1dispatch_source_creat... BSD Library Functions Manual dispatch_source_creat...
2
4 dispatch_source_create — dispatch event sources
5
7 #include <dispatch/dispatch.h>
8 dispatch_source_t
10 dispatch_source_create(dispatch_source_type_t type, uintptr_t handle,
11 unsigned long mask, dispatch_queue_t queue);
12 void
14 dispatch_source_set_event_handler(dispatch_source_t source,
15 void (^block)(void));
16 void
18 dispatch_source_set_event_handler_f(dispatch_source_t source,
19 void (*function)(void *));
20 void
22 dispatch_source_set_registration_handler(dispatch_source_t source,
23 void (^block)(void));
24 void
26 dispatch_source_set_registration_handler_f(dispatch_source_t source,
27 void (*function)(void *));
28 void
30 dispatch_source_set_cancel_handler(dispatch_source_t source,
31 void (^block)(void));
32 void
34 dispatch_source_set_cancel_handler_f(dispatch_source_t source,
35 void (*function)(void *));
36 void
38 dispatch_source_cancel(dispatch_source_t source);
39 long
41 dispatch_source_testcancel(dispatch_source_t source);
42 uintptr_t
44 dispatch_source_get_handle(dispatch_source_t source);
45 unsigned long
47 dispatch_source_get_mask(dispatch_source_t source);
48 unsigned long
50 dispatch_source_get_data(dispatch_source_t source);
51 void
53 dispatch_source_merge_data(dispatch_source_t source, unsigned long data);
54 void
56 dispatch_source_set_timer(dispatch_source_t source,
57 dispatch_time_t start, uint64_t interval, uint64_t leeway);
58
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 When a state change occurs, the dispatch source will submit its event
65 handler block to its target queue.
66 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 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 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 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 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 The dispatch_source_get_mask() function returns the set of flags that
104 were specified at source creation time via the mask argument.
105 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 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 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
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 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 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 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
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 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 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
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 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 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 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
199 The following section contains a summary of supported dispatch event
200 types and the interpretation of their parameters and returned data.
201 DISPATCH_SOURCE_TYPE_DATA_ADD, DISPATCH_SOURCE_TYPE_DATA_OR,
203 DISPATCH_SOURCE_TYPE_DATA_REPLACE
204 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 DISPATCH_SOURCE_TYPE_MACH_SEND
214 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 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 DISPATCH_SOURCE_TYPE_MACH_RECV
229 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 DISPATCH_SOURCE_TYPE_MEMORYPRESSURE
237 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 The data returned by dispatch_source_get_data() indicates which of the
249 events in the mask were observed.
250 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 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 DISPATCH_SOURCE_TYPE_PROC
262 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 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 DISPATCH_SOURCE_TYPE_READ
279 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 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 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 DISPATCH_SOURCE_TYPE_SIGNAL
295 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 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 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 signal(SIGTERM, SIG_IGN);
314 DISPATCH_SOURCE_TYPE_TIMER
316 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 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 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 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 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 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 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 DISPATCH_SOURCE_TYPE_VNODE
352 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 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 DISPATCH_SOURCE_TYPE_WRITE
376 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 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
387 dispatch(3), dispatch_object(3), dispatch_queue_create(3)
388Darwin May 1, 2009 Darwin