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_RETURNS_RETAINED DISPATCH_WARN_RESULT
 292 DISPATCH_NOTHROW
 293 dispatch_source_t
 294 dispatch_source_create(dispatch_source_type_t type,
 295         uintptr_t handle,
 296         unsigned long mask,
 297         dispatch_queue_t queue);
 298
 299 /*!
 300  * @function dispatch_source_set_event_handler
 301  *
 302  * @abstract
 303  * Sets the event handler block for the given dispatch source.
 304  *
 305  * @param source
 306  * The dispatch source to modify.
 307  * The result of passing NULL in this parameter is undefined.
 308  *
 309  * @param handler
 310  * The event handler block to submit to the source's target queue.
 311  */
 312 #ifdef __BLOCKS__
 313 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 314 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 315 void
 316 dispatch_source_set_event_handler(dispatch_source_t source,
 317         dispatch_block_t handler);
 318 #endif /* __BLOCKS__ */
 319
 320 /*!
 321  * @function dispatch_source_set_event_handler_f
 322  *
 323  * @abstract
 324  * Sets the event handler function for the given dispatch source.
 325  *
 326  * @param source
 327  * The dispatch source to modify.
 328  * The result of passing NULL in this parameter is undefined.
 329  *
 330  * @param handler
 331  * The event handler function to submit to the source's target queue.
 332  * The context parameter passed to the event handler function is the current
 333  * context of the dispatch source at the time the handler call is made.
 334  * The result of passing NULL in this parameter is undefined.
 335  */
 336 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 337 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 338 void
 339 dispatch_source_set_event_handler_f(dispatch_source_t source,
 340         dispatch_function_t handler);
 341
 342 /*!
 343  * @function dispatch_source_set_cancel_handler
 344  *
 345  * @abstract
 346  * Sets the cancellation handler block for the given dispatch source.
 347  *
 348  * @discussion
 349  * The cancellation handler (if specified) will be submitted to the source's
 350  * target queue in response to a call to dispatch_source_cancel() once the
 351  * system has released all references to the source's underlying handle and
 352  * the source's event handler block has returned.
 353  *
 354  * IMPORTANT:
 355  * A cancellation handler is required for file descriptor and mach port based
 356  * sources in order to safely close the descriptor or destroy the port. Closing
 357  * the descriptor or port before the cancellation handler may result in a race
 358  * condition. If a new descriptor is allocated with the same value as the
 359  * recently closed descriptor while the source's event handler is still running,
 360  * the event handler may read/write data to the wrong descriptor.
 361  *
 362  * @param source
 363  * The dispatch source to modify.
 364  * The result of passing NULL in this parameter is undefined.
 365  *
 366  * @param handler
 367  * The cancellation handler block to submit to the source's target queue.
 368  */
 369 #ifdef __BLOCKS__
 370 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 371 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 372 void
 373 dispatch_source_set_cancel_handler(dispatch_source_t source,
 374         dispatch_block_t cancel_handler);
 375 #endif /* __BLOCKS__ */
 376
 377 /*!
 378  * @function dispatch_source_set_cancel_handler_f
 379  *
 380  * @abstract
 381  * Sets the cancellation handler function for the given dispatch source.
 382  *
 383  * @discussion
 384  * See dispatch_source_set_cancel_handler() for more details.
 385  *
 386  * @param source
 387  * The dispatch source to modify.
 388  * The result of passing NULL in this parameter is undefined.
 389  *
 390  * @param handler
 391  * The cancellation handler function to submit to the source's target queue.
 392  * The context parameter passed to the event handler function is the current
 393  * context of the dispatch source at the time the handler call is made.
 394  */
 395 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 396 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 397 void
 398 dispatch_source_set_cancel_handler_f(dispatch_source_t source,
 399         dispatch_function_t cancel_handler);
 400
 401 /*!
 402  * @function dispatch_source_cancel
 403  *
 404  * @abstract
 405  * Asynchronously cancel the dispatch source, preventing any further invocation
 406  * of its event handler block.
 407  *
 408  * @discussion
 409  * Cancellation prevents any further invocation of the event handler block for
 410  * the specified dispatch source, but does not interrupt an event handler
 411  * block that is already in progress.
 412  *
 413  * The cancellation handler is submitted to the source's target queue once the
 414  * the source's event handler has finished, indicating it is now safe to close
 415  * the source's handle (i.e. file descriptor or mach port).
 416  *
 417  * See dispatch_source_set_cancel_handler() for more information.
 418  *
 419  * @param source
 420  * The dispatch source to be canceled.
 421  * The result of passing NULL in this parameter is undefined.
 422  */
 423 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 424 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 425 void
 426 dispatch_source_cancel(dispatch_source_t source);
 427
 428 /*!
 429  * @function dispatch_source_testcancel
 430  *
 431  * @abstract
 432  * Tests whether the given dispatch source has been canceled.
 433  *
 434  * @param source
 435  * The dispatch source to be tested.
 436  * The result of passing NULL in this parameter is undefined.
 437  *
 438  * @result
 439  * Non-zero if canceled and zero if not canceled.
 440  */
 441 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 442 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 443 DISPATCH_NOTHROW
 444 long
 445 dispatch_source_testcancel(dispatch_source_t source);
 446
 447 /*!
 448  * @function dispatch_source_get_handle
 449  *
 450  * @abstract
 451  * Returns the underlying system handle associated with this dispatch source.
 452  *
 453  * @param source
 454  * The result of passing NULL in this parameter is undefined.
 455  *
 456  * @result
 457  * The return value should be interpreted according to the type of the dispatch
 458  * source, and may be one of the following handles:
 459  *
 460  *  DISPATCH_SOURCE_TYPE_DATA_ADD:        n/a
 461  *  DISPATCH_SOURCE_TYPE_DATA_OR:         n/a
 462  *  DISPATCH_SOURCE_TYPE_MACH_SEND:       mach port (mach_port_t)
 463  *  DISPATCH_SOURCE_TYPE_MACH_RECV:       mach port (mach_port_t)
 464  *  DISPATCH_SOURCE_TYPE_PROC:            process identifier (pid_t)
 465  *  DISPATCH_SOURCE_TYPE_READ:            file descriptor (int)
 466  *  DISPATCH_SOURCE_TYPE_SIGNAL:          signal number (int)
 467  *  DISPATCH_SOURCE_TYPE_TIMER:           n/a
 468  *  DISPATCH_SOURCE_TYPE_VNODE:           file descriptor (int)
 469  *  DISPATCH_SOURCE_TYPE_WRITE:           file descriptor (int)
 470  */
 471 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 472 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 473 DISPATCH_NOTHROW
 474 uintptr_t
 475 dispatch_source_get_handle(dispatch_source_t source);
 476
 477 /*!
 478  * @function dispatch_source_get_mask
 479  *
 480  * @abstract
 481  * Returns the mask of events monitored by the dispatch source.
 482  *
 483  * @param source
 484  * The result of passing NULL in this parameter is undefined.
 485  *
 486  * @result
 487  * The return value should be interpreted according to the type of the dispatch
 488  * source, and may be one of the following flag sets:
 489  *
 490  *  DISPATCH_SOURCE_TYPE_DATA_ADD:        n/a
 491  *  DISPATCH_SOURCE_TYPE_DATA_OR:         n/a
 492  *  DISPATCH_SOURCE_TYPE_MACH_SEND:       dispatch_source_mach_send_flags_t
 493  *  DISPATCH_SOURCE_TYPE_MACH_RECV:       n/a
 494  *  DISPATCH_SOURCE_TYPE_PROC:            dispatch_source_proc_flags_t
 495  *  DISPATCH_SOURCE_TYPE_READ:            n/a
 496  *  DISPATCH_SOURCE_TYPE_SIGNAL:          n/a
 497  *  DISPATCH_SOURCE_TYPE_TIMER:           n/a
 498  *  DISPATCH_SOURCE_TYPE_VNODE:           dispatch_source_vnode_flags_t
 499  *  DISPATCH_SOURCE_TYPE_WRITE:           n/a
 500  */
 501 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 502 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 503 DISPATCH_NOTHROW
 504 unsigned long
 505 dispatch_source_get_mask(dispatch_source_t source);
 506
 507 /*!
 508  * @function dispatch_source_get_data
 509  *
 510  * @abstract
 511  * Returns pending data for the dispatch source.
 512  *
 513  * @discussion
 514  * This function is intended to be called from within the event handler block.
 515  * The result of calling this function outside of the event handler callback is
 516  * undefined.
 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:
 524  *
 525  *  DISPATCH_SOURCE_TYPE_DATA_ADD:        application defined data
 526  *  DISPATCH_SOURCE_TYPE_DATA_OR:         application defined data
 527  *  DISPATCH_SOURCE_TYPE_MACH_SEND:       dispatch_source_mach_send_flags_t
 528  *  DISPATCH_SOURCE_TYPE_MACH_RECV:       n/a
 529  *  DISPATCH_SOURCE_TYPE_PROC:            dispatch_source_proc_flags_t
 530  *  DISPATCH_SOURCE_TYPE_READ:            estimated bytes available to read
 531  *  DISPATCH_SOURCE_TYPE_SIGNAL:          number of signals delivered since
 532  *                                            the last handler invocation
 533  *  DISPATCH_SOURCE_TYPE_TIMER:           number of times the timer has fired
 534  *                                            since the last handler invocation
 535  *  DISPATCH_SOURCE_TYPE_VNODE:           dispatch_source_vnode_flags_t
 536  *  DISPATCH_SOURCE_TYPE_WRITE:           estimated buffer space available
 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 unsigned long
 542 dispatch_source_get_data(dispatch_source_t source);
 543
 544 /*!
 545  * @function dispatch_source_merge_data
 546  *
 547  * @abstract
 548  * Merges data into a dispatch source of type DISPATCH_SOURCE_TYPE_DATA_ADD or
 549  * DISPATCH_SOURCE_TYPE_DATA_OR and submits its event handler block to its
 550  * target queue.
 551  *
 552  * @param source
 553  * The result of passing NULL in this parameter is undefined.
 554  *
 555  * @param value
 556  * The value to coalesce with the pending data using a logical OR or an ADD
 557  * as specified by the dispatch source type. A value of zero has no effect
 558  * and will not result in the submission of the event handler block.
 559  */
 560 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 561 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 562 void
 563 dispatch_source_merge_data(dispatch_source_t source, unsigned long value);
 564
 565 /*!
 566  * @function dispatch_source_set_timer
 567  *
 568  * @abstract
 569  * Sets a start time, interval, and leeway value for a timer source.
 570  *
 571  * @discussion
 572  * Calling this function has no effect if the timer source has already been
 573  * canceled. Once this function returns, any pending timer data accumulated
 574  * for the previous timer values has been cleared
 575  *
 576  * The start time argument also determines which clock will be used for the
 577  * timer. If the start time is DISPATCH_TIME_NOW or created with
 578  * dispatch_time() then the timer is based on mach_absolute_time(). Otherwise,
 579  * if the start time of the timer is created with dispatch_walltime() then the
 580  * timer is based on gettimeofday(3).
 581  *
 582  * @param start
 583  * The start time of the timer. See dispatch_time() and dispatch_walltime()
 584  * for more information.
 585  *
 586  * @param interval
 587  * The nanosecond interval for the timer.
 588  *
 589  * @param leeway
 590  * A hint given to the system by the application for the amount of leeway, in
 591  * nanoseconds, that the system may defer the timer in order to align with other
 592  * system activity for improved system performance or power consumption. (For
 593  * example, an application might perform a periodic task every 5 minutes, with
 594  * a leeway of up to 30 seconds.)  Note that some latency is to be expected for
 595  * all timers even when a leeway value of zero is specified.
 596  */
 597 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 598 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 599 void
 600 dispatch_source_set_timer(dispatch_source_t source,
 601         dispatch_time_t start,
 602         uint64_t interval,
 603         uint64_t leeway);
 604
 605 /*!
 606  * @function dispatch_source_set_registration_handler
 607  *
 608  * @abstract
 609  * Sets the registration handler block for the given dispatch source.
 610  *
 611  * @discussion
 612  * The registration handler (if specified) will be submitted to the source's
 613  * target queue once the corresponding kevent() has been registered with the
 614  * system, following the initial dispatch_resume() of the source.
 615  *
 616  * If a source is already registered when the registration handler is set, the
 617  * registration handler will be invoked immediately.
 618  *
 619  * @param source
 620  * The dispatch source to modify.
 621  * The result of passing NULL in this parameter is undefined.
 622  *
 623  * @param handler
 624  * The registration handler block to submit to the source's target queue.
 625  */
 626 #ifdef __BLOCKS__
 627 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_4_3)
 628 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 629 void
 630 dispatch_source_set_registration_handler(dispatch_source_t source,
 631         dispatch_block_t registration_handler);
 632 #endif /* __BLOCKS__ */
 633
 634 /*!
 635  * @function dispatch_source_set_registration_handler_f
 636  *
 637  * @abstract
 638  * Sets the registration handler function for the given dispatch source.
 639  *
 640  * @discussion
 641  * See dispatch_source_set_registration_handler() for more details.
 642  *
 643  * @param source
 644  * The dispatch source to modify.
 645  * The result of passing NULL in this parameter is undefined.
 646  *
 647  * @param handler
 648  * The registration handler function to submit to the source's target queue.
 649  * The context parameter passed to the registration handler function is the
 650  * current context of the dispatch source at the time the handler call is made.
 651  */
 652 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_4_3)
 653 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 654 void
 655 dispatch_source_set_registration_handler_f(dispatch_source_t source,
 656         dispatch_function_t registration_handler);
 657
 658 __END_DECLS
 659
 660 #endif