1 .\" Copyright (c) 2008-2013 Apple Inc. All rights reserved.
3 .Dt dispatch_source_create 3
6 .Nm dispatch_source_create
7 .Nd dispatch event sources
9 .Fd #include <dispatch/dispatch.h>
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"
18 .Fo dispatch_source_set_event_handler
19 .Fa "dispatch_source_t source"
20 .Fa "void (^block)(void)"
23 .Fo dispatch_source_set_event_handler_f
24 .Fa "dispatch_source_t source"
25 .Fa "void (*function)(void *)"
28 .Fo dispatch_source_set_registration_handler
29 .Fa "dispatch_source_t source"
30 .Fa "void (^block)(void)"
33 .Fo dispatch_source_set_registration_handler_f
34 .Fa "dispatch_source_t source"
35 .Fa "void (*function)(void *)"
38 .Fo dispatch_source_set_cancel_handler
39 .Fa "dispatch_source_t source"
40 .Fa "void (^block)(void)"
43 .Fo dispatch_source_set_cancel_handler_f
44 .Fa "dispatch_source_t source"
45 .Fa "void (*function)(void *)"
48 .Fo dispatch_source_cancel
49 .Fa "dispatch_source_t source"
52 .Fo dispatch_source_testcancel
53 .Fa "dispatch_source_t source"
56 .Fo dispatch_source_get_handle
57 .Fa "dispatch_source_t source"
60 .Fo dispatch_source_get_mask
61 .Fa "dispatch_source_t source"
64 .Fo dispatch_source_get_data
65 .Fa "dispatch_source_t source"
68 .Fo dispatch_source_merge_data
69 .Fa "dispatch_source_t source"
70 .Fa "unsigned long data"
73 .Fo dispatch_source_set_timer
74 .Fa "dispatch_source_t source"
75 .Fa "dispatch_time_t start"
76 .Fa "uint64_t interval"
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.
84 When a state change occurs, the dispatch source will submit its event handler
85 block to its target queue.
88 .Fn dispatch_source_create
89 function creates a new dispatch source object that may be retained and released
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
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
105 etc., the source must be activated by a call to
107 before any events will be delivered.
109 Dispatch sources may be one of the following types:
110 .Bl -bullet -compact -offset indent
112 DISPATCH_SOURCE_TYPE_DATA_ADD
114 DISPATCH_SOURCE_TYPE_DATA_OR
116 DISPATCH_SOURCE_TYPE_DATA_REPLACE
118 DISPATCH_SOURCE_TYPE_MACH_SEND
120 DISPATCH_SOURCE_TYPE_MACH_RECV
122 DISPATCH_SOURCE_TYPE_MEMORYPRESSURE
124 DISPATCH_SOURCE_TYPE_PROC
126 DISPATCH_SOURCE_TYPE_READ
128 DISPATCH_SOURCE_TYPE_SIGNAL
130 DISPATCH_SOURCE_TYPE_TIMER
132 DISPATCH_SOURCE_TYPE_VNODE
134 DISPATCH_SOURCE_TYPE_WRITE
142 .Fn dispatch_source_create
143 and the return values of the
144 .Fn dispatch_source_get_handle ,
145 .Fn dispatch_source_get_mask ,
147 .Fn dispatch_source_get_data
148 functions should be interpreted according to the type of the dispatch source.
151 .Fn dispatch_source_get_handle
153 returns the underlying handle to the dispatch source (i.e. file descriptor,
154 mach port, process identifer, etc.). The result of this function may be cast
155 directly to the underlying type.
158 .Fn dispatch_source_get_mask
160 returns the set of flags that were specified at source creation time via the
165 .Fn dispatch_source_get_data
166 function returns the currently pending data for the dispatch source.
167 This function should only be called from within the source's event handler.
168 The result of calling this function from any other context is undefined.
171 .Fn dispatch_source_merge_data
172 function is intended for use with the
173 .Vt DISPATCH_SOURCE_TYPE_DATA_ADD ,
174 .Vt DISPATCH_SOURCE_TYPE_DATA_OR
176 .Vt DISPATCH_SOURCE_TYPE_DATA_REPLACE
177 source types. The result of using this function with any other source type is
178 undefined. Data merging is performed according to the source type:
179 .Bl -tag -width "XXDISPATCH_SOURCE_TYPE_DATA_REPLACE" -compact -offset indent
180 .It \(bu DISPATCH_SOURCE_TYPE_DATA_ADD
182 is atomically added to the source's data
183 .It \(bu DISPATCH_SOURCE_TYPE_DATA_OR
185 is atomically bitwise ORed into the source's data
186 .It \(bu DISPATCH_SOURCE_TYPE_DATA_REPLACE
188 atomically replaces the source's data.
191 If the source data value resulting from the merge operation is 0, the source
192 handler will not be invoked. This can happen if:
193 .Bl -bullet -compact -offset indent
195 the atomic addition wraps for sources of type
196 .Vt DISPATCH_SOURCE_TYPE_DATA_ADD ,
198 0 is merged for sources of type
199 .Vt DISPATCH_SOURCE_TYPE_DATA_REPLACE .
202 .Sh SOURCE EVENT HANDLERS
203 In order to receive events from the dispatch source, an event handler should be
205 .Fn dispatch_source_set_event_handler .
206 The event handler block is submitted to the source's target queue when the state
207 of the underlying system handle changes, or when an event occurs. If a source
208 is resumed with no event handler block set, events will be quietly ignored.
209 If the event handler block is changed while the source is suspended, or from a
210 block running on a serial queue that is the source's target queue, then the next
211 event handler invocation will use the new block.
213 Dispatch sources may be suspended or resumed independently of their target
218 on the dispatch source directly. The data describing events which occur while a
219 source is suspended are coalesced and delivered once the source is resumed.
224 need not be reentrant safe, as it is not resubmitted to the target
226 until any prior invocation for that dispatch source has completed.
227 When the handler is set, the dispatch source will perform a
233 To unset the event handler, call
234 .Fn dispatch_source_set_event_handler_f
237 This unsets the event handler regardless of whether the handler
238 was a function pointer or a block. Registration and cancellation handlers
239 (see below) may be unset in the same way, but as noted below, a cancellation
240 handler may be required.
244 is called on a suspended or newly created source, there may be a brief delay
245 before the source is ready to receive events from the underlying system handle.
246 During this delay, the event handler will not be invoked, and events will be
249 Once the dispatch source is registered with the underlying system and is ready
250 to process all events its optional registration handler will be submitted to
251 its target queue. This registration handler may be specified via
252 .Fn dispatch_source_set_registration_handler .
254 The event handler will not be called until the registration handler finishes.
255 If the source is canceled (see below) before it is registered,
256 its registration handler will not be called.
260 .Fn dispatch_source_cancel
261 function asynchronously cancels the dispatch source, preventing any further
262 invocation of its event handler block. Cancellation does not interrupt a
263 currently executing handler block (non-preemptive). If a source is canceled
264 before the first time it is resumed, its event handler will never be called.
265 (In this case, note that the source must be resumed before it can be released.)
268 .Fn dispatch_source_testcancel
269 function may be used to determine whether the specified source has been
270 canceled. A non-zero value will be returned if the source is canceled.
272 When a dispatch source is canceled its optional cancellation handler will be
273 submitted to its target queue. The cancellation handler may be specified via
274 .Fn dispatch_source_set_cancel_handler .
275 This cancellation handler is invoked only once, and only as a direct consequence
277 .Fn dispatch_source_cancel .
280 a cancellation handler is required for file descriptor and mach port based
281 sources in order to safely close the descriptor or destroy the port. Closing the
282 descriptor or port before the cancellation handler has run may result in a race
283 condition: if a new descriptor is allocated with the same value as the recently
284 closed descriptor while the source's event handler is still running, the event
285 handler may read/write data to the wrong descriptor.
287 .Sh DISPATCH SOURCE TYPES
288 The following section contains a summary of supported dispatch event types and
289 the interpretation of their parameters and returned data.
291 .Vt DISPATCH_SOURCE_TYPE_DATA_ADD ,
292 .Vt DISPATCH_SOURCE_TYPE_DATA_OR ,
293 .Vt DISPATCH_SOURCE_TYPE_DATA_REPLACE
295 Sources of this type allow applications to manually trigger the source's event
296 handler via a call to
297 .Fn dispatch_source_merge_data .
298 The data will be merged with the source's pending data via an atomic add or
299 atomic bitwise OR, or direct replacement (based on the source's type), and the
300 event handler block will be submitted to the source's target queue. The
302 is application defined. These sources have no
306 and zero should be used.
308 .Vt DISPATCH_SOURCE_TYPE_MACH_SEND
310 Sources of this type monitor a mach port with a send right for state changes.
313 is the mach port (mach_port_t) to monitor and the
316 .Bl -tag -width "XXDISPATCH_PROC_SIGNAL" -compact -offset indent
317 .It \(bu DISPATCH_MACH_SEND_DEAD
318 The port's corresponding receive right has been destroyed
322 .Fn dispatch_source_get_data
323 is a bitmask that indicates which of the events in the
325 were observed. Note that because this source type will request notifications on
326 the provided port, it should not be mixed with the use of
327 .Fn mach_port_request_notification
330 .Vt DISPATCH_SOURCE_TYPE_MACH_RECV
332 Sources of this type monitor a mach port with a receive right for state changes.
335 is the mach port (mach_port_t) to monitor and the
337 is unused and should be zero.
338 The event handler block will be submitted to the target queue when a message
339 on the mach port is waiting to be received.
341 .Vt DISPATCH_SOURCE_TYPE_MEMORYPRESSURE
343 Sources of this type monitor the system memory pressure condition for state
346 is unused and should be zero. The
348 may be one or more of the following:
349 .Bl -tag -width "XXDISPATCH_MEMORYPRESSURE_CRITICAL" -compact -offset indent
350 .It \(bu DISPATCH_MEMORYPRESSURE_NORMAL
351 The system memory pressure condition has returned to normal.
352 .It \(bu DISPATCH_MEMORYPRESSURE_WARN
353 The system memory pressure condition has changed to warning.
354 .It \(bu DISPATCH_MEMORYPRESSURE_CRITICAL
355 The system memory pressure condition has changed to critical.
359 .Fn dispatch_source_get_data
360 indicates which of the events in the
364 Elevated memory pressure is a system-wide condition that applications
365 registered for this source should react to by changing their future memory use
366 behavior, e.g. by reducing cache sizes of newly initiated operations until
367 memory pressure returns back to normal.
369 However, applications should
371 traverse and discard existing caches for past operations when the system memory
372 pressure enters an elevated state, as that is likely to trigger VM operations
373 that will further aggravate system memory pressure.
375 .Vt DISPATCH_SOURCE_TYPE_PROC
377 Sources of this type monitor processes for state changes.
380 is the process identifier (pid_t) of the process to monitor and the
382 may be one or more of the following:
383 .Bl -tag -width "XXDISPATCH_PROC_SIGNAL" -compact -offset indent
384 .It \(bu DISPATCH_PROC_EXIT
385 The process has exited and is available to
387 .It \(bu DISPATCH_PROC_FORK
388 The process has created one or more child processes.
389 .It \(bu DISPATCH_PROC_EXEC
390 The process has become another executable image via a call to
394 .It \(bu DISPATCH_PROC_SIGNAL
395 A signal was delivered to the process.
399 .Fn dispatch_source_get_data
400 is a bitmask that indicates which of the events in the
404 .Vt DISPATCH_SOURCE_TYPE_READ
406 Sources of this type monitor file descriptors for pending data.
409 is the file descriptor (int) to monitor and the
411 is unused and should be zero.
414 .Fn dispatch_source_get_data
415 is an estimated number of bytes available to be read from the descriptor. This
416 estimate should be treated as a suggested
418 read buffer size. There are no guarantees that a complete read of this size
421 Users of this source type are strongly encouraged to perform non-blocking I/O
422 and handle any truncated reads or error conditions that may occur. See
424 for additional information about setting the
426 flag on a file descriptor.
428 .Vt DISPATCH_SOURCE_TYPE_SIGNAL
430 Sources of this type monitor signals delivered to the current process. The
432 is the signal number to monitor (int) and the
434 is unused and should be zero.
437 .Fn dispatch_source_get_data
438 is the number of signals received since the last invocation of the event handler
441 Unlike signal handlers specified via
443 the execution of the event handler block does not interrupt the current thread
444 of execution; therefore the handler block is not limited to the use of signal
445 safe interfaces defined in
447 Furthermore, multiple observers of a given signal are supported; thus allowing
448 applications and libraries to cooperate safely. However, a dispatch source
450 install a signal handler or otherwise alter the behavior of signal delivery.
451 Therefore, applications must ignore or at least catch any signal that terminates
452 a process by default. For example, near the top of
454 .Bd -literal -offset ident
455 signal(SIGTERM, SIG_IGN);
458 .Vt DISPATCH_SOURCE_TYPE_TIMER
460 Sources of this type periodically submit the event handler block to the target
463 argument is unused and should be zero.
466 .Fn dispatch_source_get_data
467 is the number of times the timer has fired since the last invocation of the
470 The timer parameters are configured with the
471 .Fn dispatch_source_set_timer
472 function. Once this function returns, any pending source data accumulated for
473 the previous timer parameters has been cleared; the next fire of the timer will
478 nanoseconds thereafter until the timer source is canceled.
480 Any fire of the timer may be delayed by the system in order to improve power
481 consumption and system performance. The upper limit to the allowable delay may
482 be configured with the
484 argument, the lower limit is under the control of the system.
486 For the initial timer fire at
488 the upper limit to the allowable delay is set to
490 nanoseconds. For the subsequent timer fires at
500 The lower limit to the allowable delay may vary with process state such as
501 visibility of application UI. If the specified timer source was created with a
504 .Vt DISPATCH_TIMER_STRICT ,
505 the system will make a best effort to strictly observe the provided
507 value even if it is smaller than the current lower limit. Note that a minimal
508 amount of delay is to be expected even if this flag is specified.
512 argument also determines which clock will be used for the timer: If
515 .Vt DISPATCH_TIME_NOW
517 .Xr dispatch_time 3 ,
518 the timer is based on
519 .Fn mach_absolute_time .
523 .Xr dispatch_walltime 3 ,
524 the timer is based on
527 .Vt DISPATCH_SOURCE_TYPE_VNODE
529 Sources of this type monitor the virtual filesystem nodes for state changes.
532 is a file descriptor (int) referencing the node to monitor, and
535 may be one or more of the following:
536 .Bl -tag -width "XXDISPATCH_VNODE_ATTRIB" -compact -offset indent
537 .It \(bu DISPATCH_VNODE_DELETE
538 The referenced node was removed from the filesystem namespace via
540 .It \(bu DISPATCH_VNODE_WRITE
541 A write to the referenced file occurred.
542 .It \(bu DISPATCH_VNODE_EXTEND
543 The referenced file was extended.
544 .It \(bu DISPATCH_VNODE_ATTRIB
545 The metadata attributes of the referenced node have changed.
546 .It \(bu DISPATCH_VNODE_LINK
547 The link count on the referenced node has changed.
548 .It \(bu DISPATCH_VNODE_RENAME
549 The referenced node was renamed.
550 .It \(bu DISPATCH_VNODE_REVOKE
551 Access to the referenced node was revoked via
553 or the underlying fileystem was unmounted.
554 .It \(bu DISPATCH_VNODE_FUNLOCK
555 The referenced file was unlocked by
562 .Fn dispatch_source_get_data
563 is a bitmask that indicates which of the events in the
567 .Vt DISPATCH_SOURCE_TYPE_WRITE
569 Sources of this type monitor file descriptors for available write buffer space.
572 is the file descriptor (int) to monitor and the
574 is unused and should be zero.
576 Users of this source type are strongly encouraged to perform non-blocking I/O
577 and handle any truncated reads or error conditions that may occur. See
579 for additional information about setting the
581 flag on a file descriptor.
585 .Xr dispatch_object 3 ,
586 .Xr dispatch_queue_create 3