Tribblix: manual page: dat_evd

DAT_EVD_WAIT(3DAT) Direct Access Transport Library Functions

NAME

dat_evd_wait - remove first event from the Event Dispatcher event
queue

SYNOPSIS

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

DAT_RETURN
dat_evd_wait(
IN DAT_EVD_HANDLE evd_handle,
IN DAT_TIMEOUT timeout,
IN DAT_COUNT threshold,
OUT DAT_EVENT *event,
OUT DAT_COUNT *nmore
)

PARAMETERS

evd_handle
Handle for an instance of the Event Dispatcher.

timeout
The duration of time, in microseconds, that the
Consumer is willing to wait for the event.

threshold
The number of events that should be on the EVD queue
before the operation should return with DAT_SUCCESS.
The threshold must be at least 1.

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

nmore
The snapshot of the queue size at the time of the
operation return.

DESCRIPTION

The dat_evd_wait() 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. Therefore, 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.

A Consumer that blocks performing a dat_evd_wait() on an Event
Dispatcher effectively takes exclusive ownership of that Event
Dispatcher. Any other dequeue operation (dat_evd_wait() or
dat_evd_dequeue(3DAT)) on the Event Dispatcher is rejected with a
DAT_INVALID_STATE error code.

The CNO associated with the evd_handle() is not triggered upon event
arrival if there is a Consumer blocked on dat_evd_wait() on this
Event Dispatcher.

The timeout allows the Consumer to restrict the amount of time it is
blocked waiting for the event arrival. The value of
DAT_TIMEOUT_INFINITE indicates that the Consumer waits indefinitely
for an event arrival. Consumers should use extreme caution in using
this value.

When timeout value is reached and the number of events on the EVD
queue is below the threshold value, the operation fails and returns
DAT_TIMEOUT_EXPIRED. In this case, no event is dequeued from the EVD
and the return value for the event argument is undefined. However, an
nmore value is returned that specifies the snapshot of the number of
the events on the EVD queue that is returned.

The threshold allows the Consumer to wait for a requested number of
event arrivals prior to waking the Consumer. If the value of the
threshold is larger than the Event Dispatcher queue length, the
operation fails with the return DAT_INVALID_PARAMETER. If a non-
positive value is specified for threshold, the operation fails and
returns DAT_INVALID_PARAMETER.

If EVD is used by an Endpoint for a DTO completion stream that is
configured for a Consumer-controlled event Notification
(DAT_COMPLETION_UNSIGNALLED_FLAG or
DAT_COMPLETION_SOLICITED_WAIT_FLAG for Receive Completion Type for
Receives; DAT_COMPLETION_UNSIGNALLED_FLAG for Request Completion Type
for Send, RDMA Read, RDMA Write and RMR Bind), the threshold value
must be 1. An attempt to specify some other value for threshold for
this case results in DAT_INVALID_STATE.

The returned value of nmore indicates the number of events left on
the Event Dispatcher queue after the dat_evd_wait() returns. If the
operation return value is DAT_SUCCESS, the nmore value is at least
the value of (threshold -1). Notice that nmore is only a snapshot and
the number of events can be changed by the time the Consumer tries to
dequeue events with dat_evd_wait() with timeout of zero or with
dat_evd_dequeue().

For returns other than DAT_SUCCESS, DAT_TIMEOUT_EXPIRED, and
DAT_INTERRUPTED_CALL, the returned value of nmore is undefined.

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

If the return value is neither DAT_SUCCESS nor DAT_TIMEOUT_EXPIRED,
then returned values of nmore and event are undefined. If the return
value is DAT_TIMEOUT_EXPIRED, then the return value of event is
undefined, but the return value of nmore is defined. If the return
value is DAT_SUCCESS, then the return values of nmore and event are
defined.

If this function is called on an EVD in an unwaitable state, or if
dat_evd_set_unwaitable(3DAT) is called on an EVD on which a thread is
blocked in this function, the function returns with
DAT_INVALID_STATE.

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
The evd_handle parameter is invalid.

DAT_INVALID_PARAMETER
The timeout or threshold parameter is
invalid. For example, threshold is larger
than the EVD's evd_min_qlen.

DAT_ABORT
The operation was aborted because IA was
closed or EVD was destroyed

DAT_INVALID_STATE
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.

DAT_TIMEOUT_EXPIRED
The operation timed out.

DAT_INTERRUPTED_CALL
The operation was interrupted by a signal.

USAGE

Consumers should be cautioned against using threshold combined with
infinite timeout.

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
threshold must be set to 1. If the Consumer uses threshold to
control when a waiter is unblocked, DAT_COMPLETION_UNSIGNALLED_FLAG
locally and DAT_COMPLETION_SOLICITED_WAIT remotely shall not be used.
By default, all completions are Notification events.

ATTRIBUTES