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_cancel_handler
  29 .Fa "dispatch_source_t source"
  30 .Fa "void (^block)(void)"
  31 .Fc
  32 .Ft void
  33 .Fo dispatch_source_set_cancel_handler_f
  34 .Fa "dispatch_source_t source"
  35 .Fa "void (*function)(void *)"
  36 .Fc
  37 .Ft void
  38 .Fo dispatch_source_cancel
  39 .Fa "dispatch_source_t source"
  40 .Fc
  41 .Ft long
  42 .Fo dispatch_source_testcancel
  43 .Fa "dispatch_source_t source"
  44 .Fc
  45 .Ft uintptr_t
  46 .Fo dispatch_source_get_handle
  47 .Fa "dispatch_source_t source"
  48 .Fc
  49 .Ft "unsigned long"
  50 .Fo dispatch_source_get_mask
  51 .Fa "dispatch_source_t source"
  52 .Fc
  53 .Ft "unsigned long"
  54 .Fo dispatch_source_get_data
  55 .Fa "dispatch_source_t source"
  56 .Fc
  57 .Ft void
  58 .Fo dispatch_source_merge_data
  59 .Fa "dispatch_source_t source"
  60 .Fa "unsigned long data"
  61 .Fc
  62 .Ft void
  63 .Fo dispatch_source_set_timer
  64 .Fa "dispatch_source_t source"
  65 .Fa "dispatch_time_t start"
  66 .Fa "uint64_t interval"
  67 .Fa "uint64_t leeway"
  68 .Fc
  69 .Sh DESCRIPTION
  70 Dispatch event sources may be used to monitor a variety of system objects and
  71 events including file descriptors, mach ports, processes, virtual filesystem
  72 nodes, signal delivery and timers.
  73 .Pp
  74 When a state change occurs, the dispatch source will submit its event handler
  75 block to its target queue.
  76 .Pp
  77 The
  78 .Fn dispatch_source_create
  79 function creates a new dispatch source object that may be retained and released
  80 with calls to
  81 .Fn dispatch_retain
  82 and
  83 .Fn dispatch_release
  84 respectively. The
  85 .Fa queue
  86 parameter specifies the target queue of the new source object, it will
  87 be retained by the source object. Pass the
  88 .Dv DISPATCH_TARGET_QUEUE_DEFAULT
  89 constant to use the default target queue (the default priority global
  90 concurrent queue).
  91 .Pp
  92 Newly created sources are created in a suspended state. After the source has
  93 been configured by setting an event handler, cancellation handler, context,
  94 etc., the source must be activated by a call to
  95 .Fn dispatch_resume
  96 before any events will be delivered.
  97 .Pp
  98 Dispatch sources may be one of the following types:
  99 .Bl -bullet -compact -offset indent
 100 .It
 101 DISPATCH_SOURCE_TYPE_DATA_ADD
 102 .It
 103 DISPATCH_SOURCE_TYPE_DATA_OR
 104 .It
 105 DISPATCH_SOURCE_TYPE_MACH_SEND
 106 .It
 107 DISPATCH_SOURCE_TYPE_MACH_RECV
 108 .It
 109 DISPATCH_SOURCE_TYPE_PROC
 110 .It
 111 DISPATCH_SOURCE_TYPE_READ
 112 .It
 113 DISPATCH_SOURCE_TYPE_SIGNAL
 114 .It
 115 DISPATCH_SOURCE_TYPE_TIMER
 116 .It
 117 DISPATCH_SOURCE_TYPE_VNODE
 118 .It
 119 DISPATCH_SOURCE_TYPE_WRITE
 120 .El
 121 .Pp
 122 The
 123 .Fa handle
 124 and
 125 .Fa mask
 126 arguments to
 127 .Fn dispatch_source_create
 128 and the return values of the
 129 .Fn dispatch_source_get_handle ,
 130 .Fn dispatch_source_get_mask ,
 131 and
 132 .Fn dispatch_source_get_data
 133 functions should be interpreted according to the type of the dispatch source.
 134 .Pp
 135 The
 136 .Fn dispatch_source_get_handle
 137 function
 138 returns the underlying handle to the dispatch source (i.e. file descriptor,
 139 mach port, process identifer, etc.). The result of this function may be cast
 140 directly to the underlying type.
 141 .Pp
 142 The
 143 .Fn dispatch_source_get_mask
 144 function
 145 returns the set of flags that were specified at source creation time via the
 146 .Fa mask
 147 argument.
 148 .Pp
 149 The
 150 .Fn dispatch_source_get_data
 151 function returns the currently pending data for the dispatch source.
 152 This function should only be called from within the source's event handler.
 153 The result of calling this function from any other context is undefined.
 154 .Pp
 155 The
 156 .Fn dispatch_source_merge_data
 157 function is intended for use with the
 158 .Vt DISPATCH_SOURCE_TYPE_DATA_ADD
 159 and
 160 .Vt DISPATCH_SOURCE_TYPE_DATA_OR
 161 source types. The result of using this function with any other source type is
 162 undefined. Calling this function will atomically add or logical OR the data
 163 into the source's data, and trigger the delivery of the source's event handler.
 164 .Pp
 165 .Sh SOURCE EVENT HANDLERS
 166 In order to receive events from the dispatch source, an event handler should be
 167 specified via
 168 .Fn dispatch_source_set_event_handler .
 169 The event handler block is submitted to the source's target queue when the state
 170 of the underlying system handle changes, or when an event occurs.
 171 .Pp
 172 Dispatch sources may be suspended or resumed independently of their target
 173 queues using
 174 .Fn dispatch_suspend
 175 and
 176 .Fn dispatch_resume
 177 on the dispatch source directly. The data describing events which occur while a
 178 source is suspended are coalesced and delivered once the source is resumed.
 179 .Pp
 180 The
 181 .Fa handler
 182 block
 183 need not be reentrant safe, as it is not resubmitted to the target
 184 .Fa queue
 185 until any prior invocation for that dispatch source has completed.
 186 When the handler is set, the dispatch source will perform a
 187 .Fn Block_copy
 188 on the
 189 .Fa handler
 190 block.
 191 .Pp
 192 .Sh CANCELLATION
 193 The
 194 .Fn dispatch_source_cancel
 195 function asynchronously cancels the dispatch source, preventing any further
 196 invocation of its event handler block. Cancellation does not interrupt a
 197 currently executing handler block (non-preemptive).
 198 .Pp
 199 The
 200 .Fn dispatch_source_testcancel
 201 function may be used to determine whether the specified source has been
 202 canceled. A non-zero value will be returned if the source is canceled.
 203 .Pp
 204 When a dispatch source is canceled its optional cancellation handler will be
 205 submitted to its target queue. The cancellation handler may be specified via
 206 .Fn dispatch_source_set_cancel_handler .
 207 This cancellation handler is invoked only once, and only as a direct consequence
 208 of calling
 209 .Fn dispatch_source_cancel .
 210 .Pp
 211 .Em Important:
 212 a cancellation handler is required for file descriptor and mach port based
 213 sources in order to safely close the descriptor or destroy the port. Closing the
 214 descriptor or port before the cancellation handler has run may result in a race
 215 condition: if a new descriptor is allocated with the same value as the recently
 216 closed descriptor while the source's event handler is still running, the event
 217 handler may read/write data to the wrong descriptor.
 218 .Pp
 219 .Sh DISPATCH SOURCE TYPES
 220 The following section contains a summary of supported dispatch event types and
 221 the interpretation of their parameters and returned data.
 222 .Pp
 223 .Vt DISPATCH_SOURCE_TYPE_DATA_ADD ,
 224 .Vt DISPATCH_SOURCE_TYPE_DATA_OR
 225 .Pp
 226 Sources of this type allow applications to manually trigger the source's event
 227 handler via a call to
 228 .Fn dispatch_source_merge_data .
 229 The data will be merged with the source's pending data via an atomic add or
 230 logic OR (based on the source's type), and the event handler block will be
 231 submitted to the source's target queue. The
 232 .Fa data
 233 is application defined. These sources have no
 234 .Fa handle
 235 or
 236 .Fa mask
 237 and zero should be used.
 238 .Pp
 239 .Vt DISPATCH_SOURCE_TYPE_MACH_SEND
 240 .Pp
 241 Sources of this type monitor a mach port with a send right for state changes.
 242 The
 243 .Fa handle
 244 is the mach port (mach_port_t) to monitor and the
 245 .Fa mask
 246 may be:
 247 .Bl -tag -width "XXDISPATCH_PROC_SIGNAL" -compact -offset indent
 248 .It \(bu DISPATCH_MACH_SEND_DEAD
 249 The port's corresponding receive right has been destroyed
 250 .El
 251 .Pp
 252 The data returned by
 253 .Fn dispatch_source_get_data
 254 indicates which of the events in the
 255 .Fa mask
 256 were observed.
 257 .Pp
 258 .Vt DISPATCH_SOURCE_TYPE_MACH_RECV
 259 .Pp
 260 Sources of this type monitor a mach port with a receive right for state changes.
 261 The
 262 .Fa handle
 263 is the mach port (mach_port_t) to monitor and the
 264 .Fa mask
 265 is unused and should be zero.
 266 The event handler block will be submitted to the target queue when a message
 267 on the mach port is waiting to be received.
 268 .Pp
 269 .Vt DISPATCH_SOURCE_TYPE_PROC
 270 .Pp
 271 Sources of this type monitor processes for state changes.
 272 The
 273 .Fa handle
 274 is the process identifier (pid_t) of the process to monitor and the
 275 .Fa mask
 276 may be one or more of the following:
 277 .Bl -tag -width "XXDISPATCH_PROC_SIGNAL" -compact -offset indent
 278 .It \(bu DISPATCH_PROC_EXIT
 279 The process has exited and is available to
 280 .Xr wait 2 .
 281 .It \(bu DISPATCH_PROC_FORK
 282 The process has created one or more child processes.
 283 .It \(bu DISPATCH_PROC_EXEC
 284 The process has become another executable image via a call to
 285 .Xr execve 2
 286 or
 287 .Xr posix_spawn 2 .
 288 .It \(bu DISPATCH_PROC_REAP
 289 The process status has been collected by its parent process via
 290 .Xr wait 2 .
 291 .It \(bu DISPATCH_PROC_SIGNAL
 292 A signal was delivered to the process.
 293 .El
 294 .Pp
 295 The data returned by
 296 .Fn dispatch_source_get_data
 297 indicates which of the events in the
 298 .Fa mask
 299 were observed.
 300 .Pp
 301 .Vt DISPATCH_SOURCE_TYPE_READ
 302 .Pp
 303 Sources of this type monitor file descriptors for pending data.
 304 The
 305 .Fa handle
 306 is the file descriptor (int) to monitor and the
 307 .Fa mask
 308 is unused and should be zero.
 309 .Pp
 310 The data returned by
 311 .Fn dispatch_source_get_data
 312 is an estimated number of bytes available to be read from the descriptor. This
 313 estimate should be treated as a suggested
 314 .Em minimum
 315 read buffer size. There are no guarantees that a complete read of this size
 316 will be performed.
 317 .Pp
 318 Users of this source type are strongly encouraged to perform non-blocking I/O
 319 and handle any truncated reads or error conditions that may occur. See
 320 .Xr fcntl 2
 321 for additional information about setting the
 322 .Vt O_NONBLOCK
 323 flag on a file descriptor.
 324 .Pp
 325 .Vt DISPATCH_SOURCE_TYPE_SIGNAL
 326 .Pp
 327 Sources of this type monitor signals delivered to the current process. The
 328 .Fa handle
 329 is the signal number to monitor (int) and the
 330 .Fa mask
 331 is unused and should be zero.
 332 .Pp
 333 The data returned by
 334 .Fn dispatch_source_get_data
 335 is the number of signals received since the last invocation of the event handler
 336 block.
 337 .Pp
 338 Unlike signal handlers specified via
 339 .Fn sigaction ,
 340 the execution of the event handler block does not interrupt the current thread
 341 of execution; therefore the handler block is not limited to the use of signal
 342 safe interfaces defined in
 343 .Xr sigaction 2 .
 344 Furthermore, multiple observers of a given signal are supported; thus allowing
 345 applications and libraries to cooperate safely. However, a dispatch source
 346 .Em does not
 347 install a signal handler or otherwise alter the behavior of signal delivery.
 348 Therefore, applications must ignore or at least catch any signal that terminates
 349 a process by default. For example, near the top of
 350 .Fn main :
 351 .Bd -literal -offset ident
 352 signal(SIGTERM, SIG_IGN);
 353 .Ed
 354 .Pp
 355 .Vt DISPATCH_SOURCE_TYPE_TIMER
 356 .Pp
 357 Sources of this type periodically submit the event handler block to the target
 358 queue on an interval specified by
 359 .Fn dispatch_source_set_timer .
 360 The
 361 .Fa handle
 362 and
 363 .Fa mask
 364 arguments are unused and should be zero.
 365 .Pp
 366 A best effort attempt is made to submit the event handler block to the target
 367 queue at the specified time; however, actual invocation may occur at a later
 368 time.
 369 .Pp
 370 The data returned by
 371 .Fn dispatch_source_get_data
 372 is the number of times the timer has fired since the last invocation of the
 373 event handler block.
 374 .Pp
 375 The function
 376 .Fn dispatch_source_set_timer
 377 takes as an argument the
 378 .Fa start
 379 time of the timer (initial fire time) represented as a
 380 .Vt dispatch_time_t .
 381 The timer dispatch source will use the same clock as the function used to
 382 create this value. (See
 383 .Xr dispatch_time 3
 384 for more information.) The
 385 .Fa interval ,
 386 in nanoseconds, specifies the period at which the timer should repeat. All
 387 timers will repeat indefinitely until
 388 .Fn dispatch_source_cancel
 389 is called. The
 390 .Fa leeway ,
 391 in nanoseconds, is a hint to the system that it may defer the timer in order to
 392 align with other system activity for improved system performance or reduced
 393 power consumption. (For example, an application might perform a periodic task
 394 every 5 minutes with a leeway of up to 30 seconds.) Note that some latency is
 395 to be expected for all timers even when a value of zero is used.
 396 .Pp
 397 .Em Note :
 398 Under the C language, untyped numbers default to the
 399 .Vt int
 400 type. This can lead to truncation bugs when arithmetic operations with other
 401 numbers are expected to generate a
 402 .Vt uint64_t
 403 sized result. When in doubt, use
 404 .Vt ull
 405 as a suffix. For example:
 406 .Bd -literal -offset indent
 407 3ull * NSEC_PER_SEC
 408 .Ed
 409 .Pp
 410 .Vt DISPATCH_SOURCE_TYPE_VNODE
 411 .Pp
 412 Sources of this type monitor the virtual filesystem nodes for state changes.
 413 The
 414 .Fa handle
 415 is a file descriptor (int) referencing the node to monitor, and
 416 the
 417 .Fa mask
 418 may be one or more of the following:
 419 .Bl -tag -width "XXDISPATCH_VNODE_ATTRIB" -compact -offset indent
 420 .It \(bu DISPATCH_VNODE_DELETE
 421 The referenced node was removed from the filesystem namespace via
 422 .Xr unlink 2 .
 423 .It \(bu DISPATCH_VNODE_WRITE
 424 A write to the referenced file occurred
 425 .It \(bu DISPATCH_VNODE_EXTEND
 426 The referenced file was extended
 427 .It \(bu DISPATCH_VNODE_ATTRIB
 428 The metadata attributes of the referenced node have changed
 429 .It \(bu DISPATCH_VNODE_LINK
 430 The link count on the referenced node has changed
 431 .It \(bu DISPATCH_VNODE_RENAME
 432 The referenced node was renamed
 433 .It \(bu DISPATCH_VNODE_REVOKE
 434 Access to the referenced node was revoked via
 435 .Xr revoke 2
 436 or the underlying fileystem was unmounted.
 437 .El
 438 .Pp
 439 The data returned by
 440 .Fn dispatch_source_get_data
 441 indicates which of the events in the
 442 .Fa mask
 443 were observed.
 444 .Pp
 445 .Vt DISPATCH_SOURCE_TYPE_WRITE
 446 .Pp
 447 Sources of this type monitor file descriptors for available write buffer space.
 448 The
 449 .Fa handle
 450 is the file descriptor (int) to monitor and the
 451 .Fa mask
 452 is unused and should be zero.
 453 .Pp
 454 Users of this source type are strongly encouraged to perform non-blocking I/O
 455 and handle any truncated reads or error conditions that may occur. See
 456 .Xr fcntl 2
 457 for additional information about setting the
 458 .Vt O_NONBLOCK
 459 flag on a file descriptor.
 460 .Pp
 461 .Sh SEE ALSO
 462 .Xr dispatch 3 ,
 463 .Xr dispatch_object 3 ,
 464 .Xr dispatch_queue_create 3