dispatch/source.h

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