'\" 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_DEQUEUE 3DAT "Jul 16, 2004"
.SH NAME
dat_evd_dequeue \- remove the 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_dequeue(
    IN    DAT_EVD_HANDLE    \fIevd_handle\fR,
    OUT   DAT_EVENT         *\fIevent\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\fIevent\fR\fR
.ad
.RS 14n
Pointer to the Consumer-allocated structure that Provider fills with the event
data.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdat_evd_dequeue()\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 \fIevent\fR structure big enough to hold any event that the
Event Dispatcher can deliver.
.sp
.LP
For all events the Provider fills the \fBdat_event\fR that the Consumer
allocates. So for all events, all fields of \fBdat_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 private_data 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
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(3DAT) operation.
.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 22n
The operation was successful. An event was returned to a Consumer.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_HANDLE\fR\fR
.ad
.RS 22n
Invalid DAT handle; evd_handle is invalid.
.RE

.sp
.ne 2
.na
\fB\fBDAT_QUEUE_EMPTY\fR\fR
.ad
.RS 22n
There are no entries on the Event Dispatcher queue.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_STATE\fR\fR
.ad
.RS 22n
One of the parameters was invalid for this operation. There is already a waiter
on the EVD.
.RE

.SH USAGE
.sp
.LP
No matter how many contexts attempt to dequeue from an Event Dispatcher, each
event is delivered exactly once. However, which Consumer receives which event
is not defined. The Provider is not obligated to provide the first caller the
first event unless it is the only caller. The Provider is not obligated to
ensure that the caller receiving the first event executes earlier than contexts
receiving later events.
.sp
.LP
Preservation of event ordering within an Event Stream is an important feature
of the DAT Event Model. Consumers are cautioned that overlapping or concurrent
calls to \fBdat_evd_dequeue()\fR from multiple contexts can undermine this
ordering information. After multiple contexts are involved, the Provider can
only guarantee the order that it delivers events into the EVD. The Provider
cannot guarantee that they are processed in the correct order.
.sp
.LP
Although calling \fBdat_evd_dequeue()\fR does not cause a context switch, the
Provider is under no obligation to prevent one. A context could successfully
complete a dequeue, and then reach the end of its timeslice, before returning
control to the Consumer code. Meanwhile, a context receiving a later event
could be executing.
.sp
.LP
The Event ordering is preserved when dequeueing is serialized. Potential
Consumer serialization methods include, but are not limited to, performing all
dequeueing from a single context or protecting dequeueing by way of lock or
semaphore.
.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_wait\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5)