Direct Access Transport Library Functions datevdwait(3DAT)
NAME
datevdwait - remove first event from the Event Dispatcher
event queue
SYNOPSIS
cc [ flag... ] file... -ldat [ library... ]
#include
DATRETURN
datevdwait(
IN DATEVDHANDLE evdhandle,
IN DATIMEOUT timeout,
IN DATCOUNT threshold,
OUT DATEVENT *event,
OUT DATCOUNT *nmore
)
PARAMETERS
evdhandle 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
DATSUCES. 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 datevdwait() 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 datevent that the
Consumer allocates. Therefore, for all events, all fields of
SunOS 5.11 Last change: 16 Jul 2004 1
Direct Access Transport Library Functions datevdwait(3DAT)
datevent are OUT from the Consumer point of view. For
DATCONECTIONREQUESTEVENT, the Provider creates a Connec-
tion Request whose crhandle is returned to the Consumer in
DATCRARIVALEVENTDATA. That object is destroyed by the
Provider as part of datcraccept(3DAT),
datcrreject(3DAT), or datcrhandoff(3DAT). The Consumer
should not use crhandle or any of its parameters, including
privatedata, after one of these operations destroys the
Connection Request.
For DATCONECTIONEVENTESTABLISHED for the Active side of
connection establishment, the Provider returns the pointer
for privatedata and the privatedatasize. For the Passive
side, DATCONECTIONEVENTESTABLISHED event privatedata is
not defined and privatedatasize returns zero. The Provider
is responsible for the memory allocation and deallocation
for privatedata. The privatedata is valid until the Active
side Consumer destroys the connected Endpoint
(datepfree(3DAT)), or transitions the Endpoint into Uncon-
nected state so it is ready for the next connection. So,
while the Endpoint is in Connected, Disconnect Pending, or
Disconnected state, the privatedata of
DATCONECTIONREQUESTEVENT is still valid for Active side
Consumers.
Provider must pass to the Consumer the entire Private Data
that the remote Consumer provided for datepconnect(3DAT),
datepdupconnect(3DAT), and datcraccept(). If the Consu-
mer provides more data than the Provider and Transport can
support (larger than IA Attribute of maxprivatedatasize),
DATINVALIDPARAMETER is returned for that operation.
A Consumer that blocks performing a datevdwait() on an
Event Dispatcher effectively takes exclusive ownership of
that Event Dispatcher. Any other dequeue operation
(datevdwait() or datevddequeue(3DAT)) on the Event
Dispatcher is rejected with a DATINVALIDSTATE error code.
The CNO associated with the evdhandle() is not triggered
upon event arrival if there is a Consumer blocked on
datevdwait() 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 DATIMEOUTINFINITE indicates that the Consumer waits
indefinitely for an event arrival. Consumers should use
extreme caution in using this value.
SunOS 5.11 Last change: 16 Jul 2004 2
Direct Access Transport Library Functions datevdwait(3DAT)
When timeout value is reached and the number of events on
the EVD queue is below the threshold value, the operation
fails and returns DATIMEOUTEXPIRED. 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
DATINVALIDPARAMETER. If a non-positive value is specified
for threshold, the operation fails and returns
DATINVALIDPARAMETER.
If EVD is used by an Endpoint for a DTO completion stream
that is configured for a Consumer-controlled event Notifica-
tion (DATCOMPLETIONUNSIGNALEDFLAG or
DATCOMPLETIONSOLICITEDWAITFLAG for Receive Completion
Type for Receives; DATCOMPLETIONUNSIGNALEDFLAG 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 DATINVALIDSTATE.
The returned value of nmore indicates the number of events
left on the Event Dispatcher queue after the datevdwait()
returns. If the operation return value is DATSUCES, 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 datevdwait() with timeout of zero or with
datevddequeue().
For returns other than DATSUCES, DATIMEOUTEXPIRED, and
DATINTERUPTEDCAL, the returned value of nmore is unde-
fined.
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
datevddequeue() or datevdwait() operation.
SunOS 5.11 Last change: 16 Jul 2004 3
Direct Access Transport Library Functions datevdwait(3DAT)
If the return value is neither DATSUCES nor
DATIMEOUTEXPIRED, then returned values of nmore and event
are undefined. If the return value is DATIMEOUTEXPIRED,
then the return value of event is undefined, but the return
value of nmore is defined. If the return value is
DATSUCES, then the return values of nmore and event are
defined.
If this function is called on an EVD in an unwaitable state,
or if datevdsetunwaitable(3DAT) is called on an EVD on
which a thread is blocked in this function, the function
returns with DATINVALIDSTATE.
The ordering of events dequeued by overlapping calls to
datevdwait() or datevddequeue() is not specified.
RETURN VALUES
DATSUCES The operation was successful. An
event was returned to a Consumer.
DATINVALIDHANDLE The evdhandle parameter is
invalid.
DATINVALIDPARAMETER The timeout or threshold parameter
is invalid. For example, threshold
is larger than the EVD's
evdminqlen.
DATABORT The operation was aborted because
IA was closed or EVD was destroyed
DATINVALIDSTATE 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.
DATIMEOUTEXPIRED The operation timed out.
DATINTERUPTEDCAL The operation was interrupted by a
signal.
USAGE
SunOS 5.11 Last change: 16 Jul 2004 4
Direct Access Transport Library Functions datevdwait(3DAT)
Consumers should be cautioned against using threshold com-
bined 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, DATCOMPLETIONUNSIGNALEDFLAG locally and
DATCOMPLETIONSOLICITEDWAIT remotely shall not be used. By
default, all completions are Notification events.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard: uDAPL, 1.1, 1.2
MT-Level Safe
SEE ALSO
datcraccept(3DAT), datcrhandoff(3DAT),
datcrreject(3DAT), datepconnect(3DAT),
datepdupconnect(3DAT),datepfree(3DAT),
datevddequeue(3DAT), datevdsetunwaitable(3DAT),
libdat(3LIB), attributes(5)
SunOS 5.11 Last change: 16 Jul 2004 5
|
