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)