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]
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 )
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.
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.
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.
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.
See attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| Interface Stability | Standard: uDAPL, 1.1, 1.2 |
| MT-Level | Safe |
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_dequeue(3DAT), dat_evd_set_unwaitable(3DAT), libdat(3LIB), attributes(5)