libdispatch-913.20.5.tar.gz

[apple/libdispatch.git] / dispatch / source.h

diff --git a/dispatch/source.h b/dispatch/source.h
index 4c9f601dd4edf3543162b0c17d577c3de06d2271..6992d422691c11b5dcf2b52e0fa376054c53e350 100644 (file)
--- a/dispatch/source.h
+++ b/dispatch/source.h
@@ -1,5 +1,5 @@
 /*
 /*

- * Copyright (c) 2008-2011 Apple Inc. All rights reserved.
+ * Copyright (c) 2008-2013 Apple Inc. All rights reserved.

  *
  * @APPLE_APACHE_LICENSE_HEADER_START@
  *
  *
  * @APPLE_APACHE_LICENSE_HEADER_START@
  *


@@ -30,7 +30,12 @@
 #include <mach/port.h>
 #include <mach/message.h>
 #endif
 #include <mach/port.h>
 #include <mach/message.h>
 #endif

+
+#if !TARGET_OS_WIN32

 #include <sys/signal.h>
 #include <sys/signal.h>

+#endif
+
+DISPATCH_ASSUME_NONNULL_BEGIN

 
 /*!
  * @header
 
 /*!
  * @header


@@ -49,7 +54,9 @@
  * Dispatch sources are used to automatically submit event handler blocks to
  * dispatch queues in response to external events.
  */
  * Dispatch sources are used to automatically submit event handler blocks to
  * dispatch queues in response to external events.
  */

-DISPATCH_DECL(dispatch_source);
+DISPATCH_SOURCE_DECL(dispatch_source);
+
+__BEGIN_DECLS

 
 /*!
  * @typedef dispatch_source_type_t
 
 /*!
  * @typedef dispatch_source_type_t


@@ -59,7 +66,7 @@ DISPATCH_DECL(dispatch_source);
  * 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,
  * 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 identifer, etc.), and how the mask arugment is
+ * signal number, process identifier, etc.), and how the mask argument is

  * interpreted.
  */
 typedef const struct dispatch_source_type_s *dispatch_source_type_t;
  * interpreted.
  */
 typedef const struct dispatch_source_type_s *dispatch_source_type_t;


@@ -72,22 +79,34 @@ typedef const struct dispatch_source_type_s *dispatch_source_type_t;
  * The mask is unused (pass zero for now).
  */
 #define DISPATCH_SOURCE_TYPE_DATA_ADD (&_dispatch_source_type_data_add)
  * The mask is unused (pass zero for now).
  */
 #define DISPATCH_SOURCE_TYPE_DATA_ADD (&_dispatch_source_type_data_add)

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
-DISPATCH_EXPORT
-const struct dispatch_source_type_s _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
 
 /*!
  * @const DISPATCH_SOURCE_TYPE_DATA_OR
  * @discussion A dispatch source that coalesces data obtained via calls to

- * dispatch_source_merge_data(). A logical OR is used to coalesce the data.
+ * dispatch_source_merge_data(). A bitwise OR is used to coalesce the data.

  * The handle is unused (pass zero for now).
  * The handle is unused (pass zero for now).

- * The mask is used to perform a logical AND with the value passed to
- * dispatch_source_merge_data().
+ * The mask is unused (pass zero for now).

  */
 #define DISPATCH_SOURCE_TYPE_DATA_OR (&_dispatch_source_type_data_or)
  */
 #define DISPATCH_SOURCE_TYPE_DATA_OR (&_dispatch_source_type_data_or)

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
-DISPATCH_EXPORT
-const struct dispatch_source_type_s _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
 
 /*!
  * @const DISPATCH_SOURCE_TYPE_MACH_SEND


@@ -97,9 +116,8 @@ const struct dispatch_source_type_s _dispatch_source_type_data_or;
  * 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)
  * 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)

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
-DISPATCH_EXPORT
-const struct dispatch_source_type_s _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
 
 /*!
  * @const DISPATCH_SOURCE_TYPE_MACH_RECV


@@ -108,9 +126,21 @@ const struct dispatch_source_type_s _dispatch_source_type_mach_send;
  * The mask is unused (pass zero for now).
  */
 #define DISPATCH_SOURCE_TYPE_MACH_RECV (&_dispatch_source_type_mach_recv)
  * The mask is unused (pass zero for now).
  */
 #define DISPATCH_SOURCE_TYPE_MACH_RECV (&_dispatch_source_type_mach_recv)

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
-DISPATCH_EXPORT
-const struct dispatch_source_type_s _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
 
 /*!
  * @const DISPATCH_SOURCE_TYPE_PROC


@@ -120,9 +150,8 @@ const struct dispatch_source_type_s _dispatch_source_type_mach_recv;
  * The mask is a mask of desired events from dispatch_source_proc_flags_t.
  */
 #define DISPATCH_SOURCE_TYPE_PROC (&_dispatch_source_type_proc)
  * The mask is a mask of desired events from dispatch_source_proc_flags_t.
  */
 #define DISPATCH_SOURCE_TYPE_PROC (&_dispatch_source_type_proc)

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
-DISPATCH_EXPORT
-const struct dispatch_source_type_s _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
 
 /*!
  * @const DISPATCH_SOURCE_TYPE_READ


@@ -132,9 +161,8 @@ const struct dispatch_source_type_s _dispatch_source_type_proc;
  * The mask is unused (pass zero for now).
  */
 #define DISPATCH_SOURCE_TYPE_READ (&_dispatch_source_type_read)
  * The mask is unused (pass zero for now).
  */
 #define DISPATCH_SOURCE_TYPE_READ (&_dispatch_source_type_read)

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
-DISPATCH_EXPORT
-const struct dispatch_source_type_s _dispatch_source_type_read;
+API_AVAILABLE(macos(10.6), ios(4.0))
+DISPATCH_SOURCE_TYPE_DECL(read);

 
 /*!
  * @const DISPATCH_SOURCE_TYPE_SIGNAL
 
 /*!
  * @const DISPATCH_SOURCE_TYPE_SIGNAL


@@ -143,21 +171,19 @@ const struct dispatch_source_type_s _dispatch_source_type_read;
  * The mask is unused (pass zero for now).
  */
 #define DISPATCH_SOURCE_TYPE_SIGNAL (&_dispatch_source_type_signal)
  * The mask is unused (pass zero for now).
  */
 #define DISPATCH_SOURCE_TYPE_SIGNAL (&_dispatch_source_type_signal)

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
-DISPATCH_EXPORT
-const struct dispatch_source_type_s _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).
 
 /*!
  * @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 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)
  */
 #define DISPATCH_SOURCE_TYPE_TIMER (&_dispatch_source_type_timer)

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
-DISPATCH_EXPORT
-const struct dispatch_source_type_s _dispatch_source_type_timer;
+API_AVAILABLE(macos(10.6), ios(4.0))
+DISPATCH_SOURCE_TYPE_DECL(timer);

 
 /*!
  * @const DISPATCH_SOURCE_TYPE_VNODE
 
 /*!
  * @const DISPATCH_SOURCE_TYPE_VNODE


@@ -167,9 +193,8 @@ const struct dispatch_source_type_s _dispatch_source_type_timer;
  * The mask is a mask of desired events from dispatch_source_vnode_flags_t.
  */
 #define DISPATCH_SOURCE_TYPE_VNODE (&_dispatch_source_type_vnode)
  * The mask is a mask of desired events from dispatch_source_vnode_flags_t.
  */
 #define DISPATCH_SOURCE_TYPE_VNODE (&_dispatch_source_type_vnode)

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
-DISPATCH_EXPORT
-const struct dispatch_source_type_s _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
 
 /*!
  * @const DISPATCH_SOURCE_TYPE_WRITE


@@ -179,9 +204,8 @@ const struct dispatch_source_type_s _dispatch_source_type_vnode;
  * The mask is unused (pass zero for now).
  */
 #define DISPATCH_SOURCE_TYPE_WRITE (&_dispatch_source_type_write)
  * The mask is unused (pass zero for now).
  */
 #define DISPATCH_SOURCE_TYPE_WRITE (&_dispatch_source_type_write)

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
-DISPATCH_EXPORT
-const struct dispatch_source_type_s _dispatch_source_type_write;
+API_AVAILABLE(macos(10.6), ios(4.0))
+DISPATCH_SOURCE_TYPE_DECL(write);

 
 /*!
  * @typedef dispatch_source_mach_send_flags_t
 
 /*!
  * @typedef dispatch_source_mach_send_flags_t


@@ -194,6 +218,36 @@ const struct dispatch_source_type_s _dispatch_source_type_write;
 
 typedef unsigned long dispatch_source_mach_send_flags_t;
 
 
 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
 /*!
  * @typedef dispatch_source_proc_flags_t
  * Type of dispatch_source_proc flags


@@ -242,6 +296,9 @@ typedef unsigned long dispatch_source_proc_flags_t;
  *
  * @constant DISPATCH_VNODE_REVOKE
  * The filesystem object was revoked.
  *
  * @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_DELETE  0x1


@@ -251,10 +308,29 @@ typedef unsigned long dispatch_source_proc_flags_t;
 #define DISPATCH_VNODE_LINK            0x10
 #define DISPATCH_VNODE_RENAME  0x20
 #define DISPATCH_VNODE_REVOKE  0x40
 #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 unsigned long dispatch_source_vnode_flags_t;
 

-__BEGIN_DECLS
+/*!
+ * @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
 
 /*!
  * @function dispatch_source_create


@@ -269,31 +345,45 @@ __BEGIN_DECLS
  * will be coalesced and delivered after the dispatch source is resumed or the
  * event handler block has returned.
  *
  * will be coalesced and delivered after the dispatch source is resumed or the
  * event handler block has returned.
  *

- * Dispatch sources are created in a suspended state. After creating the
+ * Dispatch sources are created in an inactive state. After creating the

  * source and setting any desired attributes (i.e. the handler, context, etc.),
  * source and setting any desired attributes (i.e. the handler, context, etc.),

- * a call must be made to dispatch_resume() in order to begin event delivery.
+ * 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 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 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 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.
  * @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.

  */
  */

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
-DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_WARN_RESULT DISPATCH_NOTHROW
+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_source_t
 dispatch_source_create(dispatch_source_type_t type,
        uintptr_t handle,
        unsigned long mask,

-       dispatch_queue_t queue);
+       dispatch_queue_t _Nullable queue);

 
 /*!
  * @function dispatch_source_set_event_handler
 
 /*!
  * @function dispatch_source_set_event_handler


@@ -309,11 +399,11 @@ dispatch_source_create(dispatch_source_type_t type,
  * The event handler block to submit to the source's target queue.
  */
 #ifdef __BLOCKS__
  * The event handler block to submit to the source's target queue.
  */
 #ifdef __BLOCKS__

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+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_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 void
 dispatch_source_set_event_handler(dispatch_source_t source,

-       dispatch_block_t handler);
+       dispatch_block_t _Nullable handler);

 #endif /* __BLOCKS__ */
 
 /*!
 #endif /* __BLOCKS__ */
 
 /*!


@@ -328,15 +418,14 @@ dispatch_source_set_event_handler(dispatch_source_t source,
  *
  * @param handler
  * The event handler function to submit to the source's target queue.
  *
  * @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 current
- * context of the dispatch source at the time the handler call is made.
- * The result of passing NULL in this parameter is undefined.
+ * 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.

  */
  */

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+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_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 void
 dispatch_source_set_event_handler_f(dispatch_source_t source,

-       dispatch_function_t handler);
+       dispatch_function_t _Nullable handler);

 
 /*!
  * @function dispatch_source_set_cancel_handler
 
 /*!
  * @function dispatch_source_set_cancel_handler


@@ -351,12 +440,13 @@ dispatch_source_set_event_handler_f(dispatch_source_t source,
  * the source's event handler block has returned.
  *
  * IMPORTANT:
  * the source's event handler block has returned.
  *
  * IMPORTANT:

- * A cancellation handler is 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 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.
+ * 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.
  *
  * @param source
  * The dispatch source to modify.


@@ -366,11 +456,11 @@ dispatch_source_set_event_handler_f(dispatch_source_t source,
  * The cancellation handler block to submit to the source's target queue.
  */
 #ifdef __BLOCKS__
  * The cancellation handler block to submit to the source's target queue.
  */
 #ifdef __BLOCKS__

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+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_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 void
 dispatch_source_set_cancel_handler(dispatch_source_t source,

-       dispatch_block_t cancel_handler);
+       dispatch_block_t _Nullable handler);

 #endif /* __BLOCKS__ */
 
 /*!
 #endif /* __BLOCKS__ */
 
 /*!


@@ -391,11 +481,11 @@ dispatch_source_set_cancel_handler(dispatch_source_t source,
  * 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.
  */
  * 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.
  */

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+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_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 void
 dispatch_source_set_cancel_handler_f(dispatch_source_t source,

-       dispatch_function_t cancel_handler);
+       dispatch_function_t _Nullable handler);

 
 /*!
  * @function dispatch_source_cancel
 
 /*!
  * @function dispatch_source_cancel


@@ -419,7 +509,7 @@ dispatch_source_set_cancel_handler_f(dispatch_source_t source,
  * The dispatch source to be canceled.
  * The result of passing NULL in this parameter is undefined.
  */
  * The dispatch source to be canceled.
  * The result of passing NULL in this parameter is undefined.
  */

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+API_AVAILABLE(macos(10.6), ios(4.0))

 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 void
 dispatch_source_cancel(dispatch_source_t source);
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 void
 dispatch_source_cancel(dispatch_source_t source);


@@ -437,7 +527,7 @@ dispatch_source_cancel(dispatch_source_t source);
  * @result
  * Non-zero if canceled and zero if not canceled.
  */
  * @result
  * Non-zero if canceled and zero if not canceled.
  */

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+API_AVAILABLE(macos(10.6), ios(4.0))

 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 DISPATCH_NOTHROW
 long
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 DISPATCH_NOTHROW
 long


@@ -460,6 +550,7 @@ dispatch_source_testcancel(dispatch_source_t source);
  *  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_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_PROC:            process identifier (pid_t)
  *  DISPATCH_SOURCE_TYPE_READ:            file descriptor (int)
  *  DISPATCH_SOURCE_TYPE_SIGNAL:          signal number (int)


@@ -467,7 +558,7 @@ dispatch_source_testcancel(dispatch_source_t source);
  *  DISPATCH_SOURCE_TYPE_VNODE:           file descriptor (int)
  *  DISPATCH_SOURCE_TYPE_WRITE:           file descriptor (int)
  */
  *  DISPATCH_SOURCE_TYPE_VNODE:           file descriptor (int)
  *  DISPATCH_SOURCE_TYPE_WRITE:           file descriptor (int)
  */

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+API_AVAILABLE(macos(10.6), ios(4.0))

 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 DISPATCH_NOTHROW
 uintptr_t
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 DISPATCH_NOTHROW
 uintptr_t


@@ -490,14 +581,15 @@ dispatch_source_get_handle(dispatch_source_t source);
  *  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_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_PROC:            dispatch_source_proc_flags_t
  *  DISPATCH_SOURCE_TYPE_READ:            n/a
  *  DISPATCH_SOURCE_TYPE_SIGNAL:          n/a

- *  DISPATCH_SOURCE_TYPE_TIMER:           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
  */
  *  DISPATCH_SOURCE_TYPE_VNODE:           dispatch_source_vnode_flags_t
  *  DISPATCH_SOURCE_TYPE_WRITE:           n/a
  */

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+API_AVAILABLE(macos(10.6), ios(4.0))

 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 DISPATCH_NOTHROW
 unsigned long
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 DISPATCH_NOTHROW
 unsigned long


@@ -525,6 +617,7 @@ dispatch_source_get_mask(dispatch_source_t source);
  *  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_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
  *  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


@@ -534,7 +627,7 @@ dispatch_source_get_mask(dispatch_source_t source);
  *  DISPATCH_SOURCE_TYPE_VNODE:           dispatch_source_vnode_flags_t
  *  DISPATCH_SOURCE_TYPE_WRITE:           estimated buffer space available
  */
  *  DISPATCH_SOURCE_TYPE_VNODE:           dispatch_source_vnode_flags_t
  *  DISPATCH_SOURCE_TYPE_WRITE:           estimated buffer space available
  */

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+API_AVAILABLE(macos(10.6), ios(4.0))

 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 DISPATCH_NOTHROW
 unsigned long
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 DISPATCH_NOTHROW
 unsigned long


@@ -556,7 +649,7 @@ dispatch_source_get_data(dispatch_source_t source);
  * 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.
  */
  * 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.
  */

-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+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);
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 void
 dispatch_source_merge_data(dispatch_source_t source, unsigned long value);


@@ -568,32 +661,47 @@ dispatch_source_merge_data(dispatch_source_t source, unsigned long value);
  * Sets a start time, interval, and leeway value for a timer source.
  *
  * @discussion
  * Sets a start time, interval, and leeway value for a timer source.
  *
  * @discussion

- * Calling this function has no effect if the timer source has already been
- * canceled. Once this function returns, any pending timer data accumulated
- * for the previous timer values has been cleared
+ * 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).

  *
  *

- * The start time argument also determines which clock will be used for the
- * timer. If the start time is DISPATCH_TIME_NOW or created with
- * dispatch_time() then the timer is based on mach_absolute_time(). Otherwise,
- * if the start time of the timer is created with dispatch_walltime() then 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
  *
  * @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.
+ * The nanosecond interval for the timer. Use DISPATCH_TIME_FOREVER for a
+ * one-shot timer.

  *
  * @param leeway
  *
  * @param leeway

- * A hint given to the system by the application for the amount of leeway, in
- * nanoseconds, that the system may defer the timer in order to align with other
- * system activity for improved system performance or power consumption. (For
- * example, an application might perform a periodic task every 5 minutes, with
- * a leeway of up to 30 seconds.)  Note that some latency is to be expected for
- * all timers even when a leeway value of zero is specified.
- */
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+ * 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_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 void
 dispatch_source_set_timer(dispatch_source_t source,


@@ -623,11 +731,11 @@ dispatch_source_set_timer(dispatch_source_t source,
  * The registration handler block to submit to the source's target queue.
  */
 #ifdef __BLOCKS__
  * The registration handler block to submit to the source's target queue.
  */
 #ifdef __BLOCKS__

-__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_4_3)
+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_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 void
 dispatch_source_set_registration_handler(dispatch_source_t source,

-       dispatch_block_t registration_handler);
+       dispatch_block_t _Nullable handler);

 #endif /* __BLOCKS__ */
 
 /*!
 #endif /* __BLOCKS__ */
 
 /*!


@@ -648,12 +756,14 @@ dispatch_source_set_registration_handler(dispatch_source_t source,
  * 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.
  */
  * 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.
  */

-__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_4_3)
+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_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
 void
 dispatch_source_set_registration_handler_f(dispatch_source_t source,

-       dispatch_function_t registration_handler);
+       dispatch_function_t _Nullable handler);

 
 __END_DECLS
 
 
 __END_DECLS
 

+DISPATCH_ASSUME_NONNULL_END
+

 #endif
 #endif