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