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