1 DAT_EP_POST_RECV(3DAT) Direct Access Transport Library Functions 2 3 4 5 NAME 6 dat_ep_post_recv - receive data over the connection of the Endpoint 7 8 SYNOPSIS 9 cc [ flag... ] file... -ldat [ library... ] 10 #include <dat/udat.h> 11 12 DAT_RETURN 13 dat_ep_post_recv ( 14 IN DAT_EP_HANDLE ep_handle, 15 IN DAT_COUNT num_segments, 16 IN DAT_LMR_TRIPLET *local_iov, 17 IN DAT_DTO_COOKIE user_cookie, 18 IN DAT_COMPLETION_FLAGS completion_flags 19 ) 20 21 22 PARAMETERS 23 ep_handle 24 Handle for an instance of the Endpoint. 25 26 27 num_segments 28 Number of lmr_triplets in local_iov. Can be 0 for 29 receiving a 0 size message. 30 31 32 local_iov 33 I/O Vector that specifies the local buffer to be 34 filled. Can be NULL for receiving a 0 size message. 35 36 37 user_cookie: 38 User-provided cookie that is returned to the 39 Consumer at the completion of the Receive DTO. Can 40 be NULL. 41 42 43 completion_flags 44 Flags for posted Receive. The default 45 DAT_COMPLETION_DEFAULT_FLAG is 0x00. Other values 46 are as follows: 47 48 Notification of Completion 49 DAT_COMPLETION_UNSIGNALLED_FLAG 50 51 0x04 52 Non- 53 notification 54 completion. 55 Local 56 Endpoint must 57 be configured 58 for 59 Unsignaled 60 CompletionNotification 61 Suppression. 62 63 64 65 66 DESCRIPTION 67 The dat_ep_post_recv() function requests the receive of the data over 68 the connection of the ep_handle Endpoint of the incoming message into 69 the local_iov. 70 71 72 The num_segments parameter specifies the number of segments in the 73 local_iov. The local_iov segments are filled in the I/O Vector order 74 until the whole message is received. This ensures that all the "front" 75 segments of the local_iov I/O Vector are completely filled, only one 76 segment is partially filled, if needed, and all segments that follow it 77 are not filled at all. 78 79 80 The user_cookie allows Consumers to have unique identifiers for each 81 DTO. These identifiers are completely under user control and are 82 opaque to the Provider. There is no requirement on the Consumer that 83 the value user_cookie should be unique for each DTO. The user_cookie is 84 returned to the Consumer in the Completion event for the posted 85 Receive. 86 87 88 The completion of the posted Receive is reported to the Consumer 89 asynchronously through a DTO Completion event based on the 90 configuration of the connection for Solicited Wait and the specified 91 completion_flags value for the matching Send. The value of 92 DAT_COMPLETION _UNSIGNALLED_FLAG is only valid if the Endpoint Recv 93 Completion Flags DAT_COMPLETION_UNSIGNALLED_FLAG. Otherwise, 94 DAT_INVALID_PARAMETER is returned. 95 96 97 A Consumer must not modify the local_iov or its content until the DTO 98 is completed. When a Consumer does not adhere to this rule, the 99 behavior of the Provider and the underlying Transport is not defined. 100 Providers that allow Consumers to get ownership of the local_iov but 101 not the memory it specified back after the dat_ep_post_recv() returns 102 should document this behavior and also specify its support in Provider 103 attributes. This behavior allows Consumer full control of the local_iov 104 content after dat_ep_post_recv() returns. Because this behavior is not 105 guaranteed by all Providers, portable Consumers should not rely on this 106 behavior. Consumers should not rely on the Provider copying local_iov 107 information. 108 109 110 The DAT_SUCCESS return of the dat_ep_post_recv() is at least the 111 equivalent of posting a Receive operation directly by native Transport. 112 Providers should avoid resource allocation as part of 113 dat_ep_post_recv() to ensure that this operation is nonblocking and 114 thread safe for an UpCall. 115 116 117 If the size of an incoming message is larger than the size of the 118 local_iov, the reported status of the posted Receive DTO in the 119 corresponding Completion DTO event is DAT_DTO_LENGTH_ERROR. If the 120 reported status of the Completion DTO event corresponding to the posted 121 Receive DTO is not DAT_DTO_SUCCESS, the content of the local_iov is not 122 defined. 123 124 125 The operation is valid for all states of the Endpoint. The actual data 126 transfer does not take place until the Endpoint is in the 127 DAT_EP_STATE_CONNECTED state. The operation on the Endpoint in 128 DAT_EP_STATE_DISCONNECTED is allowed. If the operation returns 129 successfully, the posted Recv is immediately flushed to 130 recv_evd_handle. 131 132 RETURN VALUES 133 DAT_SUCCESS 134 The operation was successful. 135 136 137 DAT_INSUFFICIENT_RESOURCES 138 The operation failed due to resource 139 limitations. 140 141 142 DAT_INVALID_PARAMETER 143 Invalid parameter. For example, one of 144 the IOV segments pointed to a memory 145 outside its LMR. 146 147 148 DAT_INVALID_HANDLE 149 The ep_handle parameter is invalid. 150 151 152 DAT_PROTECTION_VIOLATION 153 Protection violation for local or remote 154 memory access. Protection Zone mismatch 155 between an LMR of one of the local_iov 156 segments and the local Endpoint. 157 158 159 DAT_PRIVILEGES_VIOLATION 160 Privileges violation for local or remote 161 memory access. One of the LMRs used in 162 local_iov was either invalid or did not 163 have the local read privileges. 164 165 166 USAGE 167 For best Recv operation performance, the Consumer should align each 168 buffer segment of local_iov to the Optimal Buffer Alignment attribute 169 of the Provider. For portable applications, the Consumer should align 170 each buffer segment of local_iov to the DAT_OPTIMAL_ALIGNMENT. 171 172 ATTRIBUTES 173 See attributes(5) for descriptions of the following attributes: 174 175 176 177 178 +--------------------+---------------------------+ 179 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 180 +--------------------+---------------------------+ 181 |Interface Stability | Standard: uDAPL, 1.1, 1.2 | 182 +--------------------+---------------------------+ 183 |MT-Level | Unsafe | 184 +--------------------+---------------------------+ 185 186 SEE ALSO 187 libdat(3LIB), attributes(5) 188 189 190 191 July 16, 2004 DAT_EP_POST_RECV(3DAT)