'\" te
.\" This manual page is derived from the DAT/uDAPL 1.2 specification.
.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH DAT_SRQ_POST_RECV 3DAT "Jul 16, 2004"
.SH NAME
dat_srq_post_recv \- add receive buffers to shared receive queue
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <\fBdat/udat.h\fR>

DAT_RETURN
    dat_srq_post_recv (
    IN      DAT_SRQ_HANDLE      srq_handle,
    IN      DAT_COUNT           num_segments,
    IN      DAT_LMR_TRIPLET     *local_iov,
    IN      DAT_DTO_COOKIE      user_cookie
    )
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIsrq_handle\fR\fR
.ad
.RS 16n
A handle for an instance of the SRQ.
.RE

.sp
.ne 2
.na
\fB\fInum_segments\fR\fR
.ad
.RS 16n
The number of \fIlmr_triplets\fR in \fIlocal_iov\fR. Can be 0 for receiving a
zero-size message.
.RE

.sp
.ne 2
.na
\fB\fIlocal_iov\fR\fR
.ad
.RS 16n
An I/O Vector that specifies the local buffer to be filled.  Can be \fINULL\fR
for receiving a zero-size message.
.RE

.sp
.ne 2
.na
\fB\fIuser_cookie\fR\fR
.ad
.RS 16n
A user-provided cookie that is returned to the Consumer at the completion of
the Receive DTO. Can be \fINULL\fR.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdat_srq_post_recv()\fR function posts the receive buffer that can be
used for the incoming message into the \fIlocal_iov\fR by any connected EP that
uses SRQ.
.sp
.LP
The \fInum_segments\fR argument specifies the number of segments in the
\fIlocal_iov\fR. The \fIlocal_iov\fR segments are filled in the I/O Vector
order until the whole message is received. This ensures that all the front
segments of the \fIlocal_iov\fR 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.
.sp
.LP
The \fIuser_cookie\fR 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
\fIuser_cookie\fR should be unique for each DTO. The \fIuser_cookie\fR is
returned to the Consumer in the Completion event for the posted Receive.
.sp
.LP
The completion of the posted Receive is reported to the Consumer asynchronously
through a DTO Completion event based on the configuration of the EP that
dequeues the posted buffer and the specified \fIcompletion_flags\fR value for
Solicited Wait for the matching Send. If EP Recv Completion Flag is
\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR, which is the default value for SRQ EP,
then all posted Recvs will generate completions with Signal Notifications.
.sp
.LP
A Consumer should not modify the \fIlocal_iov\fR or its content until the DTO
is completed. When a Consumer does not adhere to this rule, the behavior of the
Provider and the underlying Transport is not defined. Providers that allow
Consumers to get ownership of the \fIlocal_iov\fR but not the memory it
specified back after the \fBdat_srq_post_recv()\fR returns should document this
behavior and also specify its support in Provider attributes. This behavior
allows Consumer full control of the \fIlocal_iov\fR content after
\fBdat_srq_post_recv()\fR returns. Because this behavior is not guaranteed by
all Providers, portable Consumers shall not rely on this behavior. Consumers
shall not rely on the Provider copying \fIlocal_iov\fR information.
.sp
.LP
The \fBDAT_SUCCESS\fR return of the \fBdat_srq_post_recv()\fR is at least the
equivalent of posting a Receive operation directly by native Transport.
Providers shall avoid resource allocation as part of \fBdat_srq_post_recv()\fR
to ensure that this operation is nonblocking.
.sp
.LP
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.
.sp
.LP
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 \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR value not set for it.
.sp
.LP
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 connections regardless if they share SRQ and \fIrecv_evd\fR or not.
.sp
.LP
If the reported status of the Completion DTO event corresponding to the posted
RDMA Read DTO is not \fBDAT_DTO_SUCCESS\fR, the content of the \fIlocal_iov\fR
is not defined and the \fItransfered_length\fR in the DTO Completion event is
not defined.
.sp
.LP
The operation is valid for all states of the Shared Receive Queue.
.sp
.LP
The \fBdat_srq_post_recv()\fR function is asynchronous, nonblocking, and its
thread safety is Provider-dependent.
.SH RETURN VALUES
.sp
.ne 2
.na
\fB\fBDAT_SUCCESS\fR\fR
.ad
.RS 30n
The operation was successful.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_HANDLE\fR\fR
.ad
.RS 30n
The \fIsrq_handle\fR argument is an invalid DAT handle.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
.ad
.RS 30n
The operation failed due to resource limitations.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_PARAMETER\fR\fR
.ad
.RS 30n
Invalid parameter. For example, one of the IOV segments pointed to a memory
outside its LMR.
.RE

.sp
.ne 2
.na
\fB\fBDAT_PROTECTION_VIOLATION\fR\fR
.ad
.RS 30n
Protection violation for local or remote memory access.
.sp
Protection Zone mismatch between an LMR of one of the \fIlocal_iov\fR segments
and the SRQ.
.RE

.sp
.ne 2
.na
\fB\fBDAT_PRIVILEGES_VIOLATION\fR\fR
.ad
.RS 30n
Privileges violation for local or remote memory access.  One of the LMRs used
in local_iov was either invalid or did not have the local write privileges.
.RE

.SH USAGE
.sp
.LP
For the best Recv operation performance, the Consumer should align each buffer
segment of \fIlocal_iov\fR to the Optimal Buffer Alignment attribute of the
Provider. For portable applications, the Consumer should align each buffer
segment of \fIlocal_iov\fR to the \fBDAT_OPTIMAL_ALIGNMENT\fR.
.sp
.LP
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.
.sp
.LP
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
\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR is not set. The configuration 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
\fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR 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
\fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR, the posted Recv completion will be
generated with Signal. If the Endpoint Recv Completion flag is
\fBDAT_COMPLETION_EVD_THRESHOLD_FLAG\fR, the posted Recv completion will be
generated with Signal and \fIdat_evd_wait\fR threshold value controls if the
waiter will be unblocked or not.
.sp
.LP
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
\fIrecv_evd\fR. 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.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard: uDAPL, 1.2
_
MT-Level	Unsafe
.TE

.SH SEE ALSO
.sp
.LP
\fBdat_srq_create\fR(3DAT), \fBdat_srq_free\fR(3DAT),
\fBdat_srq_query\fR(3DAT), \fBdat_srq_resize\fR(3DAT),
\fBdat_srq_set_lw\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5)