'\" 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_EVD_WAIT 3DAT "Jul 16, 2004"
.SH NAME
dat_evd_wait \- remove first event from the Event Dispatcher event queue
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <\fBdat/udat.h\fR>

DAT_RETURN
    dat_evd_wait(
    IN    DAT_EVD_HANDLE    \fIevd_handle\fR,
    IN    DAT_TIMEOUT       \fItimeout\fR,
    IN    DAT_COUNT         \fIthreshold\fR,
    OUT   DAT_EVENT         *\fIevent\fR,
    OUT   DAT_COUNT         *\fInmore\fR
    )
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIevd_handle\fR\fR
.ad
.RS 14n
Handle for an instance of the Event Dispatcher.
.RE

.sp
.ne 2
.na
\fB\fItimeout\fR\fR
.ad
.RS 14n
The duration of time, in microseconds, that the Consumer is willing to wait for
the event.
.RE

.sp
.ne 2
.na
\fB\fIthreshold\fR\fR
.ad
.RS 14n
The number of events that should be on the EVD queue before the operation
should return with \fBDAT_SUCCESS\fR. The threshold must be at least 1.
.RE

.sp
.ne 2
.na
\fB\fIevent\fR\fR
.ad
.RS 14n
Pointer to the Consumer-allocated structure that the Provider fills with the
event data.
.RE

.sp
.ne 2
.na
\fB\fInmore\fR\fR
.ad
.RS 14n
The snapshot of the queue size at the time of the operation return.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdat_evd_wait()\fR function removes the first event from the Event
Dispatcher event queue and fills the Consumer-allocated \fIevent\fR structure
with event data. The first element in this structure provides the type of the
event; the rest provides the event type-specific parameters. The Consumer
should allocate an event structure big enough to hold any event that the Event
Dispatcher can deliver.
.sp
.LP
For all events, the Provider fills the \fIdat_event\fR that the Consumer
allocates. Therefore, for all events, all fields of \fIdat_event\fR are OUT
from the Consumer point of view. For \fBDAT_CONNECTION_REQUEST_EVENT\fR, the
Provider creates a Connection Request whose \fIcr_handle\fR is returned to the
Consumer in \fBDAT_CR_ARRIVAL_EVENT_DATA\fR. That object is destroyed by the
Provider as part of \fBdat_cr_accept\fR(3DAT), \fBdat_cr_reject\fR(3DAT), or
\fBdat_cr_handoff\fR(3DAT). The Consumer should not use \fIcr_handle\fR or any
of its parameters, including \fIprivate_data\fR, after one of these operations
destroys the Connection Request.
.sp
.LP
For \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR for the Active side of connection
establishment, the Provider returns the pointer for \fIprivate_data\fR and the
\fIprivate_data_size\fR. For the Passive side,
\fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event \fIprivate_data\fR is not defined
and \fIprivate_data_size\fR returns zero. The Provider is responsible for the
memory allocation and deallocation for \fIprivate_data\fR. The
\fIprivate_data\fR is valid until the Active side Consumer destroys the
connected Endpoint (\fBdat_ep_free\fR(3DAT)), or transitions the Endpoint into
Unconnected state so it is ready for the next connection. So, while the
Endpoint is in Connected, Disconnect Pending, or Disconnected state, the
\fIprivate_data\fR of \fBDAT_CONNECTION_REQUEST_EVENT\fR is still valid for
Active side Consumers.
.sp
.LP
Provider must pass to the Consumer the entire Private Data that the remote
Consumer provided for \fBdat_ep_connect\fR(3DAT),
\fBdat_ep_dup_connect\fR(3DAT), and \fBdat_cr_accept()\fR. If the Consumer
provides more data than the Provider and Transport can support (larger than IA
Attribute of \fImax_private_data_size\fR), \fBDAT_INVALID_PARAMETER\fR is
returned for that operation.
.sp
.LP
A Consumer that blocks performing a \fBdat_evd_wait()\fR on an Event Dispatcher
effectively takes exclusive ownership of that Event Dispatcher. Any other
dequeue operation (\fBdat_evd_wait()\fR or \fBdat_evd_dequeue\fR(3DAT)) on the
Event Dispatcher is rejected with a \fBDAT_INVALID_STATE\fR error code.
.sp
.LP
The CNO associated with the \fBevd_handle()\fR is not triggered upon event
arrival if there is a Consumer blocked on \fBdat_evd_wait()\fR on this Event
Dispatcher.
.sp
.LP
The \fItimeout\fR allows the Consumer to restrict the amount of time it is
blocked waiting for the event arrival. The value of \fBDAT_TIMEOUT_INFINITE\fR
indicates that the Consumer waits indefinitely for an event arrival. Consumers
should use extreme caution in using this value.
.sp
.LP
When \fItimeout\fR value is reached and the number of events on the EVD queue
is below the \fIthreshold\fR value, the operation fails and returns
\fBDAT_TIMEOUT_EXPIRED\fR. In this case, no event is dequeued from the EVD and
the return value for the \fIevent\fR argument is undefined. However, an
\fInmore\fR value is returned that specifies the snapshot of the number of the
events on the EVD queue that is returned.
.sp
.LP
The \fIthreshold\fR allows the Consumer to wait for a requested number of event
arrivals prior to waking the Consumer. If the value of the \fIthreshold\fR is
larger than the Event Dispatcher queue length, the operation fails with the
return \fBDAT_INVALID_PARAMETER\fR. If a non-positive value is specified for
\fIthreshold\fR, the operation fails and returns \fBDAT_INVALID_PARAMETER\fR.
.sp
.LP
If EVD is used by an Endpoint for a DTO completion stream that is configured
for a Consumer-controlled event Notification
(\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR or
\fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR for Receive Completion Type for
Receives; \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR for Request Completion Type for
Send, RDMA Read, RDMA Write and RMR Bind), the \fIthreshold\fR value must be 1.
An attempt to specify some other value for \fIthreshold\fR for this case
results in \fBDAT_INVALID_STATE\fR.
.sp
.LP
The returned value of \fInmore\fR indicates the number of events left on the
Event Dispatcher queue after the \fBdat_evd_wait()\fR returns. If the operation
return value is \fBDAT_SUCCESS\fR, the \fInmore\fR value is at least the value
of (\fIthreshold\fR -1). Notice that \fInmore\fR is only a snapshot and the
number of events can be changed by the time the Consumer tries to dequeue
events with \fBdat_evd_wait()\fR with timeout of zero or with
\fBdat_evd_dequeue()\fR.
.sp
.LP
For returns other than \fBDAT_SUCCESS\fR, \fBDAT_TIMEOUT_EXPIRED\fR, and
\fBDAT_INTERRUPTED_CALL\fR, the returned value of \fInmore\fR is undefined.
.sp
.LP
The returned event that was posted from an Event Stream guarantees Consumers
that all events that were posted from the same Event Stream prior to the
returned event were already returned to a Consumer directly through a
\fBdat_evd_dequeue()\fR or \fBdat_evd_wait()\fR operation.
.sp
.LP
If the return value is neither \fBDAT_SUCCESS\fR nor \fBDAT_TIMEOUT_EXPIRED\fR,
then returned values of \fInmore\fR and event are undefined. If the return
value is \fBDAT_TIMEOUT_EXPIRED\fR, then the return value of event is
undefined, but the return value of \fInmore\fR is defined. If the return value
is \fBDAT_SUCCESS\fR, then the return values of \fInmore\fR and \fIevent\fR are
defined.
.sp
.LP
If this function is called on an EVD in an unwaitable state, or if
\fBdat_evd_set_unwaitable\fR(3DAT) is called on an EVD on which a thread is
blocked in this function, the function returns with \fBDAT_INVALID_STATE\fR.
.sp
.LP
The ordering of events dequeued by overlapping calls to \fBdat_evd_wait()\fR or
\fBdat_evd_dequeue()\fR is not specified.
.SH RETURN VALUES
.sp
.ne 2
.na
\fB\fBDAT_SUCCESS\fR\fR
.ad
.RS 25n
The operation was successful. An event was returned to a Consumer.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_HANDLE\fR\fR
.ad
.RS 25n
The \fIevd_handle\fR parameter is invalid.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_PARAMETER\fR\fR
.ad
.RS 25n
The \fItimeout\fR or \fIthreshold\fR parameter is invalid. For example,
\fIthreshold\fR is larger than the EVD's \fIevd_min_qlen\fR.
.RE

.sp
.ne 2
.na
\fB\fBDAT_ABORT\fR\fR
.ad
.RS 25n
The operation was aborted because IA was closed or EVD was destroyed
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_STATE\fR\fR
.ad
.RS 25n
One of the parameters was invalid for this operation. There is already a waiter
on the EVD, or the EVD is in an unwaitable state.
.RE

.sp
.ne 2
.na
\fB\fBDAT_TIMEOUT_EXPIRED\fR\fR
.ad
.RS 25n
The operation timed out.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INTERRUPTED_CALL\fR\fR
.ad
.RS 25n
The operation was interrupted by a signal.
.RE

.SH USAGE
.sp
.LP
Consumers should be cautioned against using threshold combined with infinite
\fItimeout\fR.
.sp
.LP
Consumers should not mix different models for control of unblocking a waiter.
If the Consumer uses Notification Suppression or Solicited Wait to control the
Notification events for unblocking a waiter, the \fIthreshold\fR must be set to
1. If the Consumer uses \fIthreshold\fR  to control when a waiter is unblocked,
\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR locally and
\fBDAT_COMPLETION_SOLICITED_WAIT\fR remotely shall not be used. By default, all
completions are Notification events.
.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.1, 1.2
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBdat_cr_accept\fR(3DAT), \fBdat_cr_handoff\fR(3DAT),
\fBdat_cr_reject\fR(3DAT), \fBdat_ep_connect\fR(3DAT),
\fBdat_ep_dup_connect\fR(3DAT), \fBdat_ep_free\fR(3DAT),
\fBdat_evd_dequeue\fR(3DAT), \fBdat_evd_set_unwaitable\fR(3DAT),
\fBlibdat\fR(3LIB), \fBattributes\fR(5)