1dat_srq_post_recv(3DDAiTr)ect Access Transport Library Functdiaotn_ssrq_post_recv(3DAT)
2
6 dat_srq_post_recv - add receive buffers to shared receive queue
7
9 cc [ flag... ] file... -ldat [ library... ]
10 #include <dat/udat.h>
11 DAT_RETURN
13 dat_srq_post_recv (
14 IN DAT_SRQ_HANDLE srq_handle,
15 IN DAT_COUNT num_segments,
16 IN DAT_LMR_TRIPLET *local_iov,
17 IN DAT_DTO_COOKIE user_cookie
18 )
19
22 srq_handle A handle for an instance of the SRQ.
23 num_segments The number of lmr_triplets in local_iov. Can be 0 for
26 receiving a zero-size message.
27 local_iov An I/O Vector that specifies the local buffer to be
30 filled. Can be NULL for receiving a zero-size message.
31 user_cookie A user-provided cookie that is returned to the Consumer
34 at the completion of the Receive DTO. Can be NULL.
35
38 The dat_srq_post_recv() function posts the receive buffer that can be
39 used for the incoming message into the local_iov by any connected EP
40 that uses SRQ.
41 The num_segments argument specifies the number of segments in the
44 local_iov. The local_iov segments are filled in the I/O Vector order
45 until the whole message is received. This ensures that all the front
46 segments of the local_iov I/O Vector are completely filled, only one
47 segment is partially filled, if needed, and all segments that follow it
48 are not filled at all. The actual order of segment fillings is left to
49 the implementation.
50 The user_cookie argument allows Consumers to have unique identifiers
53 for each DTO. These identifiers are completely under user control and
54 are opaque to the Provider. There is no requirement on the Consumer
55 that the value user_cookie should be unique for each DTO. The
56 user_cookie is returned to the Consumer in the Completion event for the
57 posted Receive.
58 The completion of the posted Receive is reported to the Consumer asyn‐
61 chronously through a DTO Completion event based on the configuration of
62 the EP that dequeues the posted buffer and the specified comple‐
63 tion_flags value for Solicited Wait for the matching Send. If EP Recv
64 Completion Flag is DAT_COMPLETION_UNSIGNALLED_FLAG, which is the
65 default value for SRQ EP, then all posted Recvs will generate comple‐
66 tions with Signal Notifications.
67 A Consumer should not modify the local_iov or its content until the DTO
70 is completed. When a Consumer does not adhere to this rule, the behav‐
71 ior of the Provider and the underlying Transport is not defined.
72 Providers that allow Consumers to get ownership of the local_iov but
73 not the memory it specified back after the dat_srq_post_recv() returns
74 should document this behavior and also specify its support in Provider
75 attributes. This behavior allows Consumer full control of the local_iov
76 content after dat_srq_post_recv() returns. Because this behavior is not
77 guaranteed by all Providers, portable Consumers shall not rely on this
78 behavior. Consumers shall not rely on the Provider copying local_iov
79 information.
80 The DAT_SUCCESS return of the dat_srq_post_recv() is at least the
83 equivalent of posting a Receive operation directly by native Transport.
84 Providers shall avoid resource allocation as part of
85 dat_srq_post_recv() to ensure that this operation is nonblocking.
86 The completion of the Receive posted to the SRQ is equivalent to what
89 happened to the Receive posted to the Endpoint for the Endpoint that
90 dequeued the Receive buffer from the Shared Receive queue.
91 The posted Recv DTO will complete with signal, equivalently to the com‐
94 pletion of Recv posted directly to the Endpoint that dequeued the Recv
95 buffer from SRQ with DAT_COMPLETION_UNSIGNALLED_FLAG value not set for
96 it.
97 The posted Recv DTOs will complete in the order of Send postings to the
100 other endpoint of each connection whose local EP uses SRQ. There is no
101 ordering among different connections regardless if they share SRQ and
102 recv_evd or not.
103 If the reported status of the Completion DTO event corresponding to the
106 posted RDMA Read DTO is not DAT_DTO_SUCCESS, the content of the
107 local_iov is not defined and the transfered_length in the DTO Comple‐
108 tion event is not defined.
109 The operation is valid for all states of the Shared Receive Queue.
112 The dat_srq_post_recv() function is asynchronous, nonblocking, and its
115 thread safety is Provider-dependent.
116
118 DAT_SUCCESS The operation was successful.
119 DAT_INVALID_HANDLE The srq_handle argument is an invalid DAT
122 handle.
123 DAT_INSUFFICIENT_RESOURCES The operation failed due to resource lim‐
126 itations.
127 DAT_INVALID_PARAMETER Invalid parameter. For example, one of
130 the IOV segments pointed to a memory out‐
131 side its LMR.
132 DAT_PROTECTION_VIOLATION Protection violation for local or remote
135 memory access.
136 Protection Zone mismatch between an LMR
138 of one of the local_iov segments and the
139 SRQ.
140 DAT_PRIVILEGES_VIOLATION Privileges violation for local or remote
143 memory access. One of the LMRs used in
144 local_iov was either invalid or did not
145 have the local write privileges.
146
149 For the best Recv operation performance, the Consumer should align each
150 buffer segment of local_iov to the Optimal Buffer Alignment attribute
151 of the Provider. For portable applications, the Consumer should align
152 each buffer segment of local_iov to the DAT_OPTIMAL_ALIGNMENT.
153 Since any of the Endpoints that use the SRQ can dequeue the posted buf‐
156 fer from SRQ, Consumers should post a buffer large enough to handle
157 incoming message on any of these Endpoint connections.
158 The buffer posted to SRQ does not have a DTO completion flag value.
161 Posting Recv buffer to SRQ is semantically equivalent to posting to EP
162 with DAT_COMPLETION_UNSIGNALLED_FLAG is not set. The configuration of
163 the Recv Completion flag of an Endpoint that dequeues the posted buffer
164 defines how DTO completion is generated. If the Endpoint Recv Comple‐
165 tion flag is DAT_COMPLETION_SOLICITED_WAIT_FLAG then matching Send DTO
166 completion flag value for Solicited Wait determines if the completion
167 will be Signalled or not. If the Endpoint Recv Completion flag is not
168 DAT_COMPLETION_SOLICITED_WAIT_FLAG, the posted Recv completion will be
169 generated with Signal. If the Endpoint Recv Completion flag is DAT_COM‐
170 PLETION_EVD_THRESHOLD_FLAG, the posted Recv completion will be gener‐
171 ated with Signal and dat_evd_wait threshold value controls if the
172 waiter will be unblocked or not.
173 Only the Endpoint that is in Connected or Disconnect Pending states can
176 dequeue buffers from SRQ. When an Endpoint is transitioned into Discon‐
177 nected state, all the buffers that it dequeued from SRQ are queued on
178 the Endpoint recv_evd. All the buffers that the Endpoint has not com‐
179 pleted by the time of transition into Disconnected state and that have
180 not completed message reception will be flushed.
181
183 See attributes(5) for descriptions of the following attributes:
184 ┌─────────────────────────────┬─────────────────────────────┐
189 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
190 ├─────────────────────────────┼─────────────────────────────┤
191 │Interface Stability │Standard: uDAPL, 1.2 │
192 ├─────────────────────────────┼─────────────────────────────┤
193 │MT-Level │Unsafe │
194 └─────────────────────────────┴─────────────────────────────┘
195
197 dat_srq_create(3DAT), dat_srq_free(3DAT), dat_srq_query(3DAT),
198 dat_srq_resize(3DAT), dat_srq_set_lw(3DAT), libdat(3LIB), attributes(5)
199SunOS 5.11 16 Jul 2004 dat_srq_post_recv(3DAT)