DAT_EVD_DEQUEUE(3DAT) Direct Access Transport Library Functions


NAME


dat_evd_dequeue - remove the first event from the Event Dispatcher event
queue

SYNOPSIS


cc [ flag... ] file... -ldat [ library... ]
#include <dat/udat.h>

DAT_RETURN
dat_evd_dequeue(
IN DAT_EVD_HANDLE evd_handle,
OUT DAT_EVENT *event
)


PARAMETERS


evd_handle
Handle for an instance of the Event Dispatcher.


event
Pointer to the Consumer-allocated structure that Provider
fills with the event data.


DESCRIPTION


The dat_evd_dequeue() function removes the first event from the Event
Dispatcher event queue and fills the Consumer allocated event 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.


For all events the Provider fills the dat_event that the Consumer
allocates. So for all events, all fields of dat_event are OUT from the
Consumer point of view. For DAT_CONNECTION_REQUEST_EVENT, the Provider
creates a Connection Request whose cr_handle is returned to the Consumer
in DAT_CR_ARRIVAL_EVENT_DATA. That object is destroyed by the Provider as
part of dat_cr_accept(3DAT), dat_cr_reject(3DAT), or
dat_cr_handoff(3DAT). The Consumer should not use cr_handle or any of its
parameters, including private_data, after one of these operations
destroys the Connection Request.


For DAT_CONNECTION_EVENT_ESTABLISHED for the Active side of connection
establishment, the Provider returns the pointer for private_data and the
private_data_size. For the Passive side, DAT_CONNECTION_EVENT_ESTABLISHED
event private_data is not defined and private_data_size returns zero. The
Provider is responsible for the memory allocation and deallocation for
private_data. The private_data is valid until the Active side Consumer
destroys the connected Endpoint (dat_ep_free(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 DAT_CONNECTION_REQUEST_EVENT is
still valid for Active side Consumers.


Provider must pass to the Consumer the entire Private Data that the
remote Consumer provided for dat_ep_connect(3DAT),
dat_ep_dup_connect(3DAT), and dat_cr_accept(). If the Consumer provides
more data than the Provider and Transport can support (larger than IA
Attribute of max_private_data_size), DAT_INVALID_PARAMETER is returned
for that operation.


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 dat_evd_dequeue() or dat_evd_wait(3DAT) operation.


The ordering of events dequeued by overlapping calls to dat_evd_wait() or
dat_evd_dequeue() is not specified.

RETURN VALUES


DAT_SUCCESS
The operation was successful. An event was returned
to a Consumer.


DAT_INVALID_HANDLE
Invalid DAT handle; evd_handle is invalid.


DAT_QUEUE_EMPTY
There are no entries on the Event Dispatcher queue.


DAT_INVALID_STATE
One of the parameters was invalid for this
operation. There is already a waiter on the EVD.


USAGE


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.


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 dat_evd_dequeue() 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.


Although calling dat_evd_dequeue() 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.


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.

ATTRIBUTES


See attributes(5) for descriptions of the following attributes:


+--------------------+---------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+---------------------------+
|Interface Stability | Standard: uDAPL, 1.1, 1.2 |
+--------------------+---------------------------+
|MT-Level | Safe |
+--------------------+---------------------------+

SEE ALSO


dat_cr_accept(3DAT), dat_cr_handoff(3DAT), dat_cr_reject(3DAT),
dat_ep_connect(3DAT), dat_ep_dup_connect(3DAT), dat_ep_free(3DAT),
dat_evd_wait(3DAT), libdat(3LIB), attributes(5)


July 16, 2004 DAT_EVD_DEQUEUE(3DAT)