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 logic OR (based on the source's type), and the event handler block will be
 275 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 indicates which of the events in the
 299 .Fa mask
 300 were observed.  Note that because this source type will request notifications on the provided port, it should not be mixed with the use of
 301 .Fn mach_port_request_notification
 302 on the same port.
 303 .Pp
 304 .Vt DISPATCH_SOURCE_TYPE_MACH_RECV
 305 .Pp
 306 Sources of this type monitor a mach port with a receive right for state changes.
 307 The
 308 .Fa handle
 309 is the mach port (mach_port_t) to monitor and the
 310 .Fa mask
 311 is unused and should be zero.
 312 The event handler block will be submitted to the target queue when a message
 313 on the mach port is waiting to be received.
 314 .Pp
 315 .Vt DISPATCH_SOURCE_TYPE_MEMORYPRESSURE
 316 .Pp
 317 Sources of this type monitor the system memory pressure condition for state changes.
 318 The
 319 .Fa handle
 320 is unused and should be zero. The
 321 .Fa mask
 322 may be one or more of the following:
 323 .Bl -tag -width "XXDISPATCH_MEMORYPRESSURE_CRITICAL" -compact -offset indent
 324 .It \(bu DISPATCH_MEMORYPRESSURE_NORMAL
 325 The system memory pressure condition has returned to normal.
 326 .It \(bu DISPATCH_MEMORYPRESSURE_WARN
 327 The system memory pressure condition has changed to warning.
 328 .It \(bu DISPATCH_MEMORYPRESSURE_CRITICAL
 329 The system memory pressure condition has changed to critical.
 330 .El
 331 .Pp
 332 The data returned by
 333 .Fn dispatch_source_get_data
 334 indicates which of the events in the
 335 .Fa mask
 336 were observed.
 337 .Pp
 338 Elevated memory pressure is a system-wide condition that applications
 339 registered for this source should react to by changing their future memory use
 340 behavior, e.g. by reducing cache sizes of newly initiated operations until
 341 memory pressure returns back to normal.
 342 .Pp
 343 However, applications should
 344 .Em NOT
 345 traverse and discard existing caches for past operations when the system memory
 346 pressure enters an elevated state, as that is likely to trigger VM operations
 347 that will further aggravate system memory pressure.
 348 .Pp
 349 .Vt DISPATCH_SOURCE_TYPE_PROC
 350 .Pp
 351 Sources of this type monitor processes for state changes.
 352 The
 353 .Fa handle
 354 is the process identifier (pid_t) of the process to monitor and the
 355 .Fa mask
 356 may be one or more of the following:
 357 .Bl -tag -width "XXDISPATCH_PROC_SIGNAL" -compact -offset indent
 358 .It \(bu DISPATCH_PROC_EXIT
 359 The process has exited and is available to
 360 .Xr wait 2 .
 361 .It \(bu DISPATCH_PROC_FORK
 362 The process has created one or more child processes.
 363 .It \(bu DISPATCH_PROC_EXEC
 364 The process has become another executable image via a call to
 365 .Xr execve 2
 366 or
 367 .Xr posix_spawn 2 .
 368 .It \(bu DISPATCH_PROC_SIGNAL
 369 A signal was delivered to the process.
 370 .El
 371 .Pp
 372 The data returned by
 373 .Fn dispatch_source_get_data
 374 indicates which of the events in the
 375 .Fa mask
 376 were observed.
 377 .Pp
 378 .Vt DISPATCH_SOURCE_TYPE_READ
 379 .Pp
 380 Sources of this type monitor file descriptors for pending data.
 381 The
 382 .Fa handle
 383 is the file descriptor (int) to monitor and the
 384 .Fa mask
 385 is unused and should be zero.
 386 .Pp
 387 The data returned by
 388 .Fn dispatch_source_get_data
 389 is an estimated number of bytes available to be read from the descriptor. This
 390 estimate should be treated as a suggested
 391 .Em minimum
 392 read buffer size. There are no guarantees that a complete read of this size
 393 will be performed.
 394 .Pp
 395 Users of this source type are strongly encouraged to perform non-blocking I/O
 396 and handle any truncated reads or error conditions that may occur. See
 397 .Xr fcntl 2
 398 for additional information about setting the
 399 .Vt O_NONBLOCK
 400 flag on a file descriptor.
 401 .Pp
 402 .Vt DISPATCH_SOURCE_TYPE_SIGNAL
 403 .Pp
 404 Sources of this type monitor signals delivered to the current process. The
 405 .Fa handle
 406 is the signal number to monitor (int) and the
 407 .Fa mask
 408 is unused and should be zero.
 409 .Pp
 410 The data returned by
 411 .Fn dispatch_source_get_data
 412 is the number of signals received since the last invocation of the event handler
 413 block.
 414 .Pp
 415 Unlike signal handlers specified via
 416 .Fn sigaction ,
 417 the execution of the event handler block does not interrupt the current thread
 418 of execution; therefore the handler block is not limited to the use of signal
 419 safe interfaces defined in
 420 .Xr sigaction 2 .
 421 Furthermore, multiple observers of a given signal are supported; thus allowing
 422 applications and libraries to cooperate safely. However, a dispatch source
 423 .Em does not
 424 install a signal handler or otherwise alter the behavior of signal delivery.
 425 Therefore, applications must ignore or at least catch any signal that terminates
 426 a process by default. For example, near the top of
 427 .Fn main :
 428 .Bd -literal -offset ident
 429 signal(SIGTERM, SIG_IGN);
 430 .Ed
 431 .Pp
 432 .Vt DISPATCH_SOURCE_TYPE_TIMER
 433 .Pp
 434 Sources of this type periodically submit the event handler block to the target
 435 queue. The
 436 .Fa handle
 437 argument is unused and should be zero.
 438 .Pp
 439 The data returned by
 440 .Fn dispatch_source_get_data
 441 is the number of times the timer has fired since the last invocation of the
 442 event handler block.
 443 .Pp
 444 The timer parameters are configured with the
 445 .Fn dispatch_source_set_timer
 446 function. Once this function returns, any pending source data accumulated for
 447 the previous timer parameters has been cleared; the next fire of the timer will
 448 occur at
 449 .Fa start ,
 450 and every
 451 .Fa interval
 452 nanoseconds thereafter until the timer source is canceled.
 453 .Pp
 454 Any fire of the timer may be delayed by the system in order to improve power
 455 consumption and system performance. The upper limit to the allowable delay may
 456 be configured with the
 457 .Fa leeway
 458 argument, the lower limit is under the control of the system.
 459 .Pp
 460 For the initial timer fire at
 461 .Fa start ,
 462 the upper limit to the allowable delay is set to
 463 .Fa leeway
 464 nanoseconds. For the subsequent timer fires at
 465 .Fa start
 466 .Li "+ N *"
 467 .Fa interval ,
 468 the upper limit is
 469 .Li MIN(
 470 .Fa leeway ,
 471 .Fa interval
 472 .Li "/ 2 )" .
 473 .Pp
 474 The lower limit to the allowable delay may vary with process state such as
 475 visibility of application UI. If the specified timer source was created with a
 476 .Fa mask
 477 of
 478 .Vt DISPATCH_TIMER_STRICT ,
 479 the system will make a best effort to strictly observe the provided
 480 .Fa leeway
 481 value even if it is smaller than the current lower limit. Note that a minimal
 482 amount of delay is to be expected even if this flag is specified.
 483 .Pp
 484 The
 485 .Fa start
 486 argument also determines which clock will be used for the timer: If
 487 .Fa start
 488 is
 489 .Vt DISPATCH_TIME_NOW
 490 or was created with
 491 .Xr dispatch_time 3 ,
 492 the timer is based on
 493 .Fn mach_absolute_time .
 494 If
 495 .Fa start
 496 was created with
 497 .Xr dispatch_walltime 3 ,
 498 the timer is based on
 499 .Xr gettimeofday 3 .
 500 .Pp
 501 .Em Note :
 502 Under the C language, untyped numbers default to the
 503 .Vt int
 504 type. This can lead to truncation bugs when arithmetic operations with other
 505 numbers are expected to generate a
 506 .Vt uint64_t
 507 sized result. When in doubt, use
 508 .Vt ull
 509 as a suffix. For example:
 510 .Bd -literal -offset indent
 511 3ull * NSEC_PER_SEC
 512 .Ed
 513 .Pp
 514 .Vt DISPATCH_SOURCE_TYPE_VNODE
 515 .Pp
 516 Sources of this type monitor the virtual filesystem nodes for state changes.
 517 The
 518 .Fa handle
 519 is a file descriptor (int) referencing the node to monitor, and
 520 the
 521 .Fa mask
 522 may be one or more of the following:
 523 .Bl -tag -width "XXDISPATCH_VNODE_ATTRIB" -compact -offset indent
 524 .It \(bu DISPATCH_VNODE_DELETE
 525 The referenced node was removed from the filesystem namespace via
 526 .Xr unlink 2 .
 527 .It \(bu DISPATCH_VNODE_WRITE
 528 A write to the referenced file occurred
 529 .It \(bu DISPATCH_VNODE_EXTEND
 530 The referenced file was extended
 531 .It \(bu DISPATCH_VNODE_ATTRIB
 532 The metadata attributes of the referenced node have changed
 533 .It \(bu DISPATCH_VNODE_LINK
 534 The link count on the referenced node has changed
 535 .It \(bu DISPATCH_VNODE_RENAME
 536 The referenced node was renamed
 537 .It \(bu DISPATCH_VNODE_REVOKE
 538 Access to the referenced node was revoked via
 539 .Xr revoke 2
 540 or the underlying fileystem was unmounted.
 541 .El
 542 .Pp
 543 The data returned by
 544 .Fn dispatch_source_get_data
 545 indicates which of the events in the
 546 .Fa mask
 547 were observed.
 548 .Pp
 549 .Vt DISPATCH_SOURCE_TYPE_WRITE
 550 .Pp
 551 Sources of this type monitor file descriptors for available write buffer space.
 552 The
 553 .Fa handle
 554 is the file descriptor (int) to monitor and the
 555 .Fa mask
 556 is unused and should be zero.
 557 .Pp
 558 Users of this source type are strongly encouraged to perform non-blocking I/O
 559 and handle any truncated reads or error conditions that may occur. See
 560 .Xr fcntl 2
 561 for additional information about setting the
 562 .Vt O_NONBLOCK
 563 flag on a file descriptor.
 564 .Pp
 565 .Sh SEE ALSO
 566 .Xr dispatch 3 ,
 567 .Xr dispatch_object 3 ,
 568 .Xr dispatch_queue_create 3