text: /*
   * Copyright (c) 2008-2013 Apple Inc. All rights reserved.
   *
   * @APPLE_APACHE_LICENSE_HEADER_START@
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *     http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   *
   * @APPLE_APACHE_LICENSE_HEADER_END@
   */
  
  #ifndef __DISPATCH_SOURCE__
  #define __DISPATCH_SOURCE__
  
  #ifndef __DISPATCH_INDIRECT__
  #error "Please #include <dispatch/dispatch.h> instead of this file directly."
  #include <dispatch/base.h> // for HeaderDoc
  #endif
  
  #if TARGET_OS_MAC
  #include <mach/port.h>
  #include <mach/message.h>
  #endif
  
  #if !defined(_WIN32)
  #include <sys/signal.h>
  #endif
  
  DISPATCH_ASSUME_NONNULL_BEGIN
  
  /*!
   * @header
   * The dispatch framework provides a suite of interfaces for monitoring low-
   * level system objects (file descriptors, Mach ports, signals, VFS nodes, etc.)
   * for activity and automatically submitting event handler blocks to dispatch
   * queues when such activity occurs.
   *
   * This suite of interfaces is known as the Dispatch Source API.
   */
  
  /*!
   * @typedef dispatch_source_t
   *
   * @abstract
   * Dispatch sources are used to automatically submit event handler blocks to
   * dispatch queues in response to external events.
   */
  DISPATCH_SOURCE_DECL(dispatch_source);
  
  __BEGIN_DECLS
  
  /*!
   * @typedef dispatch_source_type_t
   *
   * @abstract
   * Constants of this type represent the class of low-level system object that
   * is being monitored by the dispatch source. Constants of this type are
   * passed as a parameter to dispatch_source_create() and determine how the
   * handle argument is interpreted (i.e. as a file descriptor, mach port,
   * signal number, process identifier, etc.), and how the mask argument is
   * interpreted.
   */
  typedef const struct dispatch_source_type_s *dispatch_source_type_t;
  
  /*!
   * @const DISPATCH_SOURCE_TYPE_DATA_ADD
   * @discussion A dispatch source that coalesces data obtained via calls to
   * dispatch_source_merge_data(). An ADD is used to coalesce the data.
   * The handle is unused (pass zero for now).
   * The mask is unused (pass zero for now).
   */
  #define DISPATCH_SOURCE_TYPE_DATA_ADD (&_dispatch_source_type_data_add)
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_SOURCE_TYPE_DECL(data_add);
  
  /*!
   * @const DISPATCH_SOURCE_TYPE_DATA_OR
   * @discussion A dispatch source that coalesces data obtained via calls to
   * dispatch_source_merge_data(). A bitwise OR is used to coalesce the data.
   * The handle is unused (pass zero for now).
   * The mask is unused (pass zero for now).
   */
  #define DISPATCH_SOURCE_TYPE_DATA_OR (&_dispatch_source_type_data_or)
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_SOURCE_TYPE_DECL(data_or);
  
  /*!
   * @const DISPATCH_SOURCE_TYPE_DATA_REPLACE
   * @discussion A dispatch source that tracks data obtained via calls to
   * dispatch_source_merge_data(). Newly obtained data values replace existing
   * data values not yet delivered to the source handler
   *
   * A data value of zero will cause the source handler to not be invoked.
   *
   * The handle is unused (pass zero for now).
   * The mask is unused (pass zero for now).
   */
  #define DISPATCH_SOURCE_TYPE_DATA_REPLACE (&_dispatch_source_type_data_replace)
  API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
  DISPATCH_SOURCE_TYPE_DECL(data_replace);
  
  /*!
   * @const DISPATCH_SOURCE_TYPE_MACH_SEND
   * @discussion A dispatch source that monitors a Mach port for dead name
   * notifications (send right no longer has any corresponding receive right).
   * The handle is a Mach port with a send or send-once right (mach_port_t).
   * The mask is a mask of desired events from dispatch_source_mach_send_flags_t.
   */
  #define DISPATCH_SOURCE_TYPE_MACH_SEND (&_dispatch_source_type_mach_send)
  API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
  DISPATCH_SOURCE_TYPE_DECL(mach_send);
  
  /*!
   * @const DISPATCH_SOURCE_TYPE_MACH_RECV
   * @discussion A dispatch source that monitors a Mach port for pending messages.
   * The handle is a Mach port with a receive right (mach_port_t).
   * The mask is unused (pass zero for now).
   */
  #define DISPATCH_SOURCE_TYPE_MACH_RECV (&_dispatch_source_type_mach_recv)
  API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
  DISPATCH_SOURCE_TYPE_DECL(mach_recv);
  
  /*!
   * @const DISPATCH_SOURCE_TYPE_MEMORYPRESSURE
   * @discussion A dispatch source that monitors the system for changes in
   * memory pressure condition.
   * The handle is unused (pass zero for now).
   * The mask is a mask of desired events from
   * dispatch_source_memorypressure_flags_t.
   */
  #define DISPATCH_SOURCE_TYPE_MEMORYPRESSURE \
  		(&_dispatch_source_type_memorypressure)
  API_AVAILABLE(macos(10.9), ios(8.0)) DISPATCH_LINUX_UNAVAILABLE()
  DISPATCH_SOURCE_TYPE_DECL(memorypressure);
  
  /*!
   * @const DISPATCH_SOURCE_TYPE_PROC
   * @discussion A dispatch source that monitors an external process for events
   * defined by dispatch_source_proc_flags_t.
   * The handle is a process identifier (pid_t).
   * The mask is a mask of desired events from dispatch_source_proc_flags_t.
   */
  #define DISPATCH_SOURCE_TYPE_PROC (&_dispatch_source_type_proc)
  API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
  DISPATCH_SOURCE_TYPE_DECL(proc);
  
  /*!
   * @const DISPATCH_SOURCE_TYPE_READ
   * @discussion A dispatch source that monitors a file descriptor for pending
   * bytes available to be read.
   * The handle is a file descriptor (int).
   * The mask is unused (pass zero for now).
   */
  #define DISPATCH_SOURCE_TYPE_READ (&_dispatch_source_type_read)
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_SOURCE_TYPE_DECL(read);
  
  /*!
   * @const DISPATCH_SOURCE_TYPE_SIGNAL
   * @discussion A dispatch source that monitors the current process for signals.
   * The handle is a signal number (int).
   * The mask is unused (pass zero for now).
   */
  #define DISPATCH_SOURCE_TYPE_SIGNAL (&_dispatch_source_type_signal)
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_SOURCE_TYPE_DECL(signal);
  
  /*!
   * @const DISPATCH_SOURCE_TYPE_TIMER
   * @discussion A dispatch source that submits the event handler block based
   * on a timer.
   * The handle is unused (pass zero for now).
   * The mask specifies which flags from dispatch_source_timer_flags_t to apply.
   */
  #define DISPATCH_SOURCE_TYPE_TIMER (&_dispatch_source_type_timer)
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_SOURCE_TYPE_DECL(timer);
  
  /*!
   * @const DISPATCH_SOURCE_TYPE_VNODE
   * @discussion A dispatch source that monitors a file descriptor for events
   * defined by dispatch_source_vnode_flags_t.
   * The handle is a file descriptor (int).
   * The mask is a mask of desired events from dispatch_source_vnode_flags_t.
   */
  #define DISPATCH_SOURCE_TYPE_VNODE (&_dispatch_source_type_vnode)
  API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
  DISPATCH_SOURCE_TYPE_DECL(vnode);
  
  /*!
   * @const DISPATCH_SOURCE_TYPE_WRITE
   * @discussion A dispatch source that monitors a file descriptor for available
   * buffer space to write bytes.
   * The handle is a file descriptor (int).
   * The mask is unused (pass zero for now).
   */
  #define DISPATCH_SOURCE_TYPE_WRITE (&_dispatch_source_type_write)
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_SOURCE_TYPE_DECL(write);
  
  /*!
   * @typedef dispatch_source_mach_send_flags_t
   * Type of dispatch_source_mach_send flags
   *
   * @constant DISPATCH_MACH_SEND_DEAD
   * The receive right corresponding to the given send right was destroyed.
   */
  #define DISPATCH_MACH_SEND_DEAD	0x1
  
  typedef unsigned long dispatch_source_mach_send_flags_t;
  
  /*!
   * @typedef dispatch_source_memorypressure_flags_t
   * Type of dispatch_source_memorypressure flags
   *
   * @constant DISPATCH_MEMORYPRESSURE_NORMAL
   * The system memory pressure condition has returned to normal.
   *
   * @constant DISPATCH_MEMORYPRESSURE_WARN
   * The system memory pressure condition has changed to warning.
   *
   * @constant DISPATCH_MEMORYPRESSURE_CRITICAL
   * The system memory pressure condition has changed to critical.
   *
   * @discussion
   * Elevated memory pressure is a system-wide condition that applications
   * registered for this source should react to by changing their future memory
   * use behavior, e.g. by reducing cache sizes of newly initiated operations
   * until memory pressure returns back to normal.
   * NOTE: applications should NOT traverse and discard existing caches for past
   * operations when the system memory pressure enters an elevated state, as that
   * is likely to trigger VM operations that will further aggravate system memory
   * pressure.
   */
  
  #define DISPATCH_MEMORYPRESSURE_NORMAL		0x01
  #define DISPATCH_MEMORYPRESSURE_WARN		0x02
  #define DISPATCH_MEMORYPRESSURE_CRITICAL	0x04
  
  typedef unsigned long dispatch_source_memorypressure_flags_t;
  
  /*!
   * @typedef dispatch_source_proc_flags_t
   * Type of dispatch_source_proc flags
   *
   * @constant DISPATCH_PROC_EXIT
   * The process has exited (perhaps cleanly, perhaps not).
   *
   * @constant DISPATCH_PROC_FORK
   * The process has created one or more child processes.
   *
   * @constant DISPATCH_PROC_EXEC
   * The process has become another executable image via
   * exec*() or posix_spawn*().
   *
   * @constant DISPATCH_PROC_SIGNAL
   * A Unix signal was delivered to the process.
   */
  #define DISPATCH_PROC_EXIT		0x80000000
  #define DISPATCH_PROC_FORK		0x40000000
  #define DISPATCH_PROC_EXEC		0x20000000
  #define DISPATCH_PROC_SIGNAL	0x08000000
  
  typedef unsigned long dispatch_source_proc_flags_t;
  
  /*!
   * @typedef dispatch_source_vnode_flags_t
   * Type of dispatch_source_vnode flags
   *
   * @constant DISPATCH_VNODE_DELETE
   * The filesystem object was deleted from the namespace.
   *
   * @constant DISPATCH_VNODE_WRITE
   * The filesystem object data changed.
   *
   * @constant DISPATCH_VNODE_EXTEND
   * The filesystem object changed in size.
   *
   * @constant DISPATCH_VNODE_ATTRIB
   * The filesystem object metadata changed.
   *
   * @constant DISPATCH_VNODE_LINK
   * The filesystem object link count changed.
   *
   * @constant DISPATCH_VNODE_RENAME
   * The filesystem object was renamed in the namespace.
   *
   * @constant DISPATCH_VNODE_REVOKE
   * The filesystem object was revoked.
   *
   * @constant DISPATCH_VNODE_FUNLOCK
   * The filesystem object was unlocked.
   */
  
  #define DISPATCH_VNODE_DELETE	0x1
  #define DISPATCH_VNODE_WRITE	0x2
  #define DISPATCH_VNODE_EXTEND	0x4
  #define DISPATCH_VNODE_ATTRIB	0x8
  #define DISPATCH_VNODE_LINK		0x10
  #define DISPATCH_VNODE_RENAME	0x20
  #define DISPATCH_VNODE_REVOKE	0x40
  #define DISPATCH_VNODE_FUNLOCK	0x100
  
  typedef unsigned long dispatch_source_vnode_flags_t;
  
  /*!
   * @typedef dispatch_source_timer_flags_t
   * Type of dispatch_source_timer flags
   *
   * @constant DISPATCH_TIMER_STRICT
   * Specifies that the system should make a best effort to strictly observe the
   * leeway value specified for the timer via dispatch_source_set_timer(), even
   * if that value is smaller than the default leeway value that would be applied
   * to the timer otherwise. A minimal amount of leeway will be applied to the
   * timer even if this flag is specified.
   *
   * CAUTION: Use of this flag may override power-saving techniques employed by
   * the system and cause higher power consumption, so it must be used with care
   * and only when absolutely necessary.
   */
  
  #define DISPATCH_TIMER_STRICT 0x1
  
  typedef unsigned long dispatch_source_timer_flags_t;
  
  /*!
   * @function dispatch_source_create
   *
   * @abstract
   * Creates a new dispatch source to monitor low-level system objects and auto-
   * matically submit a handler block to a dispatch queue in response to events.
   *
   * @discussion
   * Dispatch sources are not reentrant. Any events received while the dispatch
   * source is suspended or while the event handler block is currently executing
   * will be coalesced and delivered after the dispatch source is resumed or the
   * event handler block has returned.
   *
   * Dispatch sources are created in an inactive state. After creating the
   * source and setting any desired attributes (i.e. the handler, context, etc.),
   * a call must be made to dispatch_activate() in order to begin event delivery.
   *
   * Calling dispatch_set_target_queue() on a source once it has been activated
   * is not allowed (see dispatch_activate() and dispatch_set_target_queue()).
   *
   * For backward compatibility reasons, dispatch_resume() on an inactive,
   * and not otherwise suspended source has the same effect as calling
   * dispatch_activate(). For new code, using dispatch_activate() is preferred.
   *
   * @param type
   * Declares the type of the dispatch source. Must be one of the defined
   * dispatch_source_type_t constants.
   *
   * @param handle
   * The underlying system handle to monitor. The interpretation of this argument
   * is determined by the constant provided in the type parameter.
   *
   * @param mask
   * A mask of flags specifying which events are desired. The interpretation of
   * this argument is determined by the constant provided in the type parameter.
   *
   * @param queue
   * The dispatch queue to which the event handler block will be submitted.
   * If queue is DISPATCH_TARGET_QUEUE_DEFAULT, the source will submit the event
   * handler block to the default priority global queue.
   *
   * @result
   * The newly created dispatch source. Or NULL if invalid arguments are passed.
   */
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
  DISPATCH_NOTHROW
  dispatch_source_t
  dispatch_source_create(dispatch_source_type_t type,
  	uintptr_t handle,
  	unsigned long mask,
  	dispatch_queue_t _Nullable queue);
  
  /*!
   * @function dispatch_source_set_event_handler
   *
   * @abstract
   * Sets the event handler block for the given dispatch source.
   *
   * @param source
   * The dispatch source to modify.
   * The result of passing NULL in this parameter is undefined.
   *
   * @param handler
   * The event handler block to submit to the source's target queue.
   */
  #ifdef __BLOCKS__
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
  void
  dispatch_source_set_event_handler(dispatch_source_t source,
  	dispatch_block_t _Nullable handler);
  #endif /* __BLOCKS__ */
  
  /*!
   * @function dispatch_source_set_event_handler_f
   *
   * @abstract
   * Sets the event handler function for the given dispatch source.
   *
   * @param source
   * The dispatch source to modify.
   * The result of passing NULL in this parameter is undefined.
   *
   * @param handler
   * The event handler function to submit to the source's target queue.
   * The context parameter passed to the event handler function is the context of
   * the dispatch source current at the time the event handler was set.
   */
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
  void
  dispatch_source_set_event_handler_f(dispatch_source_t source,
  	dispatch_function_t _Nullable handler);
  
  /*!
   * @function dispatch_source_set_cancel_handler
   *
   * @abstract
   * Sets the cancellation handler block for the given dispatch source.
   *
   * @discussion
   * The cancellation handler (if specified) will be submitted to the source's
   * target queue in response to a call to dispatch_source_cancel() once the
   * system has released all references to the source's underlying handle and
   * the source's event handler block has returned.
   *
   * IMPORTANT:
   * Source cancellation and a cancellation handler are required for file
   * descriptor and mach port based sources in order to safely close the
   * descriptor or destroy the port.
   * Closing the descriptor or port before the cancellation handler is invoked may
   * result in a race condition. If a new descriptor is allocated with the same
   * value as the recently closed descriptor while the source's event handler is
   * still running, the event handler may read/write data to the wrong descriptor.
   *
   * @param source
   * The dispatch source to modify.
   * The result of passing NULL in this parameter is undefined.
   *
   * @param handler
   * The cancellation handler block to submit to the source's target queue.
   */
  #ifdef __BLOCKS__
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
  void
  dispatch_source_set_cancel_handler(dispatch_source_t source,
  	dispatch_block_t _Nullable handler);
  #endif /* __BLOCKS__ */
  
  /*!
   * @function dispatch_source_set_cancel_handler_f
   *
   * @abstract
   * Sets the cancellation handler function for the given dispatch source.
   *
   * @discussion
   * See dispatch_source_set_cancel_handler() for more details.
   *
   * @param source
   * The dispatch source to modify.
   * The result of passing NULL in this parameter is undefined.
   *
   * @param handler
   * The cancellation handler function to submit to the source's target queue.
   * The context parameter passed to the event handler function is the current
   * context of the dispatch source at the time the handler call is made.
   */
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
  void
  dispatch_source_set_cancel_handler_f(dispatch_source_t source,
  	dispatch_function_t _Nullable handler);
  
  /*!
   * @function dispatch_source_cancel
   *
   * @abstract
   * Asynchronously cancel the dispatch source, preventing any further invocation
   * of its event handler block.
   *
   * @discussion
   * Cancellation prevents any further invocation of the event handler block for
   * the specified dispatch source, but does not interrupt an event handler
   * block that is already in progress.
   *
   * The cancellation handler is submitted to the source's target queue once the
   * the source's event handler has finished, indicating it is now safe to close
   * the source's handle (i.e. file descriptor or mach port).
   *
   * See dispatch_source_set_cancel_handler() for more information.
   *
   * @param source
   * The dispatch source to be canceled.
   * The result of passing NULL in this parameter is undefined.
   */
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  void
  dispatch_source_cancel(dispatch_source_t source);
  
  /*!
   * @function dispatch_source_testcancel
   *
   * @abstract
   * Tests whether the given dispatch source has been canceled.
   *
   * @param source
   * The dispatch source to be tested.
   * The result of passing NULL in this parameter is undefined.
   *
   * @result
   * Non-zero if canceled and zero if not canceled.
   */
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
  DISPATCH_NOTHROW
  long
  dispatch_source_testcancel(dispatch_source_t source);
  
  /*!
   * @function dispatch_source_get_handle
   *
   * @abstract
   * Returns the underlying system handle associated with this dispatch source.
   *
   * @param source
   * The result of passing NULL in this parameter is undefined.
   *
   * @result
   * The return value should be interpreted according to the type of the dispatch
   * source, and may be one of the following handles:
   *
   *  DISPATCH_SOURCE_TYPE_DATA_ADD:        n/a
   *  DISPATCH_SOURCE_TYPE_DATA_OR:         n/a
   *  DISPATCH_SOURCE_TYPE_MACH_SEND:       mach port (mach_port_t)
   *  DISPATCH_SOURCE_TYPE_MACH_RECV:       mach port (mach_port_t)
   *  DISPATCH_SOURCE_TYPE_MEMORYPRESSURE   n/a
   *  DISPATCH_SOURCE_TYPE_PROC:            process identifier (pid_t)
   *  DISPATCH_SOURCE_TYPE_READ:            file descriptor (int)
   *  DISPATCH_SOURCE_TYPE_SIGNAL:          signal number (int)
   *  DISPATCH_SOURCE_TYPE_TIMER:           n/a
   *  DISPATCH_SOURCE_TYPE_VNODE:           file descriptor (int)
   *  DISPATCH_SOURCE_TYPE_WRITE:           file descriptor (int)
   */
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
  DISPATCH_NOTHROW
  uintptr_t
  dispatch_source_get_handle(dispatch_source_t source);
  
  /*!
   * @function dispatch_source_get_mask
   *
   * @abstract
   * Returns the mask of events monitored by the dispatch source.
   *
   * @param source
   * The result of passing NULL in this parameter is undefined.
   *
   * @result
   * The return value should be interpreted according to the type of the dispatch
   * source, and may be one of the following flag sets:
   *
   *  DISPATCH_SOURCE_TYPE_DATA_ADD:        n/a
   *  DISPATCH_SOURCE_TYPE_DATA_OR:         n/a
   *  DISPATCH_SOURCE_TYPE_MACH_SEND:       dispatch_source_mach_send_flags_t
   *  DISPATCH_SOURCE_TYPE_MACH_RECV:       n/a
   *  DISPATCH_SOURCE_TYPE_MEMORYPRESSURE   dispatch_source_memorypressure_flags_t
   *  DISPATCH_SOURCE_TYPE_PROC:            dispatch_source_proc_flags_t
   *  DISPATCH_SOURCE_TYPE_READ:            n/a
   *  DISPATCH_SOURCE_TYPE_SIGNAL:          n/a
   *  DISPATCH_SOURCE_TYPE_TIMER:           dispatch_source_timer_flags_t
   *  DISPATCH_SOURCE_TYPE_VNODE:           dispatch_source_vnode_flags_t
   *  DISPATCH_SOURCE_TYPE_WRITE:           n/a
   */
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
  DISPATCH_NOTHROW
  unsigned long
  dispatch_source_get_mask(dispatch_source_t source);
  
  /*!
   * @function dispatch_source_get_data
   *
   * @abstract
   * Returns pending data for the dispatch source.
   *
   * @discussion
   * This function is intended to be called from within the event handler block.
   * The result of calling this function outside of the event handler callback is
   * undefined.
   *
   * @param source
   * The result of passing NULL in this parameter is undefined.
   *
   * @result
   * The return value should be interpreted according to the type of the dispatch
   * source, and may be one of the following:
   *
   *  DISPATCH_SOURCE_TYPE_DATA_ADD:        application defined data
   *  DISPATCH_SOURCE_TYPE_DATA_OR:         application defined data
   *  DISPATCH_SOURCE_TYPE_MACH_SEND:       dispatch_source_mach_send_flags_t
   *  DISPATCH_SOURCE_TYPE_MACH_RECV:       n/a
   *  DISPATCH_SOURCE_TYPE_MEMORYPRESSURE   dispatch_source_memorypressure_flags_t
   *  DISPATCH_SOURCE_TYPE_PROC:            dispatch_source_proc_flags_t
   *  DISPATCH_SOURCE_TYPE_READ:            estimated bytes available to read
   *  DISPATCH_SOURCE_TYPE_SIGNAL:          number of signals delivered since
   *                                            the last handler invocation
   *  DISPATCH_SOURCE_TYPE_TIMER:           number of times the timer has fired
   *                                            since the last handler invocation
   *  DISPATCH_SOURCE_TYPE_VNODE:           dispatch_source_vnode_flags_t
   *  DISPATCH_SOURCE_TYPE_WRITE:           estimated buffer space available
   */
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
  DISPATCH_NOTHROW
  unsigned long
  dispatch_source_get_data(dispatch_source_t source);
  
  /*!
   * @function dispatch_source_merge_data
   *
   * @abstract
   * Merges data into a dispatch source of type DISPATCH_SOURCE_TYPE_DATA_ADD or
   * DISPATCH_SOURCE_TYPE_DATA_OR and submits its event handler block to its
   * target queue.
   *
   * @param source
   * The result of passing NULL in this parameter is undefined.
   *
   * @param value
   * The value to coalesce with the pending data using a logical OR or an ADD
   * as specified by the dispatch source type. A value of zero has no effect
   * and will not result in the submission of the event handler block.
   */
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  void
  dispatch_source_merge_data(dispatch_source_t source, unsigned long value);
  
  /*!
   * @function dispatch_source_set_timer
   *
   * @abstract
   * Sets a start time, interval, and leeway value for a timer source.
   *
   * @discussion
   * Once this function returns, any pending source data accumulated for the
   * previous timer values has been cleared; the next fire of the timer will
   * occur at 'start', and every 'interval' nanoseconds thereafter until the
   * timer source is canceled.
   *
   * Any fire of the timer may be delayed by the system in order to improve power
   * consumption and system performance. The upper limit to the allowable delay
   * may be configured with the 'leeway' argument, the lower limit is under the
   * control of the system.
   *
   * For the initial timer fire at 'start', the upper limit to the allowable
   * delay is set to 'leeway' nanoseconds. For the subsequent timer fires at
   * 'start' + N * 'interval', the upper limit is MIN('leeway','interval'/2).
   *
   * The lower limit to the allowable delay may vary with process state such as
   * visibility of application UI. If the specified timer source was created with
   * a mask of DISPATCH_TIMER_STRICT, the system will make a best effort to
   * strictly observe the provided 'leeway' value even if it is smaller than the
   * current lower limit. Note that a minimal amount of delay is to be expected
   * even if this flag is specified.
   *
   * The 'start' argument also determines which clock will be used for the timer:
   * If 'start' is DISPATCH_TIME_NOW or was created with dispatch_time(3), the
   * timer is based on mach_absolute_time(). If 'start' was created with
   * dispatch_walltime(3), the timer is based on gettimeofday(3).
   *
   * Calling this function has no effect if the timer source has already been
   * canceled.
   *
   * @param start
   * The start time of the timer. See dispatch_time() and dispatch_walltime()
   * for more information.
   *
   * @param interval
   * The nanosecond interval for the timer. Use DISPATCH_TIME_FOREVER for a
   * one-shot timer.
   *
   * @param leeway
   * The nanosecond leeway for the timer.
   */
  API_AVAILABLE(macos(10.6), ios(4.0))
  DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  void
  dispatch_source_set_timer(dispatch_source_t source,
  	dispatch_time_t start,
  	uint64_t interval,
  	uint64_t leeway);
  
  /*!
   * @function dispatch_source_set_registration_handler
   *
   * @abstract
   * Sets the registration handler block for the given dispatch source.
   *
   * @discussion
   * The registration handler (if specified) will be submitted to the source's
   * target queue once the corresponding kevent() has been registered with the
   * system, following the initial dispatch_resume() of the source.
   *
   * If a source is already registered when the registration handler is set, the
   * registration handler will be invoked immediately.
   *
   * @param source
   * The dispatch source to modify.
   * The result of passing NULL in this parameter is undefined.
   *
   * @param handler
   * The registration handler block to submit to the source's target queue.
   */
  #ifdef __BLOCKS__
  API_AVAILABLE(macos(10.7), ios(4.3))
  DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
  void
  dispatch_source_set_registration_handler(dispatch_source_t source,
  	dispatch_block_t _Nullable handler);
  #endif /* __BLOCKS__ */
  
  /*!
   * @function dispatch_source_set_registration_handler_f
   *
   * @abstract
   * Sets the registration handler function for the given dispatch source.
   *
   * @discussion
   * See dispatch_source_set_registration_handler() for more details.
   *
   * @param source
   * The dispatch source to modify.
   * The result of passing NULL in this parameter is undefined.
   *
   * @param handler
   * The registration handler function to submit to the source's target queue.
   * The context parameter passed to the registration handler function is the
   * current context of the dispatch source at the time the handler call is made.
   */
  API_AVAILABLE(macos(10.7), ios(4.3))
  DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
  void
  dispatch_source_set_registration_handler_f(dispatch_source_t source,
  	dispatch_function_t _Nullable handler);
  
  __END_DECLS
  
  DISPATCH_ASSUME_NONNULL_END
  
  #endif
  