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