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