source.h (29441B) - Raw
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 38 DISPATCH_ASSUME_NONNULL_BEGIN 39 DISPATCH_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 */ 58 DISPATCH_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 */ 73 DISPATCH_REFINED_FOR_SWIFT 74 typedef 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) 84 API_AVAILABLE(macos(10.6), ios(4.0)) 85 DISPATCH_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) 95 API_AVAILABLE(macos(10.6), ios(4.0)) 96 DISPATCH_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) 110 API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0)) 111 DISPATCH_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) 121 API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE() 122 DISPATCH_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) 132 API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE() 133 DISPATCH_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) 145 API_AVAILABLE(macos(10.9), ios(8.0)) DISPATCH_LINUX_UNAVAILABLE() 146 DISPATCH_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) 156 API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE() 157 DISPATCH_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) 167 API_AVAILABLE(macos(10.6), ios(4.0)) 168 DISPATCH_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) 177 API_AVAILABLE(macos(10.6), ios(4.0)) 178 DISPATCH_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) 188 API_AVAILABLE(macos(10.6), ios(4.0)) 189 DISPATCH_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) 199 API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE() 200 DISPATCH_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) 210 API_AVAILABLE(macos(10.6), ios(4.0)) 211 DISPATCH_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 222 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchSource.MachSendEvent") 223 typedef 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 */ 229 typedef 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 259 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchSource.MemoryPressureEvent") 260 typedef 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 284 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchSource.ProcessEvent") 285 typedef 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 325 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchSource.FileSystemEvent") 326 typedef 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 346 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchSource.TimerFlags") 347 typedef 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 */ 395 API_AVAILABLE(macos(10.6), ios(4.0)) 396 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT 397 DISPATCH_NOTHROW 398 DISPATCH_REFINED_FOR_SWIFT 399 dispatch_source_t 400 dispatch_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__ 419 API_AVAILABLE(macos(10.6), ios(4.0)) 420 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW 421 DISPATCH_REFINED_FOR_SWIFT 422 void 423 dispatch_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 */ 442 API_AVAILABLE(macos(10.6), ios(4.0)) 443 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW 444 DISPATCH_SWIFT_UNAVAILABLE("DispatchSource.setEventHandler(self:handler:)") 445 void 446 dispatch_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__ 478 API_AVAILABLE(macos(10.6), ios(4.0)) 479 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW 480 DISPATCH_REFINED_FOR_SWIFT 481 void 482 dispatch_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 */ 504 API_AVAILABLE(macos(10.6), ios(4.0)) 505 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW 506 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchSource.setCancelHandler(self:handler:)") 507 void 508 dispatch_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 */ 533 API_AVAILABLE(macos(10.6), ios(4.0)) 534 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW 535 DISPATCH_REFINED_FOR_SWIFT 536 void 537 dispatch_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 */ 552 API_AVAILABLE(macos(10.6), ios(4.0)) 553 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE 554 DISPATCH_NOTHROW 555 DISPATCH_REFINED_FOR_SWIFT 556 intptr_t 557 dispatch_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 */ 585 API_AVAILABLE(macos(10.6), ios(4.0)) 586 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE 587 DISPATCH_NOTHROW 588 DISPATCH_REFINED_FOR_SWIFT 589 uintptr_t 590 dispatch_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 */ 618 API_AVAILABLE(macos(10.6), ios(4.0)) 619 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE 620 DISPATCH_NOTHROW 621 DISPATCH_REFINED_FOR_SWIFT 622 uintptr_t 623 dispatch_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 */ 658 API_AVAILABLE(macos(10.6), ios(4.0)) 659 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE 660 DISPATCH_NOTHROW 661 DISPATCH_REFINED_FOR_SWIFT 662 uintptr_t 663 dispatch_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 */ 681 API_AVAILABLE(macos(10.6), ios(4.0)) 682 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW 683 DISPATCH_REFINED_FOR_SWIFT 684 void 685 dispatch_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 */ 735 API_AVAILABLE(macos(10.6), ios(4.0)) 736 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW 737 DISPATCH_REFINED_FOR_SWIFT 738 void 739 dispatch_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__ 766 API_AVAILABLE(macos(10.7), ios(4.3)) 767 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW 768 DISPATCH_REFINED_FOR_SWIFT 769 void 770 dispatch_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 */ 792 API_AVAILABLE(macos(10.7), ios(4.3)) 793 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW 794 DISPATCH_SWIFT_UNAVAILABLE("Use DispatchSource.setRegistrationHandler(self:handler:)") 795 void 796 dispatch_source_set_registration_handler_f(dispatch_source_t source, 797 dispatch_function_t _Nullable handler); 798 799 __END_DECLS 800 801 DISPATCH_ASSUME_ABI_SINGLE_END 802 DISPATCH_ASSUME_NONNULL_END 803 804 #endif