Direct Access Transport Library Functions
datsrqpostrecv(3DAT)
NAME
datsrqpostrecv - add receive buffers to shared receive
queue
SYNOPSIS
cc [ flag... ] file... -ldat [ library... ]
#include
DATRETURN
datsrqpostrecv (
IN DATSRQHANDLE srqhandle,
IN DATCOUNT numsegments,
IN DATLMRTRIPLET *localiov,
IN DATDTOCOKIE usercookie
)
PARAMETERS
srqhandle A handle for an instance of the SRQ.
numsegments The number of lmrtriplets in localiov. Can
be 0 for receiving a zero-size message.
localiov An I/O Vector that specifies the local
buffer to be filled. Can be NUL for
receiving a zero-size message.
usercookie A user-provided cookie that is returned to
the Consumer at the completion of the
Receive DTO. Can be NUL.
DESCRIPTION
The datsrqpostrecv() function posts the receive buffer
that can be used for the incoming message into the localiov
by any connected EP that uses SRQ.
The numsegments argument specifies the number of segments
in the localiov. The localiov segments are filled in the
I/O Vector order until the whole message is received. This
ensures that all the front segments of the localiov I/O
Vector are completely filled, only one segment is partially
filled, if needed, and all segments that follow it are not
filled at all. The actual order of segment fillings is left
to the implementation.
SunOS 5.11 Last change: 16 Jul 2004 1
Direct Access Transport Library Functions
datsrqpostrecv(3DAT)
The usercookie argument allows Consumers to have unique
identifiers for each DTO. These identifiers are completely
under user control and are opaque to the Provider. There is
no requirement on the Consumer that the value usercookie
should be unique for each DTO. The usercookie is returned
to the Consumer in the Completion event for the posted
Receive.
The completion of the posted Receive is reported to the Con-
sumer asynchronously through a DTO Completion event based on
the configuration of the EP that dequeues the posted buffer
and the specified completionflags value for Solicited Wait
for the matching Send. If EP Recv Completion Flag is
DATCOMPLETIONUNSIGNALEDFLAG, which is the default value
for SRQ EP, then all posted Recvs will generate completions
with Signal Notifications.
A Consumer should not modify the localiov or its content
until the DTO is completed. When a Consumer does not adhere
to this rule, the behavior of the Provider and the underly-
ing Transport is not defined. Providers that allow Consumers
to get ownership of the localiov but not the memory it
specified back after the datsrqpostrecv() returns should
document this behavior and also specify its support in Pro-
vider attributes. This behavior allows Consumer full control
of the localiov content after datsrqpostrecv() returns.
Because this behavior is not guaranteed by all Providers,
portable Consumers shall not rely on this behavior. Consu-
mers shall not rely on the Provider copying localiov infor-
mation.
The DATSUCES return of the datsrqpostrecv() is at
least the equivalent of posting a Receive operation directly
by native Transport. Providers shall avoid resource alloca-
tion as part of datsrqpostrecv() to ensure that this
operation is nonblocking.
The completion of the Receive posted to the SRQ is
equivalent to what happened to the Receive posted to the
Endpoint for the Endpoint that dequeued the Receive buffer
from the Shared Receive queue.
The posted Recv DTO will complete with signal, equivalently
to the completion of Recv posted directly to the Endpoint
that dequeued the Recv buffer from SRQ with
DATCOMPLETIONUNSIGNALEDFLAG value not set for it.
SunOS 5.11 Last change: 16 Jul 2004 2
Direct Access Transport Library Functions
datsrqpostrecv(3DAT)
The posted Recv DTOs will complete in the order of Send
postings to the other endpoint of each connection whose
local EP uses SRQ. There is no ordering among different con-
nections regardless if they share SRQ and recvevd or not.
If the reported status of the Completion DTO event
corresponding to the posted RDMA Read DTO is not
DATDTOSUCES, the content of the localiov is not defined
and the transferedlength in the DTO Completion event is not
defined.
The operation is valid for all states of the Shared Receive
Queue.
The datsrqpostrecv() function is asynchronous, nonblock-
ing, and its thread safety is Provider-dependent.
RETURN VALUES
DATSUCES The operation was successful.
DATINVALIDHANDLE The srqhandle argument is an
invalid DAT handle.
DATINSUFICIENTRESOURCES The operation failed due to
resource limitations.
DATINVALIDPARAMETER Invalid parameter. For exam-
ple, one of the IOV segments
pointed to a memory outside
its LMR.
DATPROTECTIONVIOLATION Protection violation for local
or remote memory access.
Protection Zone mismatch
between an LMR of one of the
localiov segments and the
SRQ.
DATPRIVILEGESVIOLATION Privileges violation for local
or remote memory access. One
of the LMRs used in localiov
was either invalid or did not
SunOS 5.11 Last change: 16 Jul 2004 3
Direct Access Transport Library Functions
datsrqpostrecv(3DAT)
have the local write
privileges.
USAGE
For the best Recv operation performance, the Consumer should
align each buffer segment of localiov to the Optimal Buffer
Alignment attribute of the Provider. For portable applica-
tions, the Consumer should align each buffer segment of
localiov to the DATOPTIMALALIGNMENT.
Since any of the Endpoints that use the SRQ can dequeue the
posted buffer from SRQ, Consumers should post a buffer large
enough to handle incoming message on any of these Endpoint
connections.
The buffer posted to SRQ does not have a DTO completion flag
value. Posting Recv buffer to SRQ is semantically
equivalent to posting to EP with
DATCOMPLETIONUNSIGNALEDFLAG is not set. The configura-
tion of the Recv Completion flag of an Endpoint that
dequeues the posted buffer defines how DTO completion is
generated. If the Endpoint Recv Completion flag is
DATCOMPLETIONSOLICITEDWAITFLAG then matching Send DTO
completion flag value for Solicited Wait determines if the
completion will be Signalled or not. If the Endpoint Recv
Completion flag is not DATCOMPLETIONSOLICITEDWAITFLAG,
the posted Recv completion will be generated with Signal. If
the Endpoint Recv Completion flag is
DATCOMPLETIONEVDTHRESHOLDFLAG, the posted Recv comple-
tion will be generated with Signal and datevdwait thres-
hold value controls if the waiter will be unblocked or not.
Only the Endpoint that is in Connected or Disconnect Pending
states can dequeue buffers from SRQ. When an Endpoint is
transitioned into Disconnected state, all the buffers that
it dequeued from SRQ are queued on the Endpoint recvevd.
All the buffers that the Endpoint has not completed by the
time of transition into Disconnected state and that have not
completed message reception will be flushed.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 16 Jul 2004 4
Direct Access Transport Library Functions
datsrqpostrecv(3DAT)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard: uDAPL, 1.2
MT-Level Unsafe
SEE ALSO
datsrqcreate(3DAT), datsrqfree(3DAT),
datsrqquery(3DAT), datsrqresize(3DAT),
datsrqsetlw(3DAT), libdat(3LIB), attributes(5)
SunOS 5.11 Last change: 16 Jul 2004 5
Direct Access Transport Library Functions
datsrqpostrecv(3DAT)
SunOS 5.11 Last change: 16 Jul 2004 6
|
