man/dispatch_source_create.3

   1 .\" Copyright (c) 2008-2013 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_registration_handler
  29 .Fa "dispatch_source_t source"
  30 .Fa "void (^block)(void)"
  31 .Fc
  32 .Ft void
  33 .Fo dispatch_source_set_registration_handler_f
  34 .Fa "dispatch_source_t source"
  35 .Fa "void (*function)(void *)"
  36 .Fc
  37 .Ft void
  38 .Fo dispatch_source_set_cancel_handler
  39 .Fa "dispatch_source_t source"
  40 .Fa "void (^block)(void)"
  41 .Fc
  42 .Ft void
  43 .Fo dispatch_source_set_cancel_handler_f
  44 .Fa "dispatch_source_t source"
  45 .Fa "void (*function)(void *)"
  46 .Fc
  47 .Ft void
  48 .Fo dispatch_source_cancel
  49 .Fa "dispatch_source_t source"
  50 .Fc
  51 .Ft long
  52 .Fo dispatch_source_testcancel
  53 .Fa "dispatch_source_t source"
  54 .Fc
  55 .Ft uintptr_t
  56 .Fo dispatch_source_get_handle
  57 .Fa "dispatch_source_t source"
  58 .Fc
  59 .Ft "unsigned long"
  60 .Fo dispatch_source_get_mask
  61 .Fa "dispatch_source_t source"
  62 .Fc
  63 .Ft "unsigned long"
  64 .Fo dispatch_source_get_data
  65 .Fa "dispatch_source_t source"
  66 .Fc
  67 .Ft void
  68 .Fo dispatch_source_merge_data
  69 .Fa "dispatch_source_t source"
  70 .Fa "unsigned long data"
  71 .Fc
  72 .Ft void
  73 .Fo dispatch_source_set_timer
  74 .Fa "dispatch_source_t source"
  75 .Fa "dispatch_time_t start"
  76 .Fa "uint64_t interval"
  77 .Fa "uint64_t leeway"
  78 .Fc
  79 .Sh DESCRIPTION
  80 Dispatch event sources may be used to monitor a variety of system objects and
  81 events including file descriptors, mach ports, processes, virtual filesystem
  82 nodes, signal delivery and timers.
  83 .Pp
  84 When a state change occurs, the dispatch source will submit its event handler
  85 block to its target queue.
  86 .Pp
  87 The
  88 .Fn dispatch_source_create
  89 function creates a new dispatch source object that may be retained and released
  90 with calls to
  91 .Fn dispatch_retain
  92 and
  93 .Fn dispatch_release
  94 respectively. The
  95 .Fa queue
  96 parameter specifies the target queue of the new source object, it will
  97 be retained by the source object. Pass the
  98 .Dv DISPATCH_TARGET_QUEUE_DEFAULT
  99 constant to use the default target queue (the default priority global
 100 concurrent queue).
 101 .Pp
 102 Newly created sources are created in a suspended state. After the source has
 103 been configured by setting an event handler, cancellation handler, registration
 104 handler, context,
 105 etc., the source must be activated by a call to
 106 .Fn dispatch_resume
 107 before any events will be delivered.
 108 .Pp
 109 Dispatch sources may be one of the following types:
 110 .Bl -bullet -compact -offset indent
 111 .It
 112 DISPATCH_SOURCE_TYPE_DATA_ADD
 113 .It
 114 DISPATCH_SOURCE_TYPE_DATA_OR
 115 .It
 116 DISPATCH_SOURCE_TYPE_DATA_REPLACE
 117 .It
 118 DISPATCH_SOURCE_TYPE_MACH_SEND
 119 .It
 120 DISPATCH_SOURCE_TYPE_MACH_RECV
 121 .It
 122 DISPATCH_SOURCE_TYPE_MEMORYPRESSURE
 123 .It
 124 DISPATCH_SOURCE_TYPE_PROC
 125 .It
 126 DISPATCH_SOURCE_TYPE_READ
 127 .It
 128 DISPATCH_SOURCE_TYPE_SIGNAL
 129 .It
 130 DISPATCH_SOURCE_TYPE_TIMER
 131 .It
 132 DISPATCH_SOURCE_TYPE_VNODE
 133 .It
 134 DISPATCH_SOURCE_TYPE_WRITE
 135 .El
 136 .Pp
 137 The
 138 .Fa handle
 139 and
 140 .Fa mask
 141 arguments to
 142 .Fn dispatch_source_create
 143 and the return values of the
 144 .Fn dispatch_source_get_handle ,
 145 .Fn dispatch_source_get_mask ,
 146 and
 147 .Fn dispatch_source_get_data
 148 functions should be interpreted according to the type of the dispatch source.
 149 .Pp
 150 The
 151 .Fn dispatch_source_get_handle
 152 function
 153 returns the underlying handle to the dispatch source (i.e. file descriptor,
 154 mach port, process identifer, etc.). The result of this function may be cast
 155 directly to the underlying type.
 156 .Pp
 157 The
 158 .Fn dispatch_source_get_mask
 159 function
 160 returns the set of flags that were specified at source creation time via the
 161 .Fa mask
 162 argument.
 163 .Pp
 164 The
 165 .Fn dispatch_source_get_data
 166 function returns the currently pending data for the dispatch source.
 167 This function should only be called from within the source's event handler.
 168 The result of calling this function from any other context is undefined.
 169 .Pp
 170 The
 171 .Fn dispatch_source_merge_data
 172 function is intended for use with the
 173 .Vt DISPATCH_SOURCE_TYPE_DATA_ADD ,
 174 .Vt DISPATCH_SOURCE_TYPE_DATA_OR
 175 and
 176 .Vt DISPATCH_SOURCE_TYPE_DATA_REPLACE
 177 source types. The result of using this function with any other source type is
 178 undefined. Data merging is performed according to the source type:
 179 .Bl -tag -width "XXDISPATCH_SOURCE_TYPE_DATA_REPLACE" -compact -offset indent
 180 .It \(bu DISPATCH_SOURCE_TYPE_DATA_ADD
 181 .Vt data
 182 is atomically added to the source's data
 183 .It \(bu DISPATCH_SOURCE_TYPE_DATA_OR
 184 .Vt data
 185 is atomically bitwise ORed into the source's data
 186 .It \(bu DISPATCH_SOURCE_TYPE_DATA_REPLACE
 187 .Vt data
 188 atomically replaces the source's data.
 189 .El
 190 .Pp
 191 If the source data value resulting from the merge operation is 0, the source
 192 handler will not be invoked. This can happen if:
 193 .Bl -bullet -compact -offset indent
 194 .It
 195 the atomic addition wraps for sources of type
 196 .Vt DISPATCH_SOURCE_TYPE_DATA_ADD ,
 197 .It
 198 0 is merged for sources of type
 199 .Vt DISPATCH_SOURCE_TYPE_DATA_REPLACE .
 200 .El
 201 .Pp
 202 .Sh SOURCE EVENT HANDLERS
 203 In order to receive events from the dispatch source, an event handler should be
 204 specified via
 205 .Fn dispatch_source_set_event_handler .
 206 The event handler block is submitted to the source's target queue when the state
 207 of the underlying system handle changes, or when an event occurs. If a source
 208 is resumed with no event handler block set, events will be quietly ignored.
 209 If the event handler block is changed while the source is suspended, or from a
 210 block running on a serial queue that is the source's target queue, then the next
 211 event handler invocation will use the new block.
 212 .Pp
 213 Dispatch sources may be suspended or resumed independently of their target
 214 queues using
 215 .Fn dispatch_suspend
 216 and
 217 .Fn dispatch_resume
 218 on the dispatch source directly. The data describing events which occur while a
 219 source is suspended are coalesced and delivered once the source is resumed.
 220 .Pp
 221 The
 222 .Fa handler
 223 block
 224 need not be reentrant safe, as it is not resubmitted to the target
 225 .Fa queue
 226 until any prior invocation for that dispatch source has completed.
 227 When the handler is set, the dispatch source will perform a
 228 .Fn Block_copy
 229 on the
 230 .Fa handler
 231 block.
 232 .Pp
 233 To unset the event handler, call
 234 .Fn dispatch_source_set_event_handler_f
 235 and pass NULL as
 236 .Fa function .
 237 This unsets the event handler regardless of whether the handler
 238 was a function pointer or a block. Registration and cancellation handlers
 239 (see below) may be unset in the same way, but as noted below, a cancellation
 240 handler may be required.
 241 .Sh REGISTRATION
 242 When
 243 .Fn dispatch_resume
 244 is called on a suspended or newly created source, there may be a brief delay
 245 before the source is ready to receive events from the underlying system handle.
 246 During this delay, the event handler will not be invoked, and events will be
 247 missed.
 248 .Pp
 249 Once the dispatch source is registered with the underlying system and is ready
 250 to process all events its optional registration handler will be submitted to
 251 its target queue. This registration handler may be specified via
 252 .Fn dispatch_source_set_registration_handler .
 253 .Pp
 254 The event handler will not be called until the registration handler finishes.
 255 If the source is canceled (see below) before it is registered,
 256 its registration handler will not be called.
 257 .Pp
 258 .Sh CANCELLATION
 259 The
 260 .Fn dispatch_source_cancel
 261 function asynchronously cancels the dispatch source, preventing any further
 262 invocation of its event handler block. Cancellation does not interrupt a
 263 currently executing handler block (non-preemptive). If a source is canceled
 264 before the first time it is resumed, its event handler will never be called.
 265 (In this case, note that the source must be resumed before it can be released.)
 266 .Pp
 267 The
 268 .Fn dispatch_source_testcancel
 269 function may be used to determine whether the specified source has been
 270 canceled. A non-zero value will be returned if the source is canceled.
 271 .Pp
 272 When a dispatch source is canceled its optional cancellation handler will be
 273 submitted to its target queue. The cancellation handler may be specified via
 274 .Fn dispatch_source_set_cancel_handler .
 275 This cancellation handler is invoked only once, and only as a direct consequence
 276 of calling
 277 .Fn dispatch_source_cancel .
 278 .Pp
 279 .Em Important:
 280 a cancellation handler is required for file descriptor and mach port based
 281 sources in order to safely close the descriptor or destroy the port. Closing the
 282 descriptor or port before the cancellation handler has run may result in a race
 283 condition: if a new descriptor is allocated with the same value as the recently
 284 closed descriptor while the source's event handler is still running, the event
 285 handler may read/write data to the wrong descriptor.
 286 .Pp
 287 .Sh DISPATCH SOURCE TYPES
 288 The following section contains a summary of supported dispatch event types and
 289 the interpretation of their parameters and returned data.
 290 .Pp
 291 .Vt DISPATCH_SOURCE_TYPE_DATA_ADD ,
 292 .Vt DISPATCH_SOURCE_TYPE_DATA_OR ,
 293 .Vt DISPATCH_SOURCE_TYPE_DATA_REPLACE
 294 .Pp
 295 Sources of this type allow applications to manually trigger the source's event
 296 handler via a call to
 297 .Fn dispatch_source_merge_data .
 298 The data will be merged with the source's pending data via an atomic add or
 299 atomic bitwise OR, or direct replacement (based on the source's type), and the
 300 event handler block will be submitted to the source's target queue. The
 301 .Fa data
 302 is application defined. These sources have no
 303 .Fa handle
 304 or
 305 .Fa mask
 306 and zero should be used.
 307 .Pp
 308 .Vt DISPATCH_SOURCE_TYPE_MACH_SEND
 309 .Pp
 310 Sources of this type monitor a mach port with a send right for state changes.
 311 The
 312 .Fa handle
 313 is the mach port (mach_port_t) to monitor and the
 314 .Fa mask
 315 may be:
 316 .Bl -tag -width "XXDISPATCH_PROC_SIGNAL" -compact -offset indent
 317 .It \(bu DISPATCH_MACH_SEND_DEAD
 318 The port's corresponding receive right has been destroyed
 319 .El
 320 .Pp
 321 The data returned by
 322 .Fn dispatch_source_get_data
 323 is a bitmask that indicates which of the events in the
 324 .Fa mask
 325 were observed.  Note that because this source type will request notifications on
 326 the provided port, it should not be mixed with the use of
 327 .Fn mach_port_request_notification
 328 on the same port.
 329 .Pp
 330 .Vt DISPATCH_SOURCE_TYPE_MACH_RECV
 331 .Pp
 332 Sources of this type monitor a mach port with a receive right for state changes.
 333 The
 334 .Fa handle
 335 is the mach port (mach_port_t) to monitor and the
 336 .Fa mask
 337 is unused and should be zero.
 338 The event handler block will be submitted to the target queue when a message
 339 on the mach port is waiting to be received.
 340 .Pp
 341 .Vt DISPATCH_SOURCE_TYPE_MEMORYPRESSURE
 342 .Pp
 343 Sources of this type monitor the system memory pressure condition for state
 344 changes.  The
 345 .Fa handle
 346 is unused and should be zero. The
 347 .Fa mask
 348 may be one or more of the following:
 349 .Bl -tag -width "XXDISPATCH_MEMORYPRESSURE_CRITICAL" -compact -offset indent
 350 .It \(bu DISPATCH_MEMORYPRESSURE_NORMAL
 351 The system memory pressure condition has returned to normal.
 352 .It \(bu DISPATCH_MEMORYPRESSURE_WARN
 353 The system memory pressure condition has changed to warning.
 354 .It \(bu DISPATCH_MEMORYPRESSURE_CRITICAL
 355 The system memory pressure condition has changed to critical.
 356 .El
 357 .Pp
 358 The data returned by
 359 .Fn dispatch_source_get_data
 360 indicates which of the events in the
 361 .Fa mask
 362 were observed.
 363 .Pp
 364 Elevated memory pressure is a system-wide condition that applications
 365 registered for this source should react to by changing their future memory use
 366 behavior, e.g. by reducing cache sizes of newly initiated operations until
 367 memory pressure returns back to normal.
 368 .Pp
 369 However, applications should
 370 .Em NOT
 371 traverse and discard existing caches for past operations when the system memory
 372 pressure enters an elevated state, as that is likely to trigger VM operations
 373 that will further aggravate system memory pressure.
 374 .Pp
 375 .Vt DISPATCH_SOURCE_TYPE_PROC
 376 .Pp
 377 Sources of this type monitor processes for state changes.
 378 The
 379 .Fa handle
 380 is the process identifier (pid_t) of the process to monitor and the
 381 .Fa mask
 382 may be one or more of the following:
 383 .Bl -tag -width "XXDISPATCH_PROC_SIGNAL" -compact -offset indent
 384 .It \(bu DISPATCH_PROC_EXIT
 385 The process has exited and is available to
 386 .Xr wait 2 .
 387 .It \(bu DISPATCH_PROC_FORK
 388 The process has created one or more child processes.
 389 .It \(bu DISPATCH_PROC_EXEC
 390 The process has become another executable image via a call to
 391 .Xr execve 2
 392 or
 393 .Xr posix_spawn 2 .
 394 .It \(bu DISPATCH_PROC_SIGNAL
 395 A signal was delivered to the process.
 396 .El
 397 .Pp
 398 The data returned by
 399 .Fn dispatch_source_get_data
 400 is a bitmask that indicates which of the events in the
 401 .Fa mask
 402 were observed.
 403 .Pp
 404 .Vt DISPATCH_SOURCE_TYPE_READ
 405 .Pp
 406 Sources of this type monitor file descriptors for pending data.
 407 The
 408 .Fa handle
 409 is the file descriptor (int) to monitor and the
 410 .Fa mask
 411 is unused and should be zero.
 412 .Pp
 413 The data returned by
 414 .Fn dispatch_source_get_data
 415 is an estimated number of bytes available to be read from the descriptor. This
 416 estimate should be treated as a suggested
 417 .Em minimum
 418 read buffer size. There are no guarantees that a complete read of this size
 419 will be performed.
 420 .Pp
 421 Users of this source type are strongly encouraged to perform non-blocking I/O
 422 and handle any truncated reads or error conditions that may occur. See
 423 .Xr fcntl 2
 424 for additional information about setting the
 425 .Vt O_NONBLOCK
 426 flag on a file descriptor.
 427 .Pp
 428 .Vt DISPATCH_SOURCE_TYPE_SIGNAL
 429 .Pp
 430 Sources of this type monitor signals delivered to the current process. The
 431 .Fa handle
 432 is the signal number to monitor (int) and the
 433 .Fa mask
 434 is unused and should be zero.
 435 .Pp
 436 The data returned by
 437 .Fn dispatch_source_get_data
 438 is the number of signals received since the last invocation of the event handler
 439 block.
 440 .Pp
 441 Unlike signal handlers specified via
 442 .Fn sigaction ,
 443 the execution of the event handler block does not interrupt the current thread
 444 of execution; therefore the handler block is not limited to the use of signal
 445 safe interfaces defined in
 446 .Xr sigaction 2 .
 447 Furthermore, multiple observers of a given signal are supported; thus allowing
 448 applications and libraries to cooperate safely. However, a dispatch source
 449 .Em does not
 450 install a signal handler or otherwise alter the behavior of signal delivery.
 451 Therefore, applications must ignore or at least catch any signal that terminates
 452 a process by default. For example, near the top of
 453 .Fn main :
 454 .Bd -literal -offset ident
 455 signal(SIGTERM, SIG_IGN);
 456 .Ed
 457 .Pp
 458 .Vt DISPATCH_SOURCE_TYPE_TIMER
 459 .Pp
 460 Sources of this type periodically submit the event handler block to the target
 461 queue. The
 462 .Fa handle
 463 argument is unused and should be zero.
 464 .Pp
 465 The data returned by
 466 .Fn dispatch_source_get_data
 467 is the number of times the timer has fired since the last invocation of the
 468 event handler block.
 469 .Pp
 470 The timer parameters are configured with the
 471 .Fn dispatch_source_set_timer
 472 function. Once this function returns, any pending source data accumulated for
 473 the previous timer parameters has been cleared; the next fire of the timer will
 474 occur at
 475 .Fa start ,
 476 and every
 477 .Fa interval
 478 nanoseconds thereafter until the timer source is canceled.
 479 .Pp
 480 Any fire of the timer may be delayed by the system in order to improve power
 481 consumption and system performance. The upper limit to the allowable delay may
 482 be configured with the
 483 .Fa leeway
 484 argument, the lower limit is under the control of the system.
 485 .Pp
 486 For the initial timer fire at
 487 .Fa start ,
 488 the upper limit to the allowable delay is set to
 489 .Fa leeway
 490 nanoseconds. For the subsequent timer fires at
 491 .Fa start
 492 .Li "+ N *"
 493 .Fa interval ,
 494 the upper limit is
 495 .Li MIN(
 496 .Fa leeway ,
 497 .Fa interval
 498 .Li "/ 2 )" .
 499 .Pp
 500 The lower limit to the allowable delay may vary with process state such as
 501 visibility of application UI. If the specified timer source was created with a
 502 .Fa mask
 503 of
 504 .Vt DISPATCH_TIMER_STRICT ,
 505 the system will make a best effort to strictly observe the provided
 506 .Fa leeway
 507 value even if it is smaller than the current lower limit. Note that a minimal
 508 amount of delay is to be expected even if this flag is specified.
 509 .Pp
 510 The
 511 .Fa start
 512 argument also determines which clock will be used for the timer: If
 513 .Fa start
 514 is
 515 .Vt DISPATCH_TIME_NOW
 516 or was created with
 517 .Xr dispatch_time 3 ,
 518 the timer is based on
 519 .Fn mach_absolute_time .
 520 If
 521 .Fa start
 522 was created with
 523 .Xr dispatch_walltime 3 ,
 524 the timer is based on
 525 .Xr gettimeofday 3 .
 526 .Pp
 527 .Vt DISPATCH_SOURCE_TYPE_VNODE
 528 .Pp
 529 Sources of this type monitor the virtual filesystem nodes for state changes.
 530 The
 531 .Fa handle
 532 is a file descriptor (int) referencing the node to monitor, and
 533 the
 534 .Fa mask
 535 may be one or more of the following:
 536 .Bl -tag -width "XXDISPATCH_VNODE_ATTRIB" -compact -offset indent
 537 .It \(bu DISPATCH_VNODE_DELETE
 538 The referenced node was removed from the filesystem namespace via
 539 .Xr unlink 2 .
 540 .It \(bu DISPATCH_VNODE_WRITE
 541 A write to the referenced file occurred.
 542 .It \(bu DISPATCH_VNODE_EXTEND
 543 The referenced file was extended.
 544 .It \(bu DISPATCH_VNODE_ATTRIB
 545 The metadata attributes of the referenced node have changed.
 546 .It \(bu DISPATCH_VNODE_LINK
 547 The link count on the referenced node has changed.
 548 .It \(bu DISPATCH_VNODE_RENAME
 549 The referenced node was renamed.
 550 .It \(bu DISPATCH_VNODE_REVOKE
 551 Access to the referenced node was revoked via
 552 .Xr revoke 2
 553 or the underlying fileystem was unmounted.
 554 .It \(bu DISPATCH_VNODE_FUNLOCK
 555 The referenced file was unlocked by
 556 .Xr flock 2
 557 or
 558 .Xr close 2 .
 559 .El
 560 .Pp
 561 The data returned by
 562 .Fn dispatch_source_get_data
 563 is a bitmask that indicates which of the events in the
 564 .Fa mask
 565 were observed.
 566 .Pp
 567 .Vt DISPATCH_SOURCE_TYPE_WRITE
 568 .Pp
 569 Sources of this type monitor file descriptors for available write buffer space.
 570 The
 571 .Fa handle
 572 is the file descriptor (int) to monitor and the
 573 .Fa mask
 574 is unused and should be zero.
 575 .Pp
 576 Users of this source type are strongly encouraged to perform non-blocking I/O
 577 and handle any truncated reads or error conditions that may occur. See
 578 .Xr fcntl 2
 579 for additional information about setting the
 580 .Vt O_NONBLOCK
 581 flag on a file descriptor.
 582 .Pp
 583 .Sh SEE ALSO
 584 .Xr dispatch 3 ,
 585 .Xr dispatch_object 3 ,
 586 .Xr dispatch_queue_create 3