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