1/*
2 * Copyright (c) 2008-2013 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
34#if !defined(_WIN32)
35#include <sys/signal.h>
36#endif
37
38DISPATCH_ASSUME_NONNULL_BEGIN
39DISPATCH_ASSUME_ABI_SINGLE_BEGIN
40
41/*!
42 * @header
43 * The dispatch framework provides a suite of interfaces for monitoring low-
44 * level system objects (file descriptors, Mach ports, signals, VFS nodes, etc.)
45 * for activity and automatically submitting event handler blocks to dispatch
46 * queues when such activity occurs.
47 *
48 * This suite of interfaces is known as the Dispatch Source API.
49 */
50
51/*!
52 * @typedef dispatch_source_t
53 *
54 * @abstract
55 * Dispatch sources are used to automatically submit event handler blocks to
56 * dispatch queues in response to external events.
57 */
58DISPATCH_SOURCE_DECL_SWIFT(dispatch_source, DispatchSource, DispatchSourceProtocol);
59
60__BEGIN_DECLS
61
62/*!
63 * @typedef dispatch_source_type_t
64 *
65 * @abstract
66 * Constants of this type represent the class of low-level system object that
67 * is being monitored by the dispatch source. Constants of this type are
68 * passed as a parameter to dispatch_source_create() and determine how the
69 * handle argument is interpreted (i.e. as a file descriptor, mach port,
70 * signal number, process identifier, etc.), and how the mask argument is
71 * interpreted.
72 */
73DISPATCH_REFINED_FOR_SWIFT
74typedef const struct dispatch_source_type_s *dispatch_source_type_t;
75
76/*!
77 * @const DISPATCH_SOURCE_TYPE_DATA_ADD
78 * @discussion A dispatch source that coalesces data obtained via calls to
79 * dispatch_source_merge_data(). An ADD is used to coalesce the data.
80 * The handle is unused (pass zero for now).
81 * The mask is unused (pass zero for now).
82 */
83#define DISPATCH_SOURCE_TYPE_DATA_ADD (&_dispatch_source_type_data_add)
84API_AVAILABLE(macos(10.6), ios(4.0))
85DISPATCH_SOURCE_TYPE_DECL_SWIFT(data_add, DispatchSourceUserDataAdd);
86
87/*!
88 * @const DISPATCH_SOURCE_TYPE_DATA_OR
89 * @discussion A dispatch source that coalesces data obtained via calls to
90 * dispatch_source_merge_data(). A bitwise OR is used to coalesce the data.
91 * The handle is unused (pass zero for now).
92 * The mask is unused (pass zero for now).
93 */
94#define DISPATCH_SOURCE_TYPE_DATA_OR (&_dispatch_source_type_data_or)
95API_AVAILABLE(macos(10.6), ios(4.0))
96DISPATCH_SOURCE_TYPE_DECL_SWIFT(data_or, DispatchSourceUserDataOr);
97
98/*!
99 * @const DISPATCH_SOURCE_TYPE_DATA_REPLACE
100 * @discussion A dispatch source that tracks data obtained via calls to
101 * dispatch_source_merge_data(). Newly obtained data values replace existing
102 * data values not yet delivered to the source handler
103 *
104 * A data value of zero will cause the source handler to not be invoked.
105 *
106 * The handle is unused (pass zero for now).
107 * The mask is unused (pass zero for now).
108 */
109#define DISPATCH_SOURCE_TYPE_DATA_REPLACE (&_dispatch_source_type_data_replace)
110API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0))
111DISPATCH_SOURCE_TYPE_DECL_SWIFT(data_replace, DispatchSourceUserDataReplace);
112
113/*!
114 * @const DISPATCH_SOURCE_TYPE_MACH_SEND
115 * @discussion A dispatch source that monitors a Mach port for dead name
116 * notifications (send right no longer has any corresponding receive right).
117 * The handle is a Mach port with a send or send-once right (mach_port_t).
118 * The mask is a mask of desired events from dispatch_source_mach_send_flags_t.
119 */
120#define DISPATCH_SOURCE_TYPE_MACH_SEND (&_dispatch_source_type_mach_send)
121API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
122DISPATCH_SOURCE_TYPE_DECL_SWIFT(mach_send, DispatchSourceMachSend);
123
124/*!
125 * @const DISPATCH_SOURCE_TYPE_MACH_RECV
126 * @discussion A dispatch source that monitors a Mach port for pending messages.
127 * The handle is a Mach port with a receive right (mach_port_t).
128 * The mask is a mask of desired events from dispatch_source_mach_recv_flags_t,
129 * but no flags are currently defined (pass zero for now).
130 */
131#define DISPATCH_SOURCE_TYPE_MACH_RECV (&_dispatch_source_type_mach_recv)
132API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
133DISPATCH_SOURCE_TYPE_DECL_SWIFT(mach_recv, DispatchSourceMachReceive);
134
135/*!
136 * @const DISPATCH_SOURCE_TYPE_MEMORYPRESSURE
137 * @discussion A dispatch source that monitors the system for changes in
138 * memory pressure condition.
139 * The handle is unused (pass zero for now).
140 * The mask is a mask of desired events from
141 * dispatch_source_memorypressure_flags_t.
142 */
143#define DISPATCH_SOURCE_TYPE_MEMORYPRESSURE \
144 (&_dispatch_source_type_memorypressure)
145API_AVAILABLE(macos(10.9), ios(8.0)) DISPATCH_LINUX_UNAVAILABLE()
146DISPATCH_SOURCE_TYPE_DECL_SWIFT(memorypressure, DispatchSourceMemoryPressure);
147
148/*!
149 * @const DISPATCH_SOURCE_TYPE_PROC
150 * @discussion A dispatch source that monitors an external process for events
151 * defined by dispatch_source_proc_flags_t.
152 * The handle is a process identifier (pid_t).
153 * The mask is a mask of desired events from dispatch_source_proc_flags_t.
154 */
155#define DISPATCH_SOURCE_TYPE_PROC (&_dispatch_source_type_proc)
156API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
157DISPATCH_SOURCE_TYPE_DECL_SWIFT(proc, DispatchSourceProcess);
158
159/*!
160 * @const DISPATCH_SOURCE_TYPE_READ
161 * @discussion A dispatch source that monitors a file descriptor for pending
162 * bytes available to be read.
163 * The handle is a file descriptor (int).
164 * The mask is unused (pass zero for now).
165 */
166#define DISPATCH_SOURCE_TYPE_READ (&_dispatch_source_type_read)
167API_AVAILABLE(macos(10.6), ios(4.0))
168DISPATCH_SOURCE_TYPE_DECL_SWIFT(read, DispatchSourceRead);
169
170/*!
171 * @const DISPATCH_SOURCE_TYPE_SIGNAL
172 * @discussion A dispatch source that monitors the current process for signals.
173 * The handle is a signal number (int).
174 * The mask is unused (pass zero for now).
175 */
176#define DISPATCH_SOURCE_TYPE_SIGNAL (&_dispatch_source_type_signal)
177API_AVAILABLE(macos(10.6), ios(4.0))
178DISPATCH_SOURCE_TYPE_DECL_SWIFT(signal, DispatchSourceSignal);
179
180/*!
181 * @const DISPATCH_SOURCE_TYPE_TIMER
182 * @discussion A dispatch source that submits the event handler block based
183 * on a timer.
184 * The handle is unused (pass zero for now).
185 * The mask specifies which flags from dispatch_source_timer_flags_t to apply.
186 */
187#define DISPATCH_SOURCE_TYPE_TIMER (&_dispatch_source_type_timer)
188API_AVAILABLE(macos(10.6), ios(4.0))
189DISPATCH_SOURCE_TYPE_DECL_SWIFT(timer, DispatchSourceTimer);
190
191/*!
192 * @const DISPATCH_SOURCE_TYPE_VNODE
193 * @discussion A dispatch source that monitors a file descriptor for events
194 * defined by dispatch_source_vnode_flags_t.
195 * The handle is a file descriptor (int).
196 * The mask is a mask of desired events from dispatch_source_vnode_flags_t.
197 */
198#define DISPATCH_SOURCE_TYPE_VNODE (&_dispatch_source_type_vnode)
199API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
200DISPATCH_SOURCE_TYPE_DECL_SWIFT(vnode, DispatchSourceFileSystemObject);
201
202/*!
203 * @const DISPATCH_SOURCE_TYPE_WRITE
204 * @discussion A dispatch source that monitors a file descriptor for available
205 * buffer space to write bytes.
206 * The handle is a file descriptor (int).
207 * The mask is unused (pass zero for now).
208 */
209#define DISPATCH_SOURCE_TYPE_WRITE (&_dispatch_source_type_write)
210API_AVAILABLE(macos(10.6), ios(4.0))
211DISPATCH_SOURCE_TYPE_DECL_SWIFT(write, DispatchSourceWrite);
212
213/*!
214 * @typedef dispatch_source_mach_send_flags_t
215 * Type of dispatch_source_mach_send flags
216 *
217 * @constant DISPATCH_MACH_SEND_DEAD
218 * The receive right corresponding to the given send right was destroyed.
219 */
220#define DISPATCH_MACH_SEND_DEAD 0x1
221
222DISPATCH_SWIFT_UNAVAILABLE("Use DispatchSource.MachSendEvent")
223typedef unsigned long dispatch_source_mach_send_flags_t;
224
225/*!
226 * @typedef dispatch_source_mach_recv_flags_t
227 * Type of dispatch_source_mach_recv flags
228 */
229typedef unsigned long dispatch_source_mach_recv_flags_t;
230
231/*!
232 * @typedef dispatch_source_memorypressure_flags_t
233 * Type of dispatch_source_memorypressure flags
234 *
235 * @constant DISPATCH_MEMORYPRESSURE_NORMAL
236 * The system memory pressure condition has returned to normal.
237 *
238 * @constant DISPATCH_MEMORYPRESSURE_WARN
239 * The system memory pressure condition has changed to warning.
240 *
241 * @constant DISPATCH_MEMORYPRESSURE_CRITICAL
242 * The system memory pressure condition has changed to critical.
243 *
244 * @discussion
245 * Elevated memory pressure is a system-wide condition that applications
246 * registered for this source should react to by changing their future memory
247 * use behavior, e.g. by reducing cache sizes of newly initiated operations
248 * until memory pressure returns back to normal.
249 * NOTE: applications should NOT traverse and discard existing caches for past
250 * operations when the system memory pressure enters an elevated state, as that
251 * is likely to trigger VM operations that will further aggravate system memory
252 * pressure.
253 */
254
255#define DISPATCH_MEMORYPRESSURE_NORMAL 0x01
256#define DISPATCH_MEMORYPRESSURE_WARN 0x02
257#define DISPATCH_MEMORYPRESSURE_CRITICAL 0x04
258
259DISPATCH_SWIFT_UNAVAILABLE("Use DispatchSource.MemoryPressureEvent")
260typedef unsigned long dispatch_source_memorypressure_flags_t;
261
262/*!
263 * @typedef dispatch_source_proc_flags_t
264 * Type of dispatch_source_proc flags
265 *
266 * @constant DISPATCH_PROC_EXIT
267 * The process has exited (perhaps cleanly, perhaps not).
268 *
269 * @constant DISPATCH_PROC_FORK
270 * The process has created one or more child processes.
271 *
272 * @constant DISPATCH_PROC_EXEC
273 * The process has become another executable image via
274 * exec*() or posix_spawn*().
275 *
276 * @constant DISPATCH_PROC_SIGNAL
277 * A Unix signal was delivered to the process.
278 */
279#define DISPATCH_PROC_EXIT 0x80000000
280#define DISPATCH_PROC_FORK 0x40000000
281#define DISPATCH_PROC_EXEC 0x20000000
282#define DISPATCH_PROC_SIGNAL 0x08000000
283
284DISPATCH_SWIFT_UNAVAILABLE("Use DispatchSource.ProcessEvent")
285typedef unsigned long dispatch_source_proc_flags_t;
286
287/*!
288 * @typedef dispatch_source_vnode_flags_t
289 * Type of dispatch_source_vnode flags
290 *
291 * @constant DISPATCH_VNODE_DELETE
292 * The filesystem object was deleted from the namespace.
293 *
294 * @constant DISPATCH_VNODE_WRITE
295 * The filesystem object data changed.
296 *
297 * @constant DISPATCH_VNODE_EXTEND
298 * The filesystem object changed in size.
299 *
300 * @constant DISPATCH_VNODE_ATTRIB
301 * The filesystem object metadata changed.
302 *
303 * @constant DISPATCH_VNODE_LINK
304 * The filesystem object link count changed.
305 *
306 * @constant DISPATCH_VNODE_RENAME
307 * The filesystem object was renamed in the namespace.
308 *
309 * @constant DISPATCH_VNODE_REVOKE
310 * The filesystem object was revoked.
311 *
312 * @constant DISPATCH_VNODE_FUNLOCK
313 * The filesystem object was unlocked.
314 */
315
316#define DISPATCH_VNODE_DELETE 0x1
317#define DISPATCH_VNODE_WRITE 0x2
318#define DISPATCH_VNODE_EXTEND 0x4
319#define DISPATCH_VNODE_ATTRIB 0x8
320#define DISPATCH_VNODE_LINK 0x10
321#define DISPATCH_VNODE_RENAME 0x20
322#define DISPATCH_VNODE_REVOKE 0x40
323#define DISPATCH_VNODE_FUNLOCK 0x100
324
325DISPATCH_SWIFT_UNAVAILABLE("Use DispatchSource.FileSystemEvent")
326typedef unsigned long dispatch_source_vnode_flags_t;
327
328/*!
329 * @typedef dispatch_source_timer_flags_t
330 * Type of dispatch_source_timer flags
331 *
332 * @constant DISPATCH_TIMER_STRICT
333 * Specifies that the system should make a best effort to strictly observe the
334 * leeway value specified for the timer via dispatch_source_set_timer(), even
335 * if that value is smaller than the default leeway value that would be applied
336 * to the timer otherwise. A minimal amount of leeway will be applied to the
337 * timer even if this flag is specified.
338 *
339 * CAUTION: Use of this flag may override power-saving techniques employed by
340 * the system and cause higher power consumption, so it must be used with care
341 * and only when absolutely necessary.
342 */
343
344#define DISPATCH_TIMER_STRICT 0x1
345
346DISPATCH_SWIFT_UNAVAILABLE("Use DispatchSource.TimerFlags")
347typedef unsigned long dispatch_source_timer_flags_t;
348
349/*!
350 * @function dispatch_source_create
351 *
352 * @abstract
353 * Creates a new dispatch source to monitor low-level system objects and auto-
354 * matically submit a handler block to a dispatch queue in response to events.
355 *
356 * @discussion
357 * Dispatch sources are not reentrant. Any events received while the dispatch
358 * source is suspended or while the event handler block is currently executing
359 * will be coalesced and delivered after the dispatch source is resumed or the
360 * event handler block has returned.
361 *
362 * Dispatch sources are created in an inactive state. After creating the
363 * source and setting any desired attributes (i.e. the handler, context, etc.),
364 * a call must be made to dispatch_activate() in order to begin event delivery.
365 *
366 * A source must have been activated before being disposed.
367 *
368 * Calling dispatch_set_target_queue() on a source once it has been activated
369 * is not allowed (see dispatch_activate() and dispatch_set_target_queue()).
370 *
371 * For backward compatibility reasons, dispatch_resume() on an inactive,
372 * and not otherwise suspended source has the same effect as calling
373 * dispatch_activate(). For new code, using dispatch_activate() is preferred.
374 *
375 * @param type
376 * Declares the type of the dispatch source. Must be one of the defined
377 * dispatch_source_type_t constants.
378 *
379 * @param handle
380 * The underlying system handle to monitor. The interpretation of this argument
381 * is determined by the constant provided in the type parameter.
382 *
383 * @param mask
384 * A mask of flags specifying which events are desired. The interpretation of
385 * this argument is determined by the constant provided in the type parameter.
386 *
387 * @param queue
388 * The dispatch queue to which the event handler block will be submitted.
389 * If queue is DISPATCH_TARGET_QUEUE_DEFAULT, the source will submit the event
390 * handler block to the default priority global queue.
391 *
392 * @result
393 * The newly created dispatch source. Or NULL if invalid arguments are passed.
394 */
395API_AVAILABLE(macos(10.6), ios(4.0))
396DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
397DISPATCH_NOTHROW
398DISPATCH_REFINED_FOR_SWIFT
399dispatch_source_t
400dispatch_source_create(dispatch_source_type_t type,
401 uintptr_t handle,
402 uintptr_t mask,
403 dispatch_queue_t _Nullable queue);
404
405/*!
406 * @function dispatch_source_set_event_handler
407 *
408 * @abstract
409 * Sets the event handler block for the given dispatch source.
410 *
411 * @param source
412 * The dispatch source to modify.
413 * The result of passing NULL in this parameter is undefined.
414 *
415 * @param handler
416 * The event handler block to submit to the source's target queue.
417 */
418#ifdef __BLOCKS__
419API_AVAILABLE(macos(10.6), ios(4.0))
420DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
421DISPATCH_REFINED_FOR_SWIFT
422void
423dispatch_source_set_event_handler(dispatch_source_t source,
424 dispatch_block_t _Nullable handler);
425#endif /* __BLOCKS__ */
426
427/*!
428 * @function dispatch_source_set_event_handler_f
429 *
430 * @abstract
431 * Sets the event handler function for the given dispatch source.
432 *
433 * @param source
434 * The dispatch source to modify.
435 * The result of passing NULL in this parameter is undefined.
436 *
437 * @param handler
438 * The event handler function to submit to the source's target queue.
439 * The context parameter passed to the event handler function is the context of
440 * the dispatch source current at the time the event handler was set.
441 */
442API_AVAILABLE(macos(10.6), ios(4.0))
443DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
444DISPATCH_SWIFT_UNAVAILABLE("DispatchSource.setEventHandler(self:handler:)")
445void
446dispatch_source_set_event_handler_f(dispatch_source_t source,
447 dispatch_function_t _Nullable handler);
448
449/*!
450 * @function dispatch_source_set_cancel_handler
451 *
452 * @abstract
453 * Sets the cancellation handler block for the given dispatch source.
454 *
455 * @discussion
456 * The cancellation handler (if specified) will be submitted to the source's
457 * target queue in response to a call to dispatch_source_cancel() once the
458 * system has released all references to the source's underlying handle and
459 * the source's event handler block has returned.
460 *
461 * IMPORTANT:
462 * Source cancellation and a cancellation handler are required for file
463 * descriptor and mach port based sources in order to safely close the
464 * descriptor or destroy the port.
465 * Closing the descriptor or port before the cancellation handler is invoked may
466 * result in a race condition. If a new descriptor is allocated with the same
467 * value as the recently closed descriptor while the source's event handler is
468 * still running, the event handler may read/write data to the wrong descriptor.
469 *
470 * @param source
471 * The dispatch source to modify.
472 * The result of passing NULL in this parameter is undefined.
473 *
474 * @param handler
475 * The cancellation handler block to submit to the source's target queue.
476 */
477#ifdef __BLOCKS__
478API_AVAILABLE(macos(10.6), ios(4.0))
479DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
480DISPATCH_REFINED_FOR_SWIFT
481void
482dispatch_source_set_cancel_handler(dispatch_source_t source,
483 dispatch_block_t _Nullable handler);
484#endif /* __BLOCKS__ */
485
486/*!
487 * @function dispatch_source_set_cancel_handler_f
488 *
489 * @abstract
490 * Sets the cancellation handler function for the given dispatch source.
491 *
492 * @discussion
493 * See dispatch_source_set_cancel_handler() for more details.
494 *
495 * @param source
496 * The dispatch source to modify.
497 * The result of passing NULL in this parameter is undefined.
498 *
499 * @param handler
500 * The cancellation handler function to submit to the source's target queue.
501 * The context parameter passed to the event handler function is the current
502 * context of the dispatch source at the time the handler call is made.
503 */
504API_AVAILABLE(macos(10.6), ios(4.0))
505DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
506DISPATCH_SWIFT_UNAVAILABLE("Use DispatchSource.setCancelHandler(self:handler:)")
507void
508dispatch_source_set_cancel_handler_f(dispatch_source_t source,
509 dispatch_function_t _Nullable handler);
510
511/*!
512 * @function dispatch_source_cancel
513 *
514 * @abstract
515 * Asynchronously cancel the dispatch source, preventing any further invocation
516 * of its event handler block.
517 *
518 * @discussion
519 * Cancellation prevents any further invocation of the event handler block for
520 * the specified dispatch source, but does not interrupt an event handler
521 * block that is already in progress.
522 *
523 * The cancellation handler is submitted to the source's target queue once the
524 * the source's event handler has finished, indicating it is now safe to close
525 * the source's handle (i.e. file descriptor or mach port).
526 *
527 * See dispatch_source_set_cancel_handler() for more information.
528 *
529 * @param source
530 * The dispatch source to be canceled.
531 * The result of passing NULL in this parameter is undefined.
532 */
533API_AVAILABLE(macos(10.6), ios(4.0))
534DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
535DISPATCH_REFINED_FOR_SWIFT
536void
537dispatch_source_cancel(dispatch_source_t source);
538
539/*!
540 * @function dispatch_source_testcancel
541 *
542 * @abstract
543 * Tests whether the given dispatch source has been canceled.
544 *
545 * @param source
546 * The dispatch source to be tested.
547 * The result of passing NULL in this parameter is undefined.
548 *
549 * @result
550 * Non-zero if canceled and zero if not canceled.
551 */
552API_AVAILABLE(macos(10.6), ios(4.0))
553DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
554DISPATCH_NOTHROW
555DISPATCH_REFINED_FOR_SWIFT
556intptr_t
557dispatch_source_testcancel(dispatch_source_t source);
558
559/*!
560 * @function dispatch_source_get_handle
561 *
562 * @abstract
563 * Returns the underlying system handle associated with this dispatch source.
564 *
565 * @param source
566 * The result of passing NULL in this parameter is undefined.
567 *
568 * @result
569 * The return value should be interpreted according to the type of the dispatch
570 * source, and may be one of the following handles:
571 *
572 * DISPATCH_SOURCE_TYPE_DATA_ADD: n/a
573 * DISPATCH_SOURCE_TYPE_DATA_OR: n/a
574 * DISPATCH_SOURCE_TYPE_DATA_REPLACE: n/a
575 * DISPATCH_SOURCE_TYPE_MACH_SEND: mach port (mach_port_t)
576 * DISPATCH_SOURCE_TYPE_MACH_RECV: mach port (mach_port_t)
577 * DISPATCH_SOURCE_TYPE_MEMORYPRESSURE n/a
578 * DISPATCH_SOURCE_TYPE_PROC: process identifier (pid_t)
579 * DISPATCH_SOURCE_TYPE_READ: file descriptor (int)
580 * DISPATCH_SOURCE_TYPE_SIGNAL: signal number (int)
581 * DISPATCH_SOURCE_TYPE_TIMER: n/a
582 * DISPATCH_SOURCE_TYPE_VNODE: file descriptor (int)
583 * DISPATCH_SOURCE_TYPE_WRITE: file descriptor (int)
584 */
585API_AVAILABLE(macos(10.6), ios(4.0))
586DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
587DISPATCH_NOTHROW
588DISPATCH_REFINED_FOR_SWIFT
589uintptr_t
590dispatch_source_get_handle(dispatch_source_t source);
591
592/*!
593 * @function dispatch_source_get_mask
594 *
595 * @abstract
596 * Returns the mask of events monitored by the dispatch source.
597 *
598 * @param source
599 * The result of passing NULL in this parameter is undefined.
600 *
601 * @result
602 * The return value should be interpreted according to the type of the dispatch
603 * source, and may be one of the following flag sets:
604 *
605 * DISPATCH_SOURCE_TYPE_DATA_ADD: n/a
606 * DISPATCH_SOURCE_TYPE_DATA_OR: n/a
607 * DISPATCH_SOURCE_TYPE_DATA_REPLACE: n/a
608 * DISPATCH_SOURCE_TYPE_MACH_SEND: dispatch_source_mach_send_flags_t
609 * DISPATCH_SOURCE_TYPE_MACH_RECV: dispatch_source_mach_recv_flags_t
610 * DISPATCH_SOURCE_TYPE_MEMORYPRESSURE dispatch_source_memorypressure_flags_t
611 * DISPATCH_SOURCE_TYPE_PROC: dispatch_source_proc_flags_t
612 * DISPATCH_SOURCE_TYPE_READ: n/a
613 * DISPATCH_SOURCE_TYPE_SIGNAL: n/a
614 * DISPATCH_SOURCE_TYPE_TIMER: dispatch_source_timer_flags_t
615 * DISPATCH_SOURCE_TYPE_VNODE: dispatch_source_vnode_flags_t
616 * DISPATCH_SOURCE_TYPE_WRITE: n/a
617 */
618API_AVAILABLE(macos(10.6), ios(4.0))
619DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
620DISPATCH_NOTHROW
621DISPATCH_REFINED_FOR_SWIFT
622uintptr_t
623dispatch_source_get_mask(dispatch_source_t source);
624
625/*!
626 * @function dispatch_source_get_data
627 *
628 * @abstract
629 * Returns pending data for the dispatch source.
630 *
631 * @discussion
632 * This function is intended to be called from within the event handler block.
633 * The result of calling this function outside of the event handler callback is
634 * undefined.
635 *
636 * @param source
637 * The result of passing NULL in this parameter is undefined.
638 *
639 * @result
640 * The return value should be interpreted according to the type of the dispatch
641 * source, and may be one of the following:
642 *
643 * DISPATCH_SOURCE_TYPE_DATA_ADD: application defined data
644 * DISPATCH_SOURCE_TYPE_DATA_OR: application defined data
645 * DISPATCH_SOURCE_TYPE_DATA_REPLACE: application defined data
646 * DISPATCH_SOURCE_TYPE_MACH_SEND: dispatch_source_mach_send_flags_t
647 * DISPATCH_SOURCE_TYPE_MACH_RECV: dispatch_source_mach_recv_flags_t
648 * DISPATCH_SOURCE_TYPE_MEMORYPRESSURE dispatch_source_memorypressure_flags_t
649 * DISPATCH_SOURCE_TYPE_PROC: dispatch_source_proc_flags_t
650 * DISPATCH_SOURCE_TYPE_READ: estimated bytes available to read
651 * DISPATCH_SOURCE_TYPE_SIGNAL: number of signals delivered since
652 * the last handler invocation
653 * DISPATCH_SOURCE_TYPE_TIMER: number of times the timer has fired
654 * since the last handler invocation
655 * DISPATCH_SOURCE_TYPE_VNODE: dispatch_source_vnode_flags_t
656 * DISPATCH_SOURCE_TYPE_WRITE: estimated buffer space available
657 */
658API_AVAILABLE(macos(10.6), ios(4.0))
659DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
660DISPATCH_NOTHROW
661DISPATCH_REFINED_FOR_SWIFT
662uintptr_t
663dispatch_source_get_data(dispatch_source_t source);
664
665/*!
666 * @function dispatch_source_merge_data
667 *
668 * @abstract
669 * Merges data into a dispatch source of type DISPATCH_SOURCE_TYPE_DATA_ADD,
670 * DISPATCH_SOURCE_TYPE_DATA_OR or DISPATCH_SOURCE_TYPE_DATA_REPLACE,
671 * and submits its event handler block to its target queue.
672 *
673 * @param source
674 * The result of passing NULL in this parameter is undefined.
675 *
676 * @param value
677 * The value to coalesce with the pending data using a logical OR or an ADD
678 * as specified by the dispatch source type. A value of zero has no effect
679 * and will not result in the submission of the event handler block.
680 */
681API_AVAILABLE(macos(10.6), ios(4.0))
682DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
683DISPATCH_REFINED_FOR_SWIFT
684void
685dispatch_source_merge_data(dispatch_source_t source, uintptr_t value);
686
687/*!
688 * @function dispatch_source_set_timer
689 *
690 * @abstract
691 * Sets a start time, interval, and leeway value for a timer source.
692 *
693 * @discussion
694 * Once this function returns, any pending source data accumulated for the
695 * previous timer values has been cleared; the next fire of the timer will
696 * occur at 'start', and every 'interval' nanoseconds thereafter until the
697 * timer source is canceled.
698 *
699 * Any fire of the timer may be delayed by the system in order to improve power
700 * consumption and system performance. The upper limit to the allowable delay
701 * may be configured with the 'leeway' argument, the lower limit is under the
702 * control of the system.
703 *
704 * For the initial timer fire at 'start', the upper limit to the allowable
705 * delay is set to 'leeway' nanoseconds. For the subsequent timer fires at
706 * 'start' + N * 'interval', the upper limit is MIN('leeway','interval'/2).
707 *
708 * The lower limit to the allowable delay may vary with process state such as
709 * visibility of application UI. If the specified timer source was created with
710 * a mask of DISPATCH_TIMER_STRICT, the system will make a best effort to
711 * strictly observe the provided 'leeway' value even if it is smaller than the
712 * current lower limit. Note that a minimal amount of delay is to be expected
713 * even if this flag is specified.
714 *
715 * The 'start' argument also determines which clock will be used for the timer:
716 * If 'start' is DISPATCH_TIME_NOW or was created with dispatch_time(3), the
717 * timer is based on up time (which is obtained from mach_absolute_time() on
718 * Apple platforms). If 'start' was created with dispatch_walltime(3), the
719 * timer is based on gettimeofday(3).
720 *
721 * Calling this function has no effect if the timer source has already been
722 * canceled.
723 *
724 * @param start
725 * The start time of the timer. See dispatch_time() and dispatch_walltime()
726 * for more information.
727 *
728 * @param interval
729 * The nanosecond interval for the timer. Use DISPATCH_TIME_FOREVER for a
730 * one-shot timer.
731 *
732 * @param leeway
733 * The nanosecond leeway for the timer.
734 */
735API_AVAILABLE(macos(10.6), ios(4.0))
736DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
737DISPATCH_REFINED_FOR_SWIFT
738void
739dispatch_source_set_timer(dispatch_source_t source,
740 dispatch_time_t start,
741 uint64_t interval,
742 uint64_t leeway);
743
744/*!
745 * @function dispatch_source_set_registration_handler
746 *
747 * @abstract
748 * Sets the registration handler block for the given dispatch source.
749 *
750 * @discussion
751 * The registration handler (if specified) will be submitted to the source's
752 * target queue once the corresponding kevent() has been registered with the
753 * system, following the initial dispatch_resume() of the source.
754 *
755 * If a source is already registered when the registration handler is set, the
756 * registration handler will be invoked immediately.
757 *
758 * @param source
759 * The dispatch source to modify.
760 * The result of passing NULL in this parameter is undefined.
761 *
762 * @param handler
763 * The registration handler block to submit to the source's target queue.
764 */
765#ifdef __BLOCKS__
766API_AVAILABLE(macos(10.7), ios(4.3))
767DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
768DISPATCH_REFINED_FOR_SWIFT
769void
770dispatch_source_set_registration_handler(dispatch_source_t source,
771 dispatch_block_t _Nullable handler);
772#endif /* __BLOCKS__ */
773
774/*!
775 * @function dispatch_source_set_registration_handler_f
776 *
777 * @abstract
778 * Sets the registration handler function for the given dispatch source.
779 *
780 * @discussion
781 * See dispatch_source_set_registration_handler() for more details.
782 *
783 * @param source
784 * The dispatch source to modify.
785 * The result of passing NULL in this parameter is undefined.
786 *
787 * @param handler
788 * The registration handler function to submit to the source's target queue.
789 * The context parameter passed to the registration handler function is the
790 * current context of the dispatch source at the time the handler call is made.
791 */
792API_AVAILABLE(macos(10.7), ios(4.3))
793DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
794DISPATCH_SWIFT_UNAVAILABLE("Use DispatchSource.setRegistrationHandler(self:handler:)")
795void
796dispatch_source_set_registration_handler_f(dispatch_source_t source,
797 dispatch_function_t _Nullable handler);
798
799__END_DECLS
800
801DISPATCH_ASSUME_ABI_SINGLE_END
802DISPATCH_ASSUME_NONNULL_END
803
804#endif