usr/src/man/man3dat/dat_evd_dequeue.3dat

   1 '\" te
   2 .\" This manual page is derived from the DAT/uDAPL 1.2 specification.
   3 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH DAT_EVD_DEQUEUE 3DAT "Jul 16, 2004"
   8 .SH NAME
   9 dat_evd_dequeue \- remove the first event from the Event Dispatcher event queue
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
  14 #include <\fBdat/udat.h\fR>
  15
  16 DAT_RETURN
  17     dat_evd_dequeue(
  18     IN    DAT_EVD_HANDLE    \fIevd_handle\fR,
  19     OUT   DAT_EVENT         *\fIevent\fR
  20     )
  21 .fi
  22
  23 .SH PARAMETERS
  24 .sp
  25 .ne 2
  26 .na
  27 \fB\fIevd_handle\fR\fR
  28 .ad
  29 .RS 14n
  30 Handle for an instance of the Event Dispatcher.
  31 .RE
  32
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fIevent\fR\fR
  37 .ad
  38 .RS 14n
  39 Pointer to the Consumer-allocated structure that Provider fills with the event
  40 data.
  41 .RE
  42
  43 .SH DESCRIPTION
  44 .sp
  45 .LP
  46 The \fBdat_evd_dequeue()\fR function removes the first event from the Event
  47 Dispatcher event queue and fills the Consumer allocated \fIevent\fR structure
  48 with event data. The first element in this structure provides the type of the
  49 event; the rest provides the event-type-specific parameters. The Consumer
  50 should allocate an \fIevent\fR structure big enough to hold any event that the
  51 Event Dispatcher can deliver.
  52 .sp
  53 .LP
  54 For all events the Provider fills the \fBdat_event\fR that the Consumer
  55 allocates. So for all events, all fields of \fBdat_event\fR are OUT from the
  56 Consumer point of view. For \fBDAT_CONNECTION_REQUEST_EVENT\fR, the Provider
  57 creates a Connection Request whose \fIcr_handle\fR is returned to the Consumer
  58 in \fBDAT_CR_ARRIVAL_EVENT_DATA\fR. That object is destroyed by the Provider as
  59 part of \fBdat_cr_accept\fR(3DAT), \fBdat_cr_reject\fR(3DAT), or
  60 \fBdat_cr_handoff\fR(3DAT). The Consumer should not use \fIcr_handle\fR or any
  61 of its parameters, including \fIprivate_data\fR, after one of these operations
  62 destroys the Connection Request.
  63 .sp
  64 .LP
  65 For \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR for the Active side of connection
  66 establishment, the Provider returns the pointer for \fIprivate_data\fR and the
  67 \fIprivate_data_size\fR. For the Passive side,
  68 \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event \fIprivate_data\fR is not defined
  69 and \fIprivate_data_size\fR returns zero. The Provider is responsible for the
  70 memory allocation and deallocation for \fIprivate_data\fR. The
  71 \fIprivate_data\fR is valid until the Active side Consumer destroys the
  72 connected Endpoint (\fBdat_ep_free\fR(3DAT)), or transitions the Endpoint into
  73 Unconnected state so it is ready for the next connection. So while the Endpoint
  74 is in Connected, Disconnect Pending, or Disconnected state, the private_data of
  75 \fBDAT_CONNECTION_REQUEST_EVENT\fR is still valid for Active side Consumers.
  76 .sp
  77 .LP
  78 Provider must pass to the Consumer the entire Private Data that the remote
  79 Consumer provided for \fBdat_ep_connect\fR(3DAT),
  80 \fBdat_ep_dup_connect\fR(3DAT), and \fBdat_cr_accept()\fR. If the Consumer
  81 provides more data than the Provider and Transport can support (larger than IA
  82 Attribute of \fImax_private_data_size\fR), \fBDAT_INVALID_PARAMETER\fR is
  83 returned for that operation.
  84 .sp
  85 .LP
  86 The returned event that was posted from an Event Stream guarantees Consumers
  87 that all events that were posted from the same Event Stream prior to the
  88 returned event were already returned to a Consumer directly through a
  89 \fBdat_evd_dequeue()\fR or \fBdat_evd_wait\fR(3DAT) operation.
  90 .sp
  91 .LP
  92 The ordering of events dequeued by overlapping calls to \fBdat_evd_wait()\fR or
  93 \fBdat_evd_dequeue()\fR is not specified.
  94 .SH RETURN VALUES
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBDAT_SUCCESS\fR\fR
  99 .ad
 100 .RS 22n
 101 The operation was successful. An event was returned to a Consumer.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBDAT_INVALID_HANDLE\fR\fR
 108 .ad
 109 .RS 22n
 110 Invalid DAT handle; evd_handle is invalid.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fBDAT_QUEUE_EMPTY\fR\fR
 117 .ad
 118 .RS 22n
 119 There are no entries on the Event Dispatcher queue.
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fBDAT_INVALID_STATE\fR\fR
 126 .ad
 127 .RS 22n
 128 One of the parameters was invalid for this operation. There is already a waiter
 129 on the EVD.
 130 .RE
 131
 132 .SH USAGE
 133 .sp
 134 .LP
 135 No matter how many contexts attempt to dequeue from an Event Dispatcher, each
 136 event is delivered exactly once. However, which Consumer receives which event
 137 is not defined. The Provider is not obligated to provide the first caller the
 138 first event unless it is the only caller. The Provider is not obligated to
 139 ensure that the caller receiving the first event executes earlier than contexts
 140 receiving later events.
 141 .sp
 142 .LP
 143 Preservation of event ordering within an Event Stream is an important feature
 144 of the DAT Event Model. Consumers are cautioned that overlapping or concurrent
 145 calls to \fBdat_evd_dequeue()\fR from multiple contexts can undermine this
 146 ordering information. After multiple contexts are involved, the Provider can
 147 only guarantee the order that it delivers events into the EVD. The Provider
 148 cannot guarantee that they are processed in the correct order.
 149 .sp
 150 .LP
 151 Although calling \fBdat_evd_dequeue()\fR does not cause a context switch, the
 152 Provider is under no obligation to prevent one. A context could successfully
 153 complete a dequeue, and then reach the end of its timeslice, before returning
 154 control to the Consumer code. Meanwhile, a context receiving a later event
 155 could be executing.
 156 .sp
 157 .LP
 158 The Event ordering is preserved when dequeueing is serialized. Potential
 159 Consumer serialization methods include, but are not limited to, performing all
 160 dequeueing from a single context or protecting dequeueing by way of lock or
 161 semaphore.
 162 .SH ATTRIBUTES
 163 .sp
 164 .LP
 165 See \fBattributes\fR(5) for descriptions of the following attributes:
 166 .sp
 167
 168 .sp
 169 .TS
 170 box;
 171 c | c
 172 l | l .
 173 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 174 _
 175 Interface Stability     Standard: uDAPL, 1.1, 1.2
 176 _
 177 MT-Level        Safe
 178 .TE
 179
 180 .SH SEE ALSO
 181 .sp
 182 .LP
 183 \fBdat_cr_accept\fR(3DAT), \fBdat_cr_handoff\fR(3DAT),
 184 \fBdat_cr_reject\fR(3DAT), \fBdat_ep_connect\fR(3DAT),
 185 \fBdat_ep_dup_connect\fR(3DAT), \fBdat_ep_free\fR(3DAT),
 186 \fBdat_evd_wait\fR(3DAT)\fBlibdat\fR(3LIB), \fBattributes\fR(5)