dispatch/source.h

   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  */
  55 DISPATCH_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  */
  68 typedef 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)
  89 DISPATCH_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)
 100 DISPATCH_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)
 111 DISPATCH_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)
 121 DISPATCH_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)
 134 DISPATCH_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)
 145 DISPATCH_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)
 156 DISPATCH_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)
 166 DISPATCH_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)
 177 DISPATCH_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)
 188 DISPATCH_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)
 199 DISPATCH_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
 210 typedef 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
 240 typedef 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
 264 typedef 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
 300 typedef 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
 320 typedef 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)
 356 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 357 DISPATCH_NOTHROW
 358 dispatch_source_t
 359 dispatch_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)
 379 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 380 void
 381 dispatch_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)
 402 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 403 void
 404 dispatch_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)
 436 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 437 void
 438 dispatch_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)
 461 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 462 void
 463 dispatch_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)
 489 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 490 void
 491 dispatch_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)
 507 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 508 DISPATCH_NOTHROW
 509 long
 510 dispatch_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)
 538 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 539 DISPATCH_NOTHROW
 540 uintptr_t
 541 dispatch_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)
 569 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 570 DISPATCH_NOTHROW
 571 unsigned long
 572 dispatch_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)
 607 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 608 DISPATCH_NOTHROW
 609 unsigned long
 610 dispatch_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)
 629 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 630 void
 631 dispatch_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)
 681 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 682 void
 683 dispatch_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)
 711 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 712 void
 713 dispatch_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)
 736 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 737 void
 738 dispatch_source_set_registration_handler_f(dispatch_source_t source,
 739         dispatch_function_t registration_handler);
 740
 741 __END_DECLS
 742
 743 #endif