1 |
/* |
2 |
* Copyright (c) 2008-2009 Apple Inc. All rights reserved. |
3 |
* |
4 |
* @APPLE_APACHE_LICENSE_HEADER_START@ |
5 |
* |
6 |
* Licensed under the Apache License, Version 2.0 (the "License"); |
7 |
* you may not use this file except in compliance with the License. |
8 |
* You may obtain a copy of the License at |
9 |
* |
10 |
* http://www.apache.org/licenses/LICENSE-2.0 |
11 |
* |
12 |
* Unless required by applicable law or agreed to in writing, software |
13 |
* distributed under the License is distributed on an "AS IS" BASIS, |
14 |
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
15 |
* See the License for the specific language governing permissions and |
16 |
* limitations under the License. |
17 |
* |
18 |
* @APPLE_APACHE_LICENSE_HEADER_END@ |
19 |
*/ |
20 |
|
21 |
#ifndef __DISPATCH_SOURCE__ |
22 |
#define __DISPATCH_SOURCE__ |
23 |
|
24 |
#ifndef __DISPATCH_INDIRECT__ |
25 |
#error "Please #include <dispatch/dispatch.h> instead of this file directly." |
26 |
#include <dispatch/base.h> // for HeaderDoc |
27 |
#endif |
28 |
|
29 |
#if TARGET_OS_MAC |
30 |
#include <mach/port.h> |
31 |
#include <mach/message.h> |
32 |
#endif |
33 |
#include <sys/signal.h> |
34 |
|
35 |
/*! |
36 |
* @header |
37 |
* The dispatch framework provides a suite of interfaces for monitoring low- |
38 |
* level system objects (file descriptors, Mach ports, signals, VFS nodes, etc.) |
39 |
* for activity and automatically submitting event handler blocks to dispatch |
40 |
* queues when such activity occurs. |
41 |
* |
42 |
* This suite of interfaces is known as the Dispatch Source API. |
43 |
*/ |
44 |
|
45 |
/*! |
46 |
* @typedef dispatch_source_t |
47 |
* |
48 |
* @abstract |
49 |
* Dispatch sources are used to automatically submit event handler blocks to |
50 |
* dispatch queues in response to external events. |
51 |
*/ |
52 |
DISPATCH_DECL(dispatch_source); |
53 |
|
54 |
/*! |
55 |
* @typedef dispatch_source_type_t |
56 |
* |
57 |
* @abstract |
58 |
* Constants of this type represent the class of low-level system object that |
59 |
* is being monitored by the dispatch source. Constants of this type are |
60 |
* passed as a parameter to dispatch_source_create() and determine how the |
61 |
* handle argument is interpreted (i.e. as a file descriptor, mach port, |
62 |
* signal number, process identifer, etc.), and how the mask arugment is |
63 |
* interpreted. |
64 |
*/ |
65 |
typedef const struct dispatch_source_type_s *dispatch_source_type_t; |
66 |
|
67 |
/*! |
68 |
* @const DISPATCH_SOURCE_TYPE_DATA_ADD |
69 |
* @discussion A dispatch source that coalesces data obtained via calls to |
70 |
* dispatch_source_merge_data(). An ADD is used to coalesce the data. |
71 |
* The handle is unused (pass zero for now). |
72 |
* The mask is unused (pass zero for now). |
73 |
*/ |
74 |
#define DISPATCH_SOURCE_TYPE_DATA_ADD (&_dispatch_source_type_data_add) |
75 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
76 |
DISPATCH_EXPORT |
77 |
const struct dispatch_source_type_s _dispatch_source_type_data_add; |
78 |
|
79 |
/*! |
80 |
* @const DISPATCH_SOURCE_TYPE_DATA_OR |
81 |
* @discussion A dispatch source that coalesces data obtained via calls to |
82 |
* dispatch_source_merge_data(). A logical OR is used to coalesce the data. |
83 |
* The handle is unused (pass zero for now). |
84 |
* The mask is used to perform a logical AND with the value passed to |
85 |
* dispatch_source_merge_data(). |
86 |
*/ |
87 |
#define DISPATCH_SOURCE_TYPE_DATA_OR (&_dispatch_source_type_data_or) |
88 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
89 |
DISPATCH_EXPORT |
90 |
const struct dispatch_source_type_s _dispatch_source_type_data_or; |
91 |
|
92 |
/*! |
93 |
* @const DISPATCH_SOURCE_TYPE_MACH_SEND |
94 |
* @discussion A dispatch source that monitors a Mach port for dead name |
95 |
* notifications (send right no longer has any corresponding receive right). |
96 |
* The handle is a Mach port with a send or send-once right (mach_port_t). |
97 |
* The mask is a mask of desired events from dispatch_source_mach_send_flags_t. |
98 |
*/ |
99 |
#define DISPATCH_SOURCE_TYPE_MACH_SEND (&_dispatch_source_type_mach_send) |
100 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
101 |
DISPATCH_EXPORT |
102 |
const struct dispatch_source_type_s _dispatch_source_type_mach_send; |
103 |
|
104 |
/*! |
105 |
* @const DISPATCH_SOURCE_TYPE_MACH_RECV |
106 |
* @discussion A dispatch source that monitors a Mach port for pending messages. |
107 |
* The handle is a Mach port with a receive right (mach_port_t). |
108 |
* The mask is unused (pass zero for now). |
109 |
*/ |
110 |
#define DISPATCH_SOURCE_TYPE_MACH_RECV (&_dispatch_source_type_mach_recv) |
111 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
112 |
DISPATCH_EXPORT |
113 |
const struct dispatch_source_type_s _dispatch_source_type_mach_recv; |
114 |
|
115 |
/*! |
116 |
* @const DISPATCH_SOURCE_TYPE_PROC |
117 |
* @discussion A dispatch source that monitors an external process for events |
118 |
* defined by dispatch_source_proc_flags_t. |
119 |
* The handle is a process identifier (pid_t). |
120 |
* The mask is a mask of desired events from dispatch_source_proc_flags_t. |
121 |
*/ |
122 |
#define DISPATCH_SOURCE_TYPE_PROC (&_dispatch_source_type_proc) |
123 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
124 |
DISPATCH_EXPORT |
125 |
const struct dispatch_source_type_s _dispatch_source_type_proc; |
126 |
|
127 |
/*! |
128 |
* @const DISPATCH_SOURCE_TYPE_READ |
129 |
* @discussion A dispatch source that monitors a file descriptor for pending |
130 |
* bytes available to be read. |
131 |
* The handle is a file descriptor (int). |
132 |
* The mask is unused (pass zero for now). |
133 |
*/ |
134 |
#define DISPATCH_SOURCE_TYPE_READ (&_dispatch_source_type_read) |
135 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
136 |
DISPATCH_EXPORT |
137 |
const struct dispatch_source_type_s _dispatch_source_type_read; |
138 |
|
139 |
/*! |
140 |
* @const DISPATCH_SOURCE_TYPE_SIGNAL |
141 |
* @discussion A dispatch source that monitors the current process for signals. |
142 |
* The handle is a signal number (int). |
143 |
* The mask is unused (pass zero for now). |
144 |
*/ |
145 |
#define DISPATCH_SOURCE_TYPE_SIGNAL (&_dispatch_source_type_signal) |
146 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
147 |
DISPATCH_EXPORT |
148 |
const struct dispatch_source_type_s _dispatch_source_type_signal; |
149 |
|
150 |
/*! |
151 |
* @const DISPATCH_SOURCE_TYPE_TIMER |
152 |
* @discussion A dispatch source that submits the event handler block based |
153 |
* on a timer. |
154 |
* The handle is unused (pass zero for now). |
155 |
* The mask is unused (pass zero for now). |
156 |
*/ |
157 |
#define DISPATCH_SOURCE_TYPE_TIMER (&_dispatch_source_type_timer) |
158 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
159 |
DISPATCH_EXPORT |
160 |
const struct dispatch_source_type_s _dispatch_source_type_timer; |
161 |
|
162 |
/*! |
163 |
* @const DISPATCH_SOURCE_TYPE_VNODE |
164 |
* @discussion A dispatch source that monitors a file descriptor for events |
165 |
* defined by dispatch_source_vnode_flags_t. |
166 |
* The handle is a file descriptor (int). |
167 |
* The mask is a mask of desired events from dispatch_source_vnode_flags_t. |
168 |
*/ |
169 |
#define DISPATCH_SOURCE_TYPE_VNODE (&_dispatch_source_type_vnode) |
170 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
171 |
DISPATCH_EXPORT |
172 |
const struct dispatch_source_type_s _dispatch_source_type_vnode; |
173 |
|
174 |
/*! |
175 |
* @const DISPATCH_SOURCE_TYPE_WRITE |
176 |
* @discussion A dispatch source that monitors a file descriptor for available |
177 |
* buffer space to write bytes. |
178 |
* The handle is a file descriptor (int). |
179 |
* The mask is unused (pass zero for now). |
180 |
*/ |
181 |
#define DISPATCH_SOURCE_TYPE_WRITE (&_dispatch_source_type_write) |
182 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
183 |
DISPATCH_EXPORT |
184 |
const struct dispatch_source_type_s _dispatch_source_type_write; |
185 |
|
186 |
/*! |
187 |
* @enum dispatch_source_mach_send_flags_t |
188 |
* |
189 |
* @constant DISPATCH_MACH_SEND_DEAD |
190 |
* The receive right corresponding to the given send right was destroyed. |
191 |
*/ |
192 |
enum { |
193 |
DISPATCH_MACH_SEND_DEAD = 0x1, |
194 |
}; |
195 |
|
196 |
/*! |
197 |
* @enum dispatch_source_proc_flags_t |
198 |
* |
199 |
* @constant DISPATCH_PROC_EXIT |
200 |
* The process has exited (perhaps cleanly, perhaps not). |
201 |
* |
202 |
* @constant DISPATCH_PROC_FORK |
203 |
* The process has created one or more child processes. |
204 |
* |
205 |
* @constant DISPATCH_PROC_EXEC |
206 |
* The process has become another executable image via |
207 |
* exec*() or posix_spawn*(). |
208 |
* |
209 |
* @constant DISPATCH_PROC_SIGNAL |
210 |
* A Unix signal was delivered to the process. |
211 |
*/ |
212 |
enum { |
213 |
DISPATCH_PROC_EXIT = 0x80000000, |
214 |
DISPATCH_PROC_FORK = 0x40000000, |
215 |
DISPATCH_PROC_EXEC = 0x20000000, |
216 |
DISPATCH_PROC_SIGNAL = 0x08000000, |
217 |
}; |
218 |
|
219 |
/*! |
220 |
* @enum dispatch_source_vnode_flags_t |
221 |
* |
222 |
* @constant DISPATCH_VNODE_DELETE |
223 |
* The filesystem object was deleted from the namespace. |
224 |
* |
225 |
* @constant DISPATCH_VNODE_WRITE |
226 |
* The filesystem object data changed. |
227 |
* |
228 |
* @constant DISPATCH_VNODE_EXTEND |
229 |
* The filesystem object changed in size. |
230 |
* |
231 |
* @constant DISPATCH_VNODE_ATTRIB |
232 |
* The filesystem object metadata changed. |
233 |
* |
234 |
* @constant DISPATCH_VNODE_LINK |
235 |
* The filesystem object link count changed. |
236 |
* |
237 |
* @constant DISPATCH_VNODE_RENAME |
238 |
* The filesystem object was renamed in the namespace. |
239 |
* |
240 |
* @constant DISPATCH_VNODE_REVOKE |
241 |
* The filesystem object was revoked. |
242 |
*/ |
243 |
enum { |
244 |
DISPATCH_VNODE_DELETE = 0x1, |
245 |
DISPATCH_VNODE_WRITE = 0x2, |
246 |
DISPATCH_VNODE_EXTEND = 0x4, |
247 |
DISPATCH_VNODE_ATTRIB = 0x8, |
248 |
DISPATCH_VNODE_LINK = 0x10, |
249 |
DISPATCH_VNODE_RENAME = 0x20, |
250 |
DISPATCH_VNODE_REVOKE = 0x40, |
251 |
}; |
252 |
|
253 |
__DISPATCH_BEGIN_DECLS |
254 |
|
255 |
/*! |
256 |
* @function dispatch_source_create |
257 |
* |
258 |
* @abstract |
259 |
* Creates a new dispatch source to monitor low-level system objects and auto- |
260 |
* matically submit a handler block to a dispatch queue in response to events. |
261 |
* |
262 |
* @discussion |
263 |
* Dispatch sources are not reentrant. Any events received while the dispatch |
264 |
* source is suspended or while the event handler block is currently executing |
265 |
* will be coalesced and delivered after the dispatch source is resumed or the |
266 |
* event handler block has returned. |
267 |
* |
268 |
* Dispatch sources are created in a suspended state. After creating the |
269 |
* source and setting any desired attributes (i.e. the handler, context, etc.), |
270 |
* a call must be made to dispatch_resume() in order to begin event delivery. |
271 |
* |
272 |
* @param type |
273 |
* Declares the type of the dispatch source. Must be one of the defined |
274 |
* dispatch_source_type_t constants. |
275 |
* @param handle |
276 |
* The underlying system handle to monitor. The interpretation of this argument |
277 |
* is determined by the constant provided in the type parameter. |
278 |
* @param mask |
279 |
* A mask of flags specifying which events are desired. The interpretation of |
280 |
* this argument is determined by the constant provided in the type parameter. |
281 |
* @param queue |
282 |
* The dispatch queue to which the event handler block will be submited. |
283 |
*/ |
284 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
285 |
DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_NOTHROW |
286 |
dispatch_source_t |
287 |
dispatch_source_create(dispatch_source_type_t type, |
288 |
uintptr_t handle, |
289 |
unsigned long mask, |
290 |
dispatch_queue_t queue); |
291 |
|
292 |
/*! |
293 |
* @function dispatch_source_set_event_handler |
294 |
* |
295 |
* @abstract |
296 |
* Sets the event handler block for the given dispatch source. |
297 |
* |
298 |
* @param source |
299 |
* The dispatch source to modify. |
300 |
* The result of passing NULL in this parameter is undefined. |
301 |
* |
302 |
* @param handler |
303 |
* The event handler block to submit to the source's target queue. |
304 |
*/ |
305 |
#ifdef __BLOCKS__ |
306 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
307 |
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW |
308 |
void |
309 |
dispatch_source_set_event_handler(dispatch_source_t source, |
310 |
dispatch_block_t handler); |
311 |
#endif /* __BLOCKS__ */ |
312 |
|
313 |
/*! |
314 |
* @function dispatch_source_set_event_handler_f |
315 |
* |
316 |
* @abstract |
317 |
* Sets the event handler function for the given dispatch source. |
318 |
* |
319 |
* @param source |
320 |
* The dispatch source to modify. |
321 |
* The result of passing NULL in this parameter is undefined. |
322 |
* |
323 |
* @param handler |
324 |
* The event handler function to submit to the source's target queue. |
325 |
* The context parameter passed to the event handler function is the current |
326 |
* context of the dispatch source at the time the handler call is made. |
327 |
* The result of passing NULL in this parameter is undefined. |
328 |
*/ |
329 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
330 |
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW |
331 |
void |
332 |
dispatch_source_set_event_handler_f(dispatch_source_t source, |
333 |
dispatch_function_t handler); |
334 |
|
335 |
/*! |
336 |
* @function dispatch_source_set_cancel_handler |
337 |
* |
338 |
* @abstract |
339 |
* Sets the cancellation handler block for the given dispatch source. |
340 |
* |
341 |
* @discussion |
342 |
* The cancellation handler (if specified) will be submitted to the source's |
343 |
* target queue in response to a call to dispatch_source_cancel() once the |
344 |
* system has released all references to the source's underlying handle and |
345 |
* the source's event handler block has returned. |
346 |
* |
347 |
* IMPORTANT: |
348 |
* A cancellation handler is required for file descriptor and mach port based |
349 |
* sources in order to safely close the descriptor or destroy the port. Closing |
350 |
* the descriptor or port before the cancellation handler may result in a race |
351 |
* condition. If a new descriptor is allocated with the same value as the |
352 |
* recently closed descriptor while the source's event handler is still running, |
353 |
* the event handler may read/write data to the wrong descriptor. |
354 |
* |
355 |
* @param source |
356 |
* The dispatch source to modify. |
357 |
* The result of passing NULL in this parameter is undefined. |
358 |
* |
359 |
* @param handler |
360 |
* The cancellation handler block to submit to the source's target queue. |
361 |
*/ |
362 |
#ifdef __BLOCKS__ |
363 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
364 |
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW |
365 |
void |
366 |
dispatch_source_set_cancel_handler(dispatch_source_t source, |
367 |
dispatch_block_t cancel_handler); |
368 |
#endif /* __BLOCKS__ */ |
369 |
|
370 |
/*! |
371 |
* @function dispatch_source_set_cancel_handler_f |
372 |
* |
373 |
* @abstract |
374 |
* Sets the cancellation handler function for the given dispatch source. |
375 |
* |
376 |
* @discussion |
377 |
* See dispatch_source_set_cancel_handler() for more details. |
378 |
* |
379 |
* @param source |
380 |
* The dispatch source to modify. |
381 |
* The result of passing NULL in this parameter is undefined. |
382 |
* |
383 |
* @param handler |
384 |
* The cancellation handler function to submit to the source's target queue. |
385 |
* The context parameter passed to the event handler function is the current |
386 |
* context of the dispatch source at the time the handler call is made. |
387 |
*/ |
388 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
389 |
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW |
390 |
void |
391 |
dispatch_source_set_cancel_handler_f(dispatch_source_t source, |
392 |
dispatch_function_t cancel_handler); |
393 |
|
394 |
/*! |
395 |
* @function dispatch_source_cancel |
396 |
* |
397 |
* @abstract |
398 |
* Asynchronously cancel the dispatch source, preventing any further invocation |
399 |
* of its event handler block. |
400 |
* |
401 |
* @discussion |
402 |
* Cancellation prevents any further invocation of the event handler block for |
403 |
* the specified dispatch source, but does not interrupt an event handler |
404 |
* block that is already in progress. |
405 |
* |
406 |
* The cancellation handler is submitted to the source's target queue once the |
407 |
* the source's event handler has finished, indicating it is now safe to close |
408 |
* the source's handle (i.e. file descriptor or mach port). |
409 |
* |
410 |
* See dispatch_source_set_cancel_handler() for more information. |
411 |
* |
412 |
* @param source |
413 |
* The dispatch source to be canceled. |
414 |
* The result of passing NULL in this parameter is undefined. |
415 |
*/ |
416 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
417 |
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW |
418 |
void |
419 |
dispatch_source_cancel(dispatch_source_t source); |
420 |
|
421 |
/*! |
422 |
* @function dispatch_source_testcancel |
423 |
* |
424 |
* @abstract |
425 |
* Tests whether the given dispatch source has been canceled. |
426 |
* |
427 |
* @param source |
428 |
* The dispatch source to be tested. |
429 |
* The result of passing NULL in this parameter is undefined. |
430 |
* |
431 |
* @result |
432 |
* Non-zero if canceled and zero if not canceled. |
433 |
*/ |
434 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
435 |
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW |
436 |
long |
437 |
dispatch_source_testcancel(dispatch_source_t source); |
438 |
|
439 |
/*! |
440 |
* @function dispatch_source_get_handle |
441 |
* |
442 |
* @abstract |
443 |
* Returns the underlying system handle associated with this dispatch source. |
444 |
* |
445 |
* @param source |
446 |
* The result of passing NULL in this parameter is undefined. |
447 |
* |
448 |
* @result |
449 |
* The return value should be interpreted according to the type of the dispatch |
450 |
* source, and may be one of the following handles: |
451 |
* |
452 |
* DISPATCH_SOURCE_TYPE_DATA_ADD: n/a |
453 |
* DISPATCH_SOURCE_TYPE_DATA_OR: n/a |
454 |
* DISPATCH_SOURCE_TYPE_MACH_SEND: mach port (mach_port_t) |
455 |
* DISPATCH_SOURCE_TYPE_MACH_RECV: mach port (mach_port_t) |
456 |
* DISPATCH_SOURCE_TYPE_PROC: process identifier (pid_t) |
457 |
* DISPATCH_SOURCE_TYPE_READ: file descriptor (int) |
458 |
* DISPATCH_SOURCE_TYPE_SIGNAL: signal number (int) |
459 |
* DISPATCH_SOURCE_TYPE_TIMER: n/a |
460 |
* DISPATCH_SOURCE_TYPE_VNODE: file descriptor (int) |
461 |
* DISPATCH_SOURCE_TYPE_WRITE: file descriptor (int) |
462 |
*/ |
463 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
464 |
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW |
465 |
uintptr_t |
466 |
dispatch_source_get_handle(dispatch_source_t source); |
467 |
|
468 |
/*! |
469 |
* @function dispatch_source_get_mask |
470 |
* |
471 |
* @abstract |
472 |
* Returns the mask of events monitored by the dispatch source. |
473 |
* |
474 |
* @param source |
475 |
* The result of passing NULL in this parameter is undefined. |
476 |
* |
477 |
* @result |
478 |
* The return value should be interpreted according to the type of the dispatch |
479 |
* source, and may be one of the following flag sets: |
480 |
* |
481 |
* DISPATCH_SOURCE_TYPE_DATA_ADD: n/a |
482 |
* DISPATCH_SOURCE_TYPE_DATA_OR: n/a |
483 |
* DISPATCH_SOURCE_TYPE_MACH_SEND: dispatch_source_mach_send_flags_t |
484 |
* DISPATCH_SOURCE_TYPE_MACH_RECV: n/a |
485 |
* DISPATCH_SOURCE_TYPE_PROC: dispatch_source_proc_flags_t |
486 |
* DISPATCH_SOURCE_TYPE_READ: n/a |
487 |
* DISPATCH_SOURCE_TYPE_SIGNAL: n/a |
488 |
* DISPATCH_SOURCE_TYPE_TIMER: n/a |
489 |
* DISPATCH_SOURCE_TYPE_VNODE: dispatch_source_vnode_flags_t |
490 |
* DISPATCH_SOURCE_TYPE_WRITE: n/a |
491 |
*/ |
492 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
493 |
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW |
494 |
unsigned long |
495 |
dispatch_source_get_mask(dispatch_source_t source); |
496 |
|
497 |
/*! |
498 |
* @function dispatch_source_get_data |
499 |
* |
500 |
* @abstract |
501 |
* Returns pending data for the dispatch source. |
502 |
* |
503 |
* @discussion |
504 |
* This function is intended to be called from within the event handler block. |
505 |
* The result of calling this function outside of the event handler callback is |
506 |
* undefined. |
507 |
* |
508 |
* @param source |
509 |
* The result of passing NULL in this parameter is undefined. |
510 |
* |
511 |
* @result |
512 |
* The return value should be interpreted according to the type of the dispatch |
513 |
* source, and may be one of the following: |
514 |
* |
515 |
* DISPATCH_SOURCE_TYPE_DATA_ADD: application defined data |
516 |
* DISPATCH_SOURCE_TYPE_DATA_OR: application defined data |
517 |
* DISPATCH_SOURCE_TYPE_MACH_SEND: dispatch_source_mach_send_flags_t |
518 |
* DISPATCH_SOURCE_TYPE_MACH_RECV: n/a |
519 |
* DISPATCH_SOURCE_TYPE_PROC: dispatch_source_proc_flags_t |
520 |
* DISPATCH_SOURCE_TYPE_READ: estimated bytes available to read |
521 |
* DISPATCH_SOURCE_TYPE_SIGNAL: number of signals delivered since |
522 |
* the last handler invocation |
523 |
* DISPATCH_SOURCE_TYPE_TIMER: number of times the timer has fired |
524 |
* since the last handler invocation |
525 |
* DISPATCH_SOURCE_TYPE_VNODE: dispatch_source_vnode_flags_t |
526 |
* DISPATCH_SOURCE_TYPE_WRITE: estimated buffer space available |
527 |
*/ |
528 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
529 |
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW |
530 |
unsigned long |
531 |
dispatch_source_get_data(dispatch_source_t source); |
532 |
|
533 |
/*! |
534 |
* @function dispatch_source_merge_data |
535 |
* |
536 |
* @abstract |
537 |
* Merges data into a dispatch source of type DISPATCH_SOURCE_TYPE_DATA_ADD or |
538 |
* DISPATCH_SOURCE_TYPE_DATA_OR and submits its event handler block to its |
539 |
* target queue. |
540 |
* |
541 |
* @param source |
542 |
* The result of passing NULL in this parameter is undefined. |
543 |
* |
544 |
* @param value |
545 |
* The value to coalesce with the pending data using a logical OR or an ADD |
546 |
* as specified by the dispatch source type. A value of zero has no effect |
547 |
* and will not result in the submission of the event handler block. |
548 |
*/ |
549 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
550 |
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW |
551 |
void |
552 |
dispatch_source_merge_data(dispatch_source_t source, unsigned long value); |
553 |
|
554 |
/*! |
555 |
* @function dispatch_source_set_timer |
556 |
* |
557 |
* @abstract |
558 |
* Sets a start time, interval, and leeway value for a timer source. |
559 |
* |
560 |
* @discussion |
561 |
* Calling this function has no effect if the timer source has already been |
562 |
* canceled. |
563 |
* |
564 |
* The start time argument also determines which clock will be used for the |
565 |
* timer. If the start time is DISPATCH_TIME_NOW or created with |
566 |
* dispatch_time() then the timer is based on mach_absolute_time(). Otherwise, |
567 |
* if the start time of the timer is created with dispatch_walltime() then the |
568 |
* timer is based on gettimeofday(3). |
569 |
* |
570 |
* @param start |
571 |
* The start time of the timer. See dispatch_time() and dispatch_walltime() |
572 |
* for more information. |
573 |
* |
574 |
* @param interval |
575 |
* The nanosecond interval for the timer. |
576 |
* |
577 |
* @param leeway |
578 |
* A hint given to the system by the application for the amount of leeway, in |
579 |
* nanoseconds, that the system may defer the timer in order to align with other |
580 |
* system activity for improved system performance or power consumption. (For |
581 |
* example, an application might perform a periodic task every 5 minutes, with |
582 |
* a leeway of up to 30 seconds.) Note that some latency is to be expected for |
583 |
* all timers even when a leeway value of zero is specified. |
584 |
*/ |
585 |
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0) |
586 |
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW |
587 |
void |
588 |
dispatch_source_set_timer(dispatch_source_t source, |
589 |
dispatch_time_t start, |
590 |
uint64_t interval, |
591 |
uint64_t leeway); |
592 |
|
593 |
__DISPATCH_END_DECLS |
594 |
|
595 |
#endif |