1dispatch_source_creat... BSD Library Functions Manual dispatch_source_creat...
2

NAME

4     dispatch_source_create — dispatch event sources
5

SYNOPSIS

7     #include <dispatch/dispatch.h>
8
9     dispatch_source_t
10     dispatch_source_create(dispatch_source_type_t type, uintptr_t handle,
11         unsigned long mask, dispatch_queue_t queue);
12
13     void
14     dispatch_source_set_event_handler(dispatch_source_t source,
15         void (^block)(void));
16
17     void
18     dispatch_source_set_event_handler_f(dispatch_source_t source,
19         void (*function)(void *));
20
21     void
22     dispatch_source_set_registration_handler(dispatch_source_t source,
23         void (^block)(void));
24
25     void
26     dispatch_source_set_registration_handler_f(dispatch_source_t source,
27         void (*function)(void *));
28
29     void
30     dispatch_source_set_cancel_handler(dispatch_source_t source,
31         void (^block)(void));
32
33     void
34     dispatch_source_set_cancel_handler_f(dispatch_source_t source,
35         void (*function)(void *));
36
37     void
38     dispatch_source_cancel(dispatch_source_t source);
39
40     long
41     dispatch_source_testcancel(dispatch_source_t source);
42
43     uintptr_t
44     dispatch_source_get_handle(dispatch_source_t source);
45
46     unsigned long
47     dispatch_source_get_mask(dispatch_source_t source);
48
49     unsigned long
50     dispatch_source_get_data(dispatch_source_t source);
51
52     void
53     dispatch_source_merge_data(dispatch_source_t source, unsigned long data);
54
55     void
56     dispatch_source_set_timer(dispatch_source_t source,
57         dispatch_time_t start, uint64_t interval, uint64_t leeway);
58

DESCRIPTION

60     Dispatch event sources may be used to monitor a variety of system objects
61     and events including file descriptors, mach ports, processes, virtual
62     filesystem nodes, signal delivery and timers.
63
64     When a state change occurs, the dispatch source will submit its event
65     handler block to its target queue.
66
67     The dispatch_source_create() function creates a new dispatch source
68     object that may be retained and released with calls to dispatch_retain()
69     and dispatch_release() respectively. The queue parameter specifies the
70     target queue of the new source object, it will be retained by the source
71     object. Pass the DISPATCH_TARGET_QUEUE_DEFAULT constant to use the
72     default target queue (the default priority global concurrent queue).
73
74     Newly created sources are created in a suspended state. After the source
75     has been configured by setting an event handler, cancellation handler,
76     registration handler, context, etc., the source must be activated by a
77     call to dispatch_resume() before any events will be delivered.
78
79     Dispatch sources may be one of the following types:
80           ·   DISPATCH_SOURCE_TYPE_DATA_ADD
81           ·   DISPATCH_SOURCE_TYPE_DATA_OR
82           ·   DISPATCH_SOURCE_TYPE_DATA_REPLACE
83           ·   DISPATCH_SOURCE_TYPE_MACH_SEND
84           ·   DISPATCH_SOURCE_TYPE_MACH_RECV
85           ·   DISPATCH_SOURCE_TYPE_MEMORYPRESSURE
86           ·   DISPATCH_SOURCE_TYPE_PROC
87           ·   DISPATCH_SOURCE_TYPE_READ
88           ·   DISPATCH_SOURCE_TYPE_SIGNAL
89           ·   DISPATCH_SOURCE_TYPE_TIMER
90           ·   DISPATCH_SOURCE_TYPE_VNODE
91           ·   DISPATCH_SOURCE_TYPE_WRITE
92
93     The handle and mask arguments to dispatch_source_create() and the return
94     values of the dispatch_source_get_handle(), dispatch_source_get_mask(),
95     and dispatch_source_get_data() functions should be interpreted according
96     to the type of the dispatch source.
97
98     The dispatch_source_get_handle() function returns the underlying handle
99     to the dispatch source (i.e. file descriptor, mach port, process identi‐
100     fer, etc.). The result of this function may be cast directly to the
101     underlying type.
102
103     The dispatch_source_get_mask() function returns the set of flags that
104     were specified at source creation time via the mask argument.
105
106     The dispatch_source_get_data() function returns the currently pending
107     data for the dispatch source.  This function should only be called from
108     within the source's event handler.  The result of calling this function
109     from any other context is undefined.
110
111     The dispatch_source_merge_data() function is intended for use with the
112     DISPATCH_SOURCE_TYPE_DATA_ADD, DISPATCH_SOURCE_TYPE_DATA_OR and
113     DISPATCH_SOURCE_TYPE_DATA_REPLACE source types. The result of using this
114     function with any other source type is undefined. Data merging is per‐
115     formed according to the source type:
116           · DISPATCH_SOURCE_TYPE_DATA_ADD      data is atomically added to
117                                                the source's data
118           · DISPATCH_SOURCE_TYPE_DATA_OR       data is atomically bitwise
119                                                ORed into the source's data
120           · DISPATCH_SOURCE_TYPE_DATA_REPLACE  data atomically replaces the
121                                                source's data.
122
123     If the source data value resulting from the merge operation is 0, the
124     source handler will not be invoked. This can happen if:
125           ·   the atomic addition wraps for sources of type
126               DISPATCH_SOURCE_TYPE_DATA_ADD,
127           ·   0 is merged for sources of type
128               DISPATCH_SOURCE_TYPE_DATA_REPLACE.
129

SOURCE EVENT HANDLERS

131     In order to receive events from the dispatch source, an event handler
132     should be specified via dispatch_source_set_event_handler().  The event
133     handler block is submitted to the source's target queue when the state of
134     the underlying system handle changes, or when an event occurs. If a
135     source is resumed with no event handler block set, events will be quietly
136     ignored.  If the event handler block is changed while the source is sus‐
137     pended, or from a block running on a serial queue that is the source's
138     target queue, then the next event handler invocation will use the new
139     block.
140
141     Dispatch sources may be suspended or resumed independently of their tar‐
142     get queues using dispatch_suspend() and dispatch_resume() on the dispatch
143     source directly. The data describing events which occur while a source is
144     suspended are coalesced and delivered once the source is resumed.
145
146     The handler block need not be reentrant safe, as it is not resubmitted to
147     the target queue until any prior invocation for that dispatch source has
148     completed.  When the handler is set, the dispatch source will perform a
149     Block_copy() on the handler block.
150
151     To unset the event handler, call dispatch_source_set_event_handler_f()
152     and pass NULL as function.  This unsets the event handler regardless of
153     whether the handler was a function pointer or a block. Registration and
154     cancellation handlers (see below) may be unset in the same way, but as
155     noted below, a cancellation handler may be required.
156

REGISTRATION

158     When dispatch_resume() is called on a suspended or newly created source,
159     there may be a brief delay before the source is ready to receive events
160     from the underlying system handle.  During this delay, the event handler
161     will not be invoked, and events will be missed.
162
163     Once the dispatch source is registered with the underlying system and is
164     ready to process all events its optional registration handler will be
165     submitted to its target queue. This registration handler may be specified
166     via dispatch_source_set_registration_handler().
167
168     The event handler will not be called until the registration handler fin‐
169     ishes.  If the source is canceled (see below) before it is registered,
170     its registration handler will not be called.
171

CANCELLATION

173     The dispatch_source_cancel() function asynchronously cancels the dispatch
174     source, preventing any further invocation of its event handler block.
175     Cancellation does not interrupt a currently executing handler block (non-
176     preemptive). If a source is canceled before the first time it is resumed,
177     its event handler will never be called.  (In this case, note that the
178     source must be resumed before it can be released.)
179
180     The dispatch_source_testcancel() function may be used to determine
181     whether the specified source has been canceled. A non-zero value will be
182     returned if the source is canceled.
183
184     When a dispatch source is canceled its optional cancellation handler will
185     be submitted to its target queue. The cancellation handler may be speci‐
186     fied via dispatch_source_set_cancel_handler().  This cancellation handler
187     is invoked only once, and only as a direct consequence of calling
188     dispatch_source_cancel().
189
190     Important: a cancellation handler is required for file descriptor and
191     mach port based sources in order to safely close the descriptor or
192     destroy the port. Closing the descriptor or port before the cancellation
193     handler has run may result in a race condition: if a new descriptor is
194     allocated with the same value as the recently closed descriptor while the
195     source's event handler is still running, the event handler may read/write
196     data to the wrong descriptor.
197

DISPATCH SOURCE TYPES

199     The following section contains a summary of supported dispatch event
200     types and the interpretation of their parameters and returned data.
201
202     DISPATCH_SOURCE_TYPE_DATA_ADD, DISPATCH_SOURCE_TYPE_DATA_OR,
203     DISPATCH_SOURCE_TYPE_DATA_REPLACE
204
205     Sources of this type allow applications to manually trigger the source's
206     event handler via a call to dispatch_source_merge_data().  The data will
207     be merged with the source's pending data via an atomic add or atomic bit‐
208     wise OR, or direct replacement (based on the source's type), and the
209     event handler block will be submitted to the source's target queue. The
210     data is application defined. These sources have no handle or mask and
211     zero should be used.
212
213     DISPATCH_SOURCE_TYPE_MACH_SEND
214
215     Sources of this type monitor a mach port with a send right for state
216     changes.  The handle is the mach port (mach_port_t) to monitor and the
217     mask may be:
218           · DISPATCH_MACH_SEND_DEAD
219                                   The port's corresponding receive right has
220                                   been destroyed
221
222     The data returned by dispatch_source_get_data() is a bitmask that indi‐
223     cates which of the events in the mask were observed.  Note that because
224     this source type will request notifications on the provided port, it
225     should not be mixed with the use of mach_port_request_notification() on
226     the same port.
227
228     DISPATCH_SOURCE_TYPE_MACH_RECV
229
230     Sources of this type monitor a mach port with a receive right for state
231     changes.  The handle is the mach port (mach_port_t) to monitor and the
232     mask is unused and should be zero.  The event handler block will be sub‐
233     mitted to the target queue when a message on the mach port is waiting to
234     be received.
235
236     DISPATCH_SOURCE_TYPE_MEMORYPRESSURE
237
238     Sources of this type monitor the system memory pressure condition for
239     state changes.  The handle is unused and should be zero. The mask may be
240     one or more of the following:
241           · DISPATCH_MEMORYPRESSURE_NORMAL    The system memory pressure con‐
242                                               dition has returned to normal.
243           · DISPATCH_MEMORYPRESSURE_WARN      The system memory pressure con‐
244                                               dition has changed to warning.
245           · DISPATCH_MEMORYPRESSURE_CRITICAL  The system memory pressure con‐
246                                               dition has changed to critical.
247
248     The data returned by dispatch_source_get_data() indicates which of the
249     events in the mask were observed.
250
251     Elevated memory pressure is a system-wide condition that applications
252     registered for this source should react to by changing their future mem‐
253     ory use behavior, e.g. by reducing cache sizes of newly initiated opera‐
254     tions until memory pressure returns back to normal.
255
256     However, applications should NOT traverse and discard existing caches for
257     past operations when the system memory pressure enters an elevated state,
258     as that is likely to trigger VM operations that will further aggravate
259     system memory pressure.
260
261     DISPATCH_SOURCE_TYPE_PROC
262
263     Sources of this type monitor processes for state changes.  The handle is
264     the process identifier (pid_t) of the process to monitor and the mask may
265     be one or more of the following:
266           · DISPATCH_PROC_EXIT    The process has exited and is available to
267                                   wait(2).
268           · DISPATCH_PROC_FORK    The process has created one or more child
269                                   processes.
270           · DISPATCH_PROC_EXEC    The process has become another executable
271                                   image via a call to execve(2) or
272                                   posix_spawn(2).
273           · DISPATCH_PROC_SIGNAL  A signal was delivered to the process.
274
275     The data returned by dispatch_source_get_data() is a bitmask that indi‐
276     cates which of the events in the mask were observed.
277
278     DISPATCH_SOURCE_TYPE_READ
279
280     Sources of this type monitor file descriptors for pending data.  The
281     handle is the file descriptor (int) to monitor and the mask is unused and
282     should be zero.
283
284     The data returned by dispatch_source_get_data() is an estimated number of
285     bytes available to be read from the descriptor. This estimate should be
286     treated as a suggested minimum read buffer size. There are no guarantees
287     that a complete read of this size will be performed.
288
289     Users of this source type are strongly encouraged to perform non-blocking
290     I/O and handle any truncated reads or error conditions that may occur.
291     See fcntl(2) for additional information about setting the O_NONBLOCK flag
292     on a file descriptor.
293
294     DISPATCH_SOURCE_TYPE_SIGNAL
295
296     Sources of this type monitor signals delivered to the current process.
297     The handle is the signal number to monitor (int) and the mask is unused
298     and should be zero.
299
300     The data returned by dispatch_source_get_data() is the number of signals
301     received since the last invocation of the event handler block.
302
303     Unlike signal handlers specified via sigaction(), the execution of the
304     event handler block does not interrupt the current thread of execution;
305     therefore the handler block is not limited to the use of signal safe
306     interfaces defined in sigaction(2).  Furthermore, multiple observers of a
307     given signal are supported; thus allowing applications and libraries to
308     cooperate safely. However, a dispatch source does not install a signal
309     handler or otherwise alter the behavior of signal delivery.  Therefore,
310     applications must ignore or at least catch any signal that terminates a
311     process by default. For example, near the top of main():
312
313          signal(SIGTERM, SIG_IGN);
314
315     DISPATCH_SOURCE_TYPE_TIMER
316
317     Sources of this type periodically submit the event handler block to the
318     target queue. The handle argument is unused and should be zero.
319
320     The data returned by dispatch_source_get_data() is the number of times
321     the timer has fired since the last invocation of the event handler block.
322
323     The timer parameters are configured with the dispatch_source_set_timer()
324     function. Once this function returns, any pending source data accumulated
325     for the previous timer parameters has been cleared; the next fire of the
326     timer will occur at start, and every interval nanoseconds thereafter
327     until the timer source is canceled.
328
329     Any fire of the timer may be delayed by the system in order to improve
330     power consumption and system performance. The upper limit to the allow‐
331     able delay may be configured with the leeway argument, the lower limit is
332     under the control of the system.
333
334     For the initial timer fire at start, the upper limit to the allowable
335     delay is set to leeway nanoseconds. For the subsequent timer fires at
336     start + N * interval, the upper limit is MIN( leeway, interval / 2 ).
337
338     The lower limit to the allowable delay may vary with process state such
339     as visibility of application UI. If the specified timer source was cre‐
340     ated with a mask of DISPATCH_TIMER_STRICT, the system will make a best
341     effort to strictly observe the provided leeway value even if it is
342     smaller than the current lower limit. Note that a minimal amount of delay
343     is to be expected even if this flag is specified.
344
345     The start argument also determines which clock will be used for the
346     timer: If start is DISPATCH_TIME_NOW or was created with
347     dispatch_time(3), the timer is based on up time (which is obtained from
348     mach_absolute_time() on Apple platforms).  If start was created with
349     dispatch_walltime(3), the timer is based on gettimeofday(3).
350
351     DISPATCH_SOURCE_TYPE_VNODE
352
353     Sources of this type monitor the virtual filesystem nodes for state
354     changes.  The handle is a file descriptor (int) referencing the node to
355     monitor, and the mask may be one or more of the following:
356           · DISPATCH_VNODE_DELETE  The referenced node was removed from the
357                                    filesystem namespace via unlink(2).
358           · DISPATCH_VNODE_WRITE   A write to the referenced file occurred.
359           · DISPATCH_VNODE_EXTEND  The referenced file was extended.
360           · DISPATCH_VNODE_ATTRIB  The metadata attributes of the referenced
361                                    node have changed.
362           · DISPATCH_VNODE_LINK    The link count on the referenced node has
363                                    changed.
364           · DISPATCH_VNODE_RENAME  The referenced node was renamed.
365           · DISPATCH_VNODE_REVOKE  Access to the referenced node was revoked
366                                    via revoke(2) or the underlying fileystem
367                                    was unmounted.
368           · DISPATCH_VNODE_FUNLOCK
369                                    The referenced file was unlocked by
370                                    flock(2) or close(2).
371
372     The data returned by dispatch_source_get_data() is a bitmask that indi‐
373     cates which of the events in the mask were observed.
374
375     DISPATCH_SOURCE_TYPE_WRITE
376
377     Sources of this type monitor file descriptors for available write buffer
378     space.  The handle is the file descriptor (int) to monitor and the mask
379     is unused and should be zero.
380
381     Users of this source type are strongly encouraged to perform non-blocking
382     I/O and handle any truncated reads or error conditions that may occur.
383     See fcntl(2) for additional information about setting the O_NONBLOCK flag
384     on a file descriptor.
385

SEE ALSO

387     dispatch(3), dispatch_object(3), dispatch_queue_create(3)
388
389Darwin                            May 1, 2009                           Darwin
Impressum