dispatch-1.0/man/dispatch_source_create.3

   1 .\" Copyright (c) 2008-2009 Apple Inc. All rights reserved.
   2 .Dd May 1, 2009
   3 .Dt dispatch_source_create 3
   4 .Os Darwin
   5 .Sh NAME
   6 .Nm dispatch_source_create
   7 .Nd dispatch event sources
   8 .Sh SYNOPSIS
   9 .Fd #include <dispatch/dispatch.h>
  10 .Ft dispatch_source_t
  11 .Fo dispatch_source_create
  12 .Fa "dispatch_source_type_t type"
  13 .Fa "uintptr_t handle"
  14 .Fa "unsigned long mask"
  15 .Fa "dispatch_queue_t queue"
  16 .Fc
  17 .Ft void
  18 .Fo dispatch_source_set_event_handler
  19 .Fa "dispatch_source_t source"
  20 .Fa "void (^block)(void)"
  21 .Fc
  22 .Ft void
  23 .Fo dispatch_source_set_event_handler_f
  24 .Fa "dispatch_source_t source"
  25 .Fa "void (*function)(void *)"
  26 .Fc
  27 .Ft void
  28 .Fo dispatch_source_set_cancel_handler
  29 .Fa "dispatch_source_t source"
  30 .Fa "void (^block)(void)"
  31 .Fc
  32 .Ft void
  33 .Fo dispatch_source_set_cancel_handler_f
  34 .Fa "dispatch_source_t source"
  35 .Fa "void (*function)(void *)"
  36 .Fc
  37 .Ft void
  38 .Fo dispatch_source_cancel
  39 .Fa "dispatch_source_t source"
  40 .Fc
  41 .Ft void
  42 .Fo dispatch_source_testcancel
  43 .Fa "dispatch_source_t source"
  44 .Fc
  45 .Ft uintptr_t
  46 .Fo dispatch_source_get_handle
  47 .Fa "dispatch_source_t source"
  48 .Fc
  49 .Ft "unsigned long"
  50 .Fo dispatch_source_get_mask
  51 .Fa "dispatch_source_t source"
  52 .Fc
  53 .Ft "unsigned long"
  54 .Fo dispatch_source_get_data
  55 .Fa "dispatch_source_t source"
  56 .Fc
  57 .Ft void
  58 .Fo dispatch_source_merge_data
  59 .Fa "dispatch_source_t source"
  60 .Fa "unsigned long data"
  61 .Fc
  62 .Ft void
  63 .Fo dispatch_source_set_timer
  64 .Fa "dispatch_source_t source"
  65 .Fa "dispatch_time_t start"
  66 .Fa "uint64_t interval"
  67 .Fa "uint64_t leeway"
  68 .Fc
  69 .Sh DESCRIPTION
  70 Dispatch event sources may be used to monitor a variety of system objects and
  71 events including file descriptors, mach ports, processes, virtual filesystem
  72 nodes, signal delivery and timers.
  73 .Pp
  74 When a state change occurs, the dispatch source will submit its event handler
  75 block to its target queue.
  76 .Pp
  77 The
  78 .Fn dispatch_source_create
  79 function creates a new dispatch source object that may be retained and released
  80 with calls to
  81 .Fn dispatch_retain
  82 and
  83 .Fn dispatch_release
  84 respectively. Newly created sources are created in a suspended state. After the
  85 source has been configured by setting an event handler, cancellation handler,
  86 context, etc., the source must be activated by a call to
  87 .Fn dispatch_resume
  88 before any events will be delivered.
  89 .Pp
  90 Dispatch sources may be one of the following types:
  91 .Bl -bullet -compact -offset indent
  92 .It
  93 DISPATCH_SOURCE_TYPE_DATA_ADD
  94 .It
  95 DISPATCH_SOURCE_TYPE_DATA_OR
  96 .It
  97 DISPATCH_SOURCE_TYPE_MACH_SEND
  98 .It
  99 DISPATCH_SOURCE_TYPE_MACH_RECV
 100 .It
 101 DISPATCH_SOURCE_TYPE_PROC
 102 .It
 103 DISPATCH_SOURCE_TYPE_READ
 104 .It
 105 DISPATCH_SOURCE_TYPE_SIGNAL
 106 .It
 107 DISPATCH_SOURCE_TYPE_TIMER
 108 .It
 109 DISPATCH_SOURCE_TYPE_VNODE
 110 .It
 111 DISPATCH_SOURCE_TYPE_WRITE
 112 .El
 113 .Pp
 114 The
 115 .Fa handle
 116 and
 117 .Fa mask
 118 arguments to
 119 .Fn dispatch_source_create
 120 and the return values of the
 121 .Fn dispatch_source_get_handle ,
 122 .Fn dispatch_source_get_mask ,
 123 and
 124 .Fn dispatch_source_get_data
 125 functions should be interpreted according to the type of the dispatch source.
 126 .Pp
 127 The
 128 .Fn dispatch_source_get_handle
 129 function
 130 returns the underlying handle to the dispatch source (i.e. file descriptor,
 131 mach port, process identifer, etc.). The result of this function may be cast
 132 directly to the underlying type.
 133 .Pp
 134 The
 135 .Fn dispatch_source_get_mask
 136 function
 137 returns the set of flags that were specified at source creation time via the
 138 .Fa mask
 139 argument.
 140 .Pp
 141 The
 142 .Fn dispatch_source_get_data
 143 function returns the currently pending data for the dispatch source.
 144 This function should only be called from within the source's event handler.
 145 The result of calling this function from any other context is undefined.
 146 .Pp
 147 The
 148 .Fn dispatch_source_merge_data
 149 function is intended for use with the
 150 .Vt DISPATCH_SOURCE_TYPE_DATA_ADD
 151 and
 152 .Vt DISPATCH_SOURCE_TYPE_DATA_OR
 153 source types. The result of using this function with any other source type is
 154 undefined. Calling this function will atomically add or logical OR the data
 155 into the source's data, and trigger the delivery of the source's event handler.
 156 .Pp
 157 .Sh SOURCE EVENT HANDLERS
 158 In order to receive events from the dispatch source, an event handler should be
 159 specified via
 160 .Fn dispatch_source_set_event_handler .
 161 The event handler block is submitted to the source's target queue when the state
 162 of the underlying system handle changes, or when an event occurs.
 163 .Pp
 164 Dispatch sources may be suspended or resumed independently of their target
 165 queues using
 166 .Fn dispatch_suspend
 167 and
 168 .Fn dispatch_resume
 169 on the dispatch source directly. The data describing events which occur while a
 170 source is suspended are coalesced and delivered once the source is resumed.
 171 .Pp
 172 The
 173 .Fa handler
 174 block
 175 need not be reentrant safe, as it is not resubmitted to the target
 176 .Fa queue
 177 until any prior invocation for that dispatch source has completed.
 178 When the handler is set, the dispatch source will perform a
 179 .Fn Block_copy
 180 on the
 181 .Fa handler
 182 block.
 183 .Pp
 184 .Sh CANCELLATION
 185 The
 186 .Fn dispatch_source_cancel
 187 function asynchronously cancels the dispatch source, preventing any further
 188 invocation of its event handler block. Cancellation does not interrupt a
 189 currently executing handler block (non-preemptive).
 190 .Pp
 191 The
 192 .Fn dispatch_source_testcancel
 193 function may be used to determine whether the specified source has been
 194 canceled. A non-zero value will be returned if the source is canceled.
 195 .Pp
 196 When a dispatch source is canceled its optional cancellation handler will be
 197 submitted to its target queue. The cancellation handler may be specified via
 198 .Fn dispatch_source_set_cancel_handler .
 199 This cancellation handler is invoked only once, and only as a direct consequence
 200 of calling
 201 .Fn dispatch_source_cancel .
 202 .Pp
 203 .Em Important:
 204 a cancellation handler is required for file descriptor and mach port based
 205 sources in order to safely close the descriptor or destroy the port. Closing the
 206 descriptor or port before the cancellation handler has run may result in a race
 207 condition: if a new descriptor is allocated with the same value as the recently
 208 closed descriptor while the source's event handler is still running, the event
 209 handler may read/write data to the wrong descriptor.
 210 .Pp
 211 .Sh DISPATCH SOURCE TYPES
 212 The following section contains a summary of supported dispatch event types and
 213 the interpretation of their parameters and returned data.
 214 .Pp
 215 .Vt DISPATCH_SOURCE_TYPE_DATA_ADD ,
 216 .Vt DISPATCH_SOURCE_TYPE_DATA_OR
 217 .Pp
 218 Sources of this type allow applications to manually trigger the source's event
 219 handler via a call to
 220 .Fn dispatch_source_merge_data .
 221 The data will be merged with the source's pending data via an atomic add or
 222 logic OR (based on the source's type), and the event handler block will be
 223 submitted to the source's target queue. The
 224 .Fa data
 225 is application defined. These sources have no
 226 .Fa handle
 227 or
 228 .Fa mask
 229 and zero should be used.
 230 .Pp
 231 .Vt DISPATCH_SOURCE_TYPE_MACH_SEND
 232 .Pp
 233 Sources of this type monitor a mach port with a send right for state changes.
 234 The
 235 .Fa handle
 236 is the mach port (mach_port_t) to monitor and the
 237 .Fa mask
 238 may be:
 239 .Bl -tag -width "XXDISPATCH_PROC_SIGNAL" -compact -offset indent
 240 .It \(bu DISPATCH_MACH_SEND_DEAD
 241 The port's corresponding receive right has been destroyed
 242 .El
 243 .Pp
 244 The data returned by
 245 .Fn dispatch_source_get_data
 246 indicates which of the events in the
 247 .Fa mask
 248 were observed.
 249 .Pp
 250 .Vt DISPATCH_SOURCE_TYPE_MACH_RECV
 251 .Pp
 252 Sources of this type monitor a mach port with a receive right for state changes.
 253 The
 254 .Fa handle
 255 is the mach port (mach_port_t) to monitor and the
 256 .Fa mask
 257 is unused and should be zero.
 258 The event handler block will be submitted to the target queue when a message
 259 on the mach port is waiting to be received.
 260 .Pp
 261 .Vt DISPATCH_SOURCE_TYPE_PROC
 262 .Pp
 263 Sources of this type monitor processes for state changes.
 264 The
 265 .Fa handle
 266 is the process identifier (pid_t) of the process to monitor and the
 267 .Fa mask
 268 may be one or more of the following:
 269 .Bl -tag -width "XXDISPATCH_PROC_SIGNAL" -compact -offset indent
 270 .It \(bu DISPATCH_PROC_EXIT
 271 The process has exited and is available to
 272 .Xr wait 2 .
 273 .It \(bu DISPATCH_PROC_FORK
 274 The process has created one or more child processes.
 275 .It \(bu DISPATCH_PROC_EXEC
 276 The process has become another executable image via a call to
 277 .Xr execve 2
 278 or
 279 .Xr posix_spawn 2 .
 280 .It \(bu  DISPATCH_PROC_REAP
 281 The process status has been collected by its parent process via
 282 .Xr wait 2 .
 283 .It \(bu DISPATCH_PROC_SIGNAL
 284 A signal was delivered to the process.
 285 .El
 286 .Pp
 287 The data returned by
 288 .Fn dispatch_source_get_data
 289 indicates which of the events in the
 290 .Fa mask
 291 were observed.
 292 .Pp
 293 .Vt DISPATCH_SOURCE_TYPE_READ
 294 .Pp
 295 Sources of this type monitor file descriptors for pending data.
 296 The
 297 .Fa handle
 298 is the file descriptor (int) to monitor and the
 299 .Fa mask
 300 is unused and should be zero.
 301 .Pp
 302 The data returned by
 303 .Fn dispatch_source_get_data
 304 is an estimated number of bytes available to be read from the descriptor. This
 305 estimate should be treated as a suggested
 306 .Em minimum
 307 read buffer size. There are no guarantees that a complete read of this size
 308 will be performed.
 309 .Pp
 310 Users of this source type are strongly encouraged to perform non-blocking I/O
 311 and handle any truncated reads or error conditions that may occur. See
 312 .Xr fcntl 2
 313 for additional information about setting the
 314 .Vt O_NONBLOCK
 315 flag on a file descriptor.
 316 .Pp
 317 .Vt DISPATCH_SOURCE_TYPE_SIGNAL
 318 .Pp
 319 Sources of this type monitor signals delivered to the current process. The
 320 .Fa handle
 321 is the signal number to monitor (int) and the
 322 .Fa mask
 323 is unused and should be zero.
 324 .Pp
 325 The data returned by
 326 .Fn dispatch_source_get_data
 327 is the number of signals received since the last invocation of the event handler
 328 block.
 329 .Pp
 330 Unlike signal handlers specified via
 331 .Fn sigaction ,
 332 the execution of the event handler block does not interrupt the current thread
 333 of execution; therefore the handler block is not limited to the use of signal
 334 safe interfaces defined in
 335 .Xr sigaction 2 .
 336 Furthermore, multiple observers of a given signal are supported; thus allowing
 337 applications and libraries to cooperate safely. However, a dispatch source
 338 .Em does not
 339 install a signal handler or otherwise alter the behavior of signal delivery.
 340 Therefore, applications must ignore or at least catch any signal that terminates
 341 a process by default. For example, near the top of
 342 .Fn main :
 343 .Bd -literal -offset ident
 344 signal(SIGTERM, SIG_IGN);
 345 .Ed
 346 .Pp
 347 .Vt DISPATCH_SOURCE_TYPE_TIMER
 348 .Pp
 349 Sources of this type periodically submit the event handler block to the target
 350 queue on an interval specified by
 351 .Fn dispatch_source_set_timer .
 352 The
 353 .Fa handle
 354 and
 355 .Fa mask
 356 arguments are unused and should be zero.
 357 .Pp
 358 A best effort attempt is made to submit the event handler block to the target
 359 queue at the specified time; however, actual invocation may occur at a later
 360 time.
 361 .Pp
 362 The data returned by
 363 .Fn dispatch_source_get_data
 364 is the number of times the timer has fired since the last invocation of the
 365 event handler block.
 366 .Pp
 367 The function
 368 .Fn dispatch_source_set_timer
 369 takes as an argument the
 370 .Fa start
 371 time of the timer (initial fire time) represented as a
 372 .Vt dispatch_time_t .
 373 The timer dispatch source will use the same clock as the function used to
 374 create this value. (See
 375 .Xr dispatch_time 3
 376 for more information.) The
 377 .Fa interval ,
 378 in nanoseconds, specifies the period at which the timer should repeat. All
 379 timers will repeat indefinitely until
 380 .Fn dispatch_source_cancel
 381 is called. The
 382 .Fa leeway ,
 383 in nanoseconds, is a hint to the system that it may defer the timer in order to
 384 align with other system activity for improved system performance or reduced
 385 power consumption. (For example, an application might perform a periodic task
 386 every 5 minutes with a leeway of up to 30 seconds.) Note that some latency is
 387 to be expected for all timers even when a value of zero is used.
 388 .Pp
 389 .Em Note :
 390 Under the C language, untyped numbers default to the
 391 .Vt int
 392 type. This can lead to truncation bugs when arithmetic operations with other
 393 numbers are expected to generate a
 394 .Vt uint64_t
 395 sized result. When in doubt, use
 396 .Vt ull
 397 as a suffix. For example:
 398 .Bd -literal -offset indent
 399 3ull * NSEC_PER_SEC
 400 .Ed
 401 .Pp
 402 .Vt DISPATCH_SOURCE_TYPE_VNODE
 403 .Pp
 404 Sources of this type monitor the virtual filesystem nodes for state changes.
 405 The
 406 .Fa handle
 407 is a file descriptor (int) referencing the node to monitor, and
 408 the
 409 .Fa mask
 410 may be one or more of the following:
 411 .Bl -tag -width "XXDISPATCH_VNODE_ATTRIB" -compact -offset indent
 412 .It \(bu DISPATCH_VNODE_DELETE
 413 The referenced node was removed from the filesystem namespace via
 414 .Xr unlink 2 .
 415 .It \(bu DISPATCH_VNODE_WRITE
 416 A write to the referenced file occurred
 417 .It \(bu DISPATCH_VNODE_EXTEND
 418 The referenced file was extended
 419 .It \(bu DISPATCH_VNODE_ATTRIB
 420 The metadata attributes of the referenced node have changed
 421 .It \(bu DISPATCH_VNODE_LINK
 422 The link count on the referenced node has changed
 423 .It \(bu DISPATCH_VNODE_RENAME
 424 The referenced node was renamed
 425 .It \(bu DISPATCH_VNODE_REVOKE
 426 Access to the referenced node was revoked via
 427 .Xr revoke 2
 428 or the underlying fileystem was unmounted.
 429 .El
 430 .Pp
 431 The data returned by
 432 .Fn dispatch_source_get_data
 433 indicates which of the events in the
 434 .Fa mask
 435 were observed.
 436 .Pp
 437 .Vt DISPATCH_SOURCE_TYPE_WRITE
 438 .Pp
 439 Sources of this type monitor file descriptors for available write buffer space.
 440 The
 441 .Fa handle
 442 is the file descriptor (int) to monitor and the
 443 .Fa mask
 444 is unused and should be zero.
 445 .Pp
 446 Users of this source type are strongly encouraged to perform non-blocking I/O
 447 and handle any truncated reads or error conditions that may occur. See
 448 .Xr fcntl 2
 449 for additional information about setting the
 450 .Vt O_NONBLOCK
 451 flag on a file descriptor.
 452 .Pp
 453 .Sh SEE ALSO
 454 .Xr dispatch 3 ,
 455 .Xr dispatch_object 3 ,
 456 .Xr dispatch_queue_create 3