1dat_evd_dequeue(3DATD)irect Access Transport Library Functiodnast_evd_dequeue(3DAT)
2
6 dat_evd_dequeue - remove the first event from the Event Dispatcher
7 event queue
8
10 cc [ flag... ] file... -ldat [ library... ]
11 #include <dat/udat.h>
12 DAT_RETURN
14 dat_evd_dequeue(
15 IN DAT_EVD_HANDLE evd_handle,
16 OUT DAT_EVENT *event
17 )
18
21 evd_handle Handle for an instance of the Event Dispatcher.
22 event Pointer to the Consumer-allocated structure that Provider
25 fills with the event data.
26
29 The dat_evd_dequeue() function removes the first event from the Event
30 Dispatcher event queue and fills the Consumer allocated event structure
31 with event data. The first element in this structure provides the type
32 of the event; the rest provides the event-type-specific parameters. The
33 Consumer should allocate an event structure big enough to hold any
34 event that the Event Dispatcher can deliver.
35 For all events the Provider fills the dat_event that the Consumer allo‐
38 cates. So for all events, all fields of dat_event are OUT from the Con‐
39 sumer point of view. For DAT_CONNECTION_REQUEST_EVENT, the Provider
40 creates a Connection Request whose cr_handle is returned to the Con‐
41 sumer in DAT_CR_ARRIVAL_EVENT_DATA. That object is destroyed by the
42 Provider as part of dat_cr_accept(3DAT), dat_cr_reject(3DAT), or
43 dat_cr_handoff(3DAT). The Consumer should not use cr_handle or any of
44 its parameters, including private_data, after one of these operations
45 destroys the Connection Request.
46 For DAT_CONNECTION_EVENT_ESTABLISHED for the Active side of connection
49 establishment, the Provider returns the pointer for private_data and
50 the private_data_size. For the Passive side, DAT_CONNEC‐
51 TION_EVENT_ESTABLISHED event private_data is not defined and pri‐
52 vate_data_size returns zero. The Provider is responsible for the memory
53 allocation and deallocation for private_data. The private_data is valid
54 until the Active side Consumer destroys the connected Endpoint
55 (dat_ep_free(3DAT)), or transitions the Endpoint into Unconnected state
56 so it is ready for the next connection. So while the Endpoint is in
57 Connected, Disconnect Pending, or Disconnected state, the private_data
58 of DAT_CONNECTION_REQUEST_EVENT is still valid for Active side Con‐
59 sumers.
60 Provider must pass to the Consumer the entire Private Data that the
63 remote Consumer provided for dat_ep_connect(3DAT), dat_ep_dup_con‐
64 nect(3DAT), and dat_cr_accept(). If the Consumer provides more data
65 than the Provider and Transport can support (larger than IA Attribute
66 of max_private_data_size), DAT_INVALID_PARAMETER is returned for that
67 operation.
68 The returned event that was posted from an Event Stream guarantees Con‐
71 sumers that all events that were posted from the same Event Stream
72 prior to the returned event were already returned to a Consumer
73 directly through a dat_evd_dequeue() or dat_evd_wait(3DAT) operation.
74 The ordering of events dequeued by overlapping calls to dat_evd_wait()
77 or dat_evd_dequeue() is not specified.
78
80 DAT_SUCCESS The operation was successful. An event was
81 returned to a Consumer.
82 DAT_INVALID_HANDLE Invalid DAT handle; evd_handle is invalid.
85 DAT_QUEUE_EMPTY There are no entries on the Event Dispatcher
88 queue.
89 DAT_INVALID_STATE One of the parameters was invalid for this opera‐
92 tion. There is already a waiter on the EVD.
93
96 No matter how many contexts attempt to dequeue from an Event Dis‐
97 patcher, each event is delivered exactly once. However, which Consumer
98 receives which event is not defined. The Provider is not obligated to
99 provide the first caller the first event unless it is the only caller.
100 The Provider is not obligated to ensure that the caller receiving the
101 first event executes earlier than contexts receiving later events.
102 Preservation of event ordering within an Event Stream is an important
105 feature of the DAT Event Model. Consumers are cautioned that overlap‐
106 ping or concurrent calls to dat_evd_dequeue() from multiple contexts
107 can undermine this ordering information. After multiple contexts are
108 involved, the Provider can only guarantee the order that it delivers
109 events into the EVD. The Provider cannot guarantee that they are pro‐
110 cessed in the correct order.
111 Although calling dat_evd_dequeue() does not cause a context switch, the
114 Provider is under no obligation to prevent one. A context could suc‐
115 cessfully complete a dequeue, and then reach the end of its timeslice,
116 before returning control to the Consumer code. Meanwhile, a context
117 receiving a later event could be executing.
118 The Event ordering is preserved when dequeueing is serialized. Poten‐
121 tial Consumer serialization methods include, but are not limited to,
122 performing all dequeueing from a single context or protecting dequeue‐
123 ing by way of lock or semaphore.
124
126 See attributes(5) for descriptions of the following attributes:
127 ┌─────────────────────────────┬─────────────────────────────┐
132 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
133 ├─────────────────────────────┼─────────────────────────────┤
134 │Interface Stability │Standard: uDAPL, 1.1, 1.2 │
135 ├─────────────────────────────┼─────────────────────────────┤
136 │MT-Level │Safe │
137 └─────────────────────────────┴─────────────────────────────┘
138
140 dat_cr_accept(3DAT), dat_cr_handoff(3DAT), dat_cr_reject(3DAT),
141 dat_ep_connect(3DAT), dat_ep_dup_connect(3DAT), dat_ep_free(3DAT),
142 dat_evd_wait(3DAT)libdat(3LIB), attributes(5)
143SunOS 5.11 16 Jul 2004 dat_evd_dequeue(3DAT)