share/man/man3dat/dat_evd_wait.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_WAIT 3DAT "Jul 16, 2004"
   8 .SH NAME
   9 dat_evd_wait \- remove 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_wait(
  18     IN    DAT_EVD_HANDLE    \fIevd_handle\fR,
  19     IN    DAT_TIMEOUT       \fItimeout\fR,
  20     IN    DAT_COUNT         \fIthreshold\fR,
  21     OUT   DAT_EVENT         *\fIevent\fR,
  22     OUT   DAT_COUNT         *\fInmore\fR
  23     )
  24 .fi
  25
  26 .SH PARAMETERS
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fIevd_handle\fR\fR
  31 .ad
  32 .RS 14n
  33 Handle for an instance of the Event Dispatcher.
  34 .RE
  35
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fItimeout\fR\fR
  40 .ad
  41 .RS 14n
  42 The duration of time, in microseconds, that the Consumer is willing to wait for
  43 the event.
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIthreshold\fR\fR
  50 .ad
  51 .RS 14n
  52 The number of events that should be on the EVD queue before the operation
  53 should return with \fBDAT_SUCCESS\fR. The threshold must be at least 1.
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fIevent\fR\fR
  60 .ad
  61 .RS 14n
  62 Pointer to the Consumer-allocated structure that the Provider fills with the
  63 event data.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fInmore\fR\fR
  70 .ad
  71 .RS 14n
  72 The snapshot of the queue size at the time of the operation return.
  73 .RE
  74
  75 .SH DESCRIPTION
  76 .sp
  77 .LP
  78 The \fBdat_evd_wait()\fR function removes the first event from the Event
  79 Dispatcher event queue and fills the Consumer-allocated \fIevent\fR structure
  80 with event data. The first element in this structure provides the type of the
  81 event; the rest provides the event type-specific parameters. The Consumer
  82 should allocate an event structure big enough to hold any event that the Event
  83 Dispatcher can deliver.
  84 .sp
  85 .LP
  86 For all events, the Provider fills the \fIdat_event\fR that the Consumer
  87 allocates. Therefore, for all events, all fields of \fIdat_event\fR are OUT
  88 from the Consumer point of view. For \fBDAT_CONNECTION_REQUEST_EVENT\fR, the
  89 Provider creates a Connection Request whose \fIcr_handle\fR is returned to the
  90 Consumer in \fBDAT_CR_ARRIVAL_EVENT_DATA\fR. That object is destroyed by the
  91 Provider as part of \fBdat_cr_accept\fR(3DAT), \fBdat_cr_reject\fR(3DAT), or
  92 \fBdat_cr_handoff\fR(3DAT). The Consumer should not use \fIcr_handle\fR or any
  93 of its parameters, including \fIprivate_data\fR, after one of these operations
  94 destroys the Connection Request.
  95 .sp
  96 .LP
  97 For \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR for the Active side of connection
  98 establishment, the Provider returns the pointer for \fIprivate_data\fR and the
  99 \fIprivate_data_size\fR. For the Passive side,
 100 \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event \fIprivate_data\fR is not defined
 101 and \fIprivate_data_size\fR returns zero. The Provider is responsible for the
 102 memory allocation and deallocation for \fIprivate_data\fR. The
 103 \fIprivate_data\fR is valid until the Active side Consumer destroys the
 104 connected Endpoint (\fBdat_ep_free\fR(3DAT)), or transitions the Endpoint into
 105 Unconnected state so it is ready for the next connection. So, while the
 106 Endpoint is in Connected, Disconnect Pending, or Disconnected state, the
 107 \fIprivate_data\fR of \fBDAT_CONNECTION_REQUEST_EVENT\fR is still valid for
 108 Active side Consumers.
 109 .sp
 110 .LP
 111 Provider must pass to the Consumer the entire Private Data that the remote
 112 Consumer provided for \fBdat_ep_connect\fR(3DAT),
 113 \fBdat_ep_dup_connect\fR(3DAT), and \fBdat_cr_accept()\fR. If the Consumer
 114 provides more data than the Provider and Transport can support (larger than IA
 115 Attribute of \fImax_private_data_size\fR), \fBDAT_INVALID_PARAMETER\fR is
 116 returned for that operation.
 117 .sp
 118 .LP
 119 A Consumer that blocks performing a \fBdat_evd_wait()\fR on an Event Dispatcher
 120 effectively takes exclusive ownership of that Event Dispatcher. Any other
 121 dequeue operation (\fBdat_evd_wait()\fR or \fBdat_evd_dequeue\fR(3DAT)) on the
 122 Event Dispatcher is rejected with a \fBDAT_INVALID_STATE\fR error code.
 123 .sp
 124 .LP
 125 The CNO associated with the \fBevd_handle()\fR is not triggered upon event
 126 arrival if there is a Consumer blocked on \fBdat_evd_wait()\fR on this Event
 127 Dispatcher.
 128 .sp
 129 .LP
 130 The \fItimeout\fR allows the Consumer to restrict the amount of time it is
 131 blocked waiting for the event arrival. The value of \fBDAT_TIMEOUT_INFINITE\fR
 132 indicates that the Consumer waits indefinitely for an event arrival. Consumers
 133 should use extreme caution in using this value.
 134 .sp
 135 .LP
 136 When \fItimeout\fR value is reached and the number of events on the EVD queue
 137 is below the \fIthreshold\fR value, the operation fails and returns
 138 \fBDAT_TIMEOUT_EXPIRED\fR. In this case, no event is dequeued from the EVD and
 139 the return value for the \fIevent\fR argument is undefined. However, an
 140 \fInmore\fR value is returned that specifies the snapshot of the number of the
 141 events on the EVD queue that is returned.
 142 .sp
 143 .LP
 144 The \fIthreshold\fR allows the Consumer to wait for a requested number of event
 145 arrivals prior to waking the Consumer. If the value of the \fIthreshold\fR is
 146 larger than the Event Dispatcher queue length, the operation fails with the
 147 return \fBDAT_INVALID_PARAMETER\fR. If a non-positive value is specified for
 148 \fIthreshold\fR, the operation fails and returns \fBDAT_INVALID_PARAMETER\fR.
 149 .sp
 150 .LP
 151 If EVD is used by an Endpoint for a DTO completion stream that is configured
 152 for a Consumer-controlled event Notification
 153 (\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR or
 154 \fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR for Receive Completion Type for
 155 Receives; \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR for Request Completion Type for
 156 Send, RDMA Read, RDMA Write and RMR Bind), the \fIthreshold\fR value must be 1.
 157 An attempt to specify some other value for \fIthreshold\fR for this case
 158 results in \fBDAT_INVALID_STATE\fR.
 159 .sp
 160 .LP
 161 The returned value of \fInmore\fR indicates the number of events left on the
 162 Event Dispatcher queue after the \fBdat_evd_wait()\fR returns. If the operation
 163 return value is \fBDAT_SUCCESS\fR, the \fInmore\fR value is at least the value
 164 of (\fIthreshold\fR -1). Notice that \fInmore\fR is only a snapshot and the
 165 number of events can be changed by the time the Consumer tries to dequeue
 166 events with \fBdat_evd_wait()\fR with timeout of zero or with
 167 \fBdat_evd_dequeue()\fR.
 168 .sp
 169 .LP
 170 For returns other than \fBDAT_SUCCESS\fR, \fBDAT_TIMEOUT_EXPIRED\fR, and
 171 \fBDAT_INTERRUPTED_CALL\fR, the returned value of \fInmore\fR is undefined.
 172 .sp
 173 .LP
 174 The returned event that was posted from an Event Stream guarantees Consumers
 175 that all events that were posted from the same Event Stream prior to the
 176 returned event were already returned to a Consumer directly through a
 177 \fBdat_evd_dequeue()\fR or \fBdat_evd_wait()\fR operation.
 178 .sp
 179 .LP
 180 If the return value is neither \fBDAT_SUCCESS\fR nor \fBDAT_TIMEOUT_EXPIRED\fR,
 181 then returned values of \fInmore\fR and event are undefined. If the return
 182 value is \fBDAT_TIMEOUT_EXPIRED\fR, then the return value of event is
 183 undefined, but the return value of \fInmore\fR is defined. If the return value
 184 is \fBDAT_SUCCESS\fR, then the return values of \fInmore\fR and \fIevent\fR are
 185 defined.
 186 .sp
 187 .LP
 188 If this function is called on an EVD in an unwaitable state, or if
 189 \fBdat_evd_set_unwaitable\fR(3DAT) is called on an EVD on which a thread is
 190 blocked in this function, the function returns with \fBDAT_INVALID_STATE\fR.
 191 .sp
 192 .LP
 193 The ordering of events dequeued by overlapping calls to \fBdat_evd_wait()\fR or
 194 \fBdat_evd_dequeue()\fR is not specified.
 195 .SH RETURN VALUES
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBDAT_SUCCESS\fR\fR
 200 .ad
 201 .RS 25n
 202 The operation was successful. An event was returned to a Consumer.
 203 .RE
 204
 205 .sp
 206 .ne 2
 207 .na
 208 \fB\fBDAT_INVALID_HANDLE\fR\fR
 209 .ad
 210 .RS 25n
 211 The \fIevd_handle\fR parameter is invalid.
 212 .RE
 213
 214 .sp
 215 .ne 2
 216 .na
 217 \fB\fBDAT_INVALID_PARAMETER\fR\fR
 218 .ad
 219 .RS 25n
 220 The \fItimeout\fR or \fIthreshold\fR parameter is invalid. For example,
 221 \fIthreshold\fR is larger than the EVD's \fIevd_min_qlen\fR.
 222 .RE
 223
 224 .sp
 225 .ne 2
 226 .na
 227 \fB\fBDAT_ABORT\fR\fR
 228 .ad
 229 .RS 25n
 230 The operation was aborted because IA was closed or EVD was destroyed
 231 .RE
 232
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fBDAT_INVALID_STATE\fR\fR
 237 .ad
 238 .RS 25n
 239 One of the parameters was invalid for this operation. There is already a waiter
 240 on the EVD, or the EVD is in an unwaitable state.
 241 .RE
 242
 243 .sp
 244 .ne 2
 245 .na
 246 \fB\fBDAT_TIMEOUT_EXPIRED\fR\fR
 247 .ad
 248 .RS 25n
 249 The operation timed out.
 250 .RE
 251
 252 .sp
 253 .ne 2
 254 .na
 255 \fB\fBDAT_INTERRUPTED_CALL\fR\fR
 256 .ad
 257 .RS 25n
 258 The operation was interrupted by a signal.
 259 .RE
 260
 261 .SH USAGE
 262 .sp
 263 .LP
 264 Consumers should be cautioned against using threshold combined with infinite
 265 \fItimeout\fR.
 266 .sp
 267 .LP
 268 Consumers should not mix different models for control of unblocking a waiter.
 269 If the Consumer uses Notification Suppression or Solicited Wait to control the
 270 Notification events for unblocking a waiter, the \fIthreshold\fR must be set to
 271 1. If the Consumer uses \fIthreshold\fR  to control when a waiter is unblocked,
 272 \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR locally and
 273 \fBDAT_COMPLETION_SOLICITED_WAIT\fR remotely shall not be used. By default, all
 274 completions are Notification events.
 275 .SH ATTRIBUTES
 276 .sp
 277 .LP
 278 See \fBattributes\fR(5) for descriptions of the following attributes:
 279 .sp
 280
 281 .sp
 282 .TS
 283 box;
 284 c | c
 285 l | l .
 286 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 287 _
 288 Interface Stability     Standard: uDAPL, 1.1, 1.2
 289 _
 290 MT-Level        Safe
 291 .TE
 292
 293 .SH SEE ALSO
 294 .sp
 295 .LP
 296 \fBdat_cr_accept\fR(3DAT), \fBdat_cr_handoff\fR(3DAT),
 297 \fBdat_cr_reject\fR(3DAT), \fBdat_ep_connect\fR(3DAT),
 298 \fBdat_ep_dup_connect\fR(3DAT), \fBdat_ep_free\fR(3DAT),
 299 \fBdat_evd_dequeue\fR(3DAT), \fBdat_evd_set_unwaitable\fR(3DAT),
 300 \fBlibdat\fR(3LIB), \fBattributes\fR(5)