1dat_evd_wait(3DAT) Direct Access Transport Library Functionsdat_evd_wait(3DAT)
2
6 dat_evd_wait - remove first event from the Event Dispatcher event queue
7
9 cc [ flag... ] file... -ldat [ library... ]
10 #include <dat/udat.h>
11 DAT_RETURN
13 dat_evd_wait(
14 IN DAT_EVD_HANDLE evd_handle,
15 IN DAT_TIMEOUT timeout,
16 IN DAT_COUNT threshold,
17 OUT DAT_EVENT *event,
18 OUT DAT_COUNT *nmore
19 )
20
23 evd_handle Handle for an instance of the Event Dispatcher.
24 timeout The duration of time, in microseconds, that the Consumer
27 is willing to wait for the event.
28 threshold The number of events that should be on the EVD queue
31 before the operation should return with DAT_SUCCESS. The
32 threshold must be at least 1.
33 event Pointer to the Consumer-allocated structure that the
36 Provider fills with the event data.
37 nmore The snapshot of the queue size at the time of the opera‐
40 tion return.
41
44 The dat_evd_wait() function removes the first event from the Event Dis‐
45 patcher event queue and fills the Consumer-allocated event structure
46 with event data. The first element in this structure provides the type
47 of the event; the rest provides the event type-specific parameters. The
48 Consumer should allocate an event structure big enough to hold any
49 event that the Event Dispatcher can deliver.
50 For all events, the Provider fills the dat_event that the Consumer
53 allocates. Therefore, for all events, all fields of dat_event are OUT
54 from the Consumer point of view. For DAT_CONNECTION_REQUEST_EVENT, the
55 Provider creates a Connection Request whose cr_handle is returned to
56 the Consumer in DAT_CR_ARRIVAL_EVENT_DATA. That object is destroyed by
57 the Provider as part of dat_cr_accept(3DAT), dat_cr_reject(3DAT), or
58 dat_cr_handoff(3DAT). The Consumer should not use cr_handle or any of
59 its parameters, including private_data, after one of these operations
60 destroys the Connection Request.
61 For DAT_CONNECTION_EVENT_ESTABLISHED for the Active side of connection
64 establishment, the Provider returns the pointer for private_data and
65 the private_data_size. For the Passive side, DAT_CONNEC‐
66 TION_EVENT_ESTABLISHED event private_data is not defined and pri‐
67 vate_data_size returns zero. The Provider is responsible for the memory
68 allocation and deallocation for private_data. The private_data is valid
69 until the Active side Consumer destroys the connected Endpoint
70 (dat_ep_free(3DAT)), or transitions the Endpoint into Unconnected state
71 so it is ready for the next connection. So, while the Endpoint is in
72 Connected, Disconnect Pending, or Disconnected state, the private_data
73 of DAT_CONNECTION_REQUEST_EVENT is still valid for Active side Con‐
74 sumers.
75 Provider must pass to the Consumer the entire Private Data that the
78 remote Consumer provided for dat_ep_connect(3DAT), dat_ep_dup_con‐
79 nect(3DAT), and dat_cr_accept(). If the Consumer provides more data
80 than the Provider and Transport can support (larger than IA Attribute
81 of max_private_data_size), DAT_INVALID_PARAMETER is returned for that
82 operation.
83 A Consumer that blocks performing a dat_evd_wait() on an Event Dis‐
86 patcher effectively takes exclusive ownership of that Event Dispatcher.
87 Any other dequeue operation (dat_evd_wait() or dat_evd_dequeue(3DAT))
88 on the Event Dispatcher is rejected with a DAT_INVALID_STATE error
89 code.
90 The CNO associated with the evd_handle() is not triggered upon event
93 arrival if there is a Consumer blocked on dat_evd_wait() on this Event
94 Dispatcher.
95 The timeout allows the Consumer to restrict the amount of time it is
98 blocked waiting for the event arrival. The value of DAT_TIMEOUT_INFI‐
99 NITE indicates that the Consumer waits indefinitely for an event
100 arrival. Consumers should use extreme caution in using this value.
101 When timeout value is reached and the number of events on the EVD queue
104 is below the threshold value, the operation fails and returns DAT_TIME‐
105 OUT_EXPIRED. In this case, no event is dequeued from the EVD and the
106 return value for the event argument is undefined. However, an nmore
107 value is returned that specifies the snapshot of the number of the
108 events on the EVD queue that is returned.
109 The threshold allows the Consumer to wait for a requested number of
112 event arrivals prior to waking the Consumer. If the value of the
113 threshold is larger than the Event Dispatcher queue length, the opera‐
114 tion fails with the return DAT_INVALID_PARAMETER. If a non-positive
115 value is specified for threshold, the operation fails and returns
116 DAT_INVALID_PARAMETER.
117 If EVD is used by an Endpoint for a DTO completion stream that is con‐
120 figured for a Consumer-controlled event Notification (DAT_COMPLE‐
121 TION_UNSIGNALLED_FLAG or DAT_COMPLETION_SOLICITED_WAIT_FLAG for Receive
122 Completion Type for Receives; DAT_COMPLETION_UNSIGNALLED_FLAG for
123 Request Completion Type for Send, RDMA Read, RDMA Write and RMR Bind),
124 the threshold value must be 1. An attempt to specify some other value
125 for threshold for this case results in DAT_INVALID_STATE.
126 The returned value of nmore indicates the number of events left on the
129 Event Dispatcher queue after the dat_evd_wait() returns. If the opera‐
130 tion return value is DAT_SUCCESS, the nmore value is at least the value
131 of (threshold -1). Notice that nmore is only a snapshot and the number
132 of events can be changed by the time the Consumer tries to dequeue
133 events with dat_evd_wait() with timeout of zero or with
134 dat_evd_dequeue().
135 For returns other than DAT_SUCCESS, DAT_TIMEOUT_EXPIRED, and DAT_INTER‐
138 RUPTED_CALL, the returned value of nmore is undefined.
139 The returned event that was posted from an Event Stream guarantees Con‐
142 sumers that all events that were posted from the same Event Stream
143 prior to the returned event were already returned to a Consumer
144 directly through a dat_evd_dequeue() or dat_evd_wait() operation.
145 If the return value is neither DAT_SUCCESS nor DAT_TIMEOUT_EXPIRED,
148 then returned values of nmore and event are undefined. If the return
149 value is DAT_TIMEOUT_EXPIRED, then the return value of event is unde‐
150 fined, but the return value of nmore is defined. If the return value is
151 DAT_SUCCESS, then the return values of nmore and event are defined.
152 If this function is called on an EVD in an unwaitable state, or if
155 dat_evd_set_unwaitable(3DAT) is called on an EVD on which a thread is
156 blocked in this function, the function returns with DAT_INVALID_STATE.
157 The ordering of events dequeued by overlapping calls to dat_evd_wait()
160 or dat_evd_dequeue() is not specified.
161
163 DAT_SUCCESS The operation was successful. An event was
164 returned to a Consumer.
165 DAT_INVALID_HANDLE The evd_handle parameter is invalid.
168 DAT_INVALID_PARAMETER The timeout or threshold parameter is invalid.
171 For example, threshold is larger than the
172 EVD's evd_min_qlen.
173 DAT_ABORT The operation was aborted because IA was
176 closed or EVD was destroyed
177 DAT_INVALID_STATE One of the parameters was invalid for this
180 operation. There is already a waiter on the
181 EVD, or the EVD is in an unwaitable state.
182 DAT_TIMEOUT_EXPIRED The operation timed out.
185 DAT_INTERRUPTED_CALL The operation was interrupted by a signal.
188
191 Consumers should be cautioned against using threshold combined with
192 infinite timeout.
193 Consumers should not mix different models for control of unblocking a
196 waiter. If the Consumer uses Notification Suppression or Solicited Wait
197 to control the Notification events for unblocking a waiter, the thresh‐
198 old must be set to 1. If the Consumer uses threshold to control when a
199 waiter is unblocked, DAT_COMPLETION_UNSIGNALLED_FLAG locally and
200 DAT_COMPLETION_SOLICITED_WAIT remotely shall not be used. By default,
201 all completions are Notification events.
202
204 See attributes(5) for descriptions of the following attributes:
205 ┌─────────────────────────────┬─────────────────────────────┐
210 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
211 ├─────────────────────────────┼─────────────────────────────┤
212 │Interface Stability │Standard: uDAPL, 1.1, 1.2 │
213 ├─────────────────────────────┼─────────────────────────────┤
214 │MT-Level │Safe │
215 └─────────────────────────────┴─────────────────────────────┘
216
218 dat_cr_accept(3DAT), dat_cr_handoff(3DAT), dat_cr_reject(3DAT),
219 dat_ep_connect(3DAT), dat_ep_dup_connect(3DAT),dat_ep_free(3DAT),
220 dat_evd_dequeue(3DAT), dat_evd_set_unwaitable(3DAT), libdat(3LIB),
221 attributes(5)
222SunOS 5.11 16 Jul 2004 dat_evd_wait(3DAT)