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