man/dispatch_source_create.3

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