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