#include <sys/signal.h>
#endif
+DISPATCH_ASSUME_NONNULL_BEGIN
+
/*!
* @header
* The dispatch framework provides a suite of interfaces for monitoring low-
* 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
* 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;
-#if !TARGET_OS_WIN32
-/*! @parseOnly */
-#define DISPATCH_SOURCE_TYPE_DECL(name) \
- DISPATCH_EXPORT const struct dispatch_source_type_s \
- _dispatch_source_type_##name
-#else
-#define DISPATCH_SOURCE_TYPE_DECL(name) \
- DISPATCH_EXPORT struct dispatch_source_type_s _dispatch_source_type_##name
-#endif
-
/*!
* @const DISPATCH_SOURCE_TYPE_DATA_ADD
* @discussion A dispatch source that coalesces data obtained via calls to
* 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)
+API_AVAILABLE(macos(10.6), ios(4.0))
DISPATCH_SOURCE_TYPE_DECL(data_add);
/*!
* The mask is unused (pass zero for now).
*/
#define DISPATCH_SOURCE_TYPE_DATA_OR (&_dispatch_source_type_data_or)
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+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
* 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)
+API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
DISPATCH_SOURCE_TYPE_DECL(mach_send);
/*!
* 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)
+API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
DISPATCH_SOURCE_TYPE_DECL(mach_recv);
/*!
*/
#define DISPATCH_SOURCE_TYPE_MEMORYPRESSURE \
(&_dispatch_source_type_memorypressure)
-__OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_NA)
+API_AVAILABLE(macos(10.9), ios(8.0)) DISPATCH_LINUX_UNAVAILABLE()
DISPATCH_SOURCE_TYPE_DECL(memorypressure);
/*!
* 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)
+API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
DISPATCH_SOURCE_TYPE_DECL(proc);
/*!
* 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)
+API_AVAILABLE(macos(10.6), ios(4.0))
DISPATCH_SOURCE_TYPE_DECL(read);
/*!
* 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)
+API_AVAILABLE(macos(10.6), ios(4.0))
DISPATCH_SOURCE_TYPE_DECL(signal);
/*!
* The mask specifies which flags from dispatch_source_timer_flags_t to apply.
*/
#define DISPATCH_SOURCE_TYPE_TIMER (&_dispatch_source_type_timer)
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+API_AVAILABLE(macos(10.6), ios(4.0))
DISPATCH_SOURCE_TYPE_DECL(timer);
/*!
* 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)
+API_AVAILABLE(macos(10.6), ios(4.0)) DISPATCH_LINUX_UNAVAILABLE()
DISPATCH_SOURCE_TYPE_DECL(vnode);
/*!
* 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)
+API_AVAILABLE(macos(10.6), ios(4.0))
DISPATCH_SOURCE_TYPE_DECL(write);
/*!
*
* @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_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_timer_flags_t;
-__BEGIN_DECLS
-
/*!
* @function dispatch_source_create
*
* 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.),
- * 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 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.
*/
-__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
+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 queue);
+ dispatch_queue_t _Nullable queue);
/*!
* @function dispatch_source_set_event_handler
* 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_block_t handler);
+ dispatch_block_t _Nullable handler);
#endif /* __BLOCKS__ */
/*!
*
* @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_function_t handler);
+ dispatch_function_t _Nullable handler);
/*!
* @function dispatch_source_set_cancel_handler
* 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.
* 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_block_t cancel_handler);
+ dispatch_block_t _Nullable handler);
#endif /* __BLOCKS__ */
/*!
* 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_function_t cancel_handler);
+ dispatch_function_t _Nullable handler);
/*!
* @function dispatch_source_cancel
* 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);
* @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_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_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_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
* 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);
* @param leeway
* The nanosecond leeway for the timer.
*/
-__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_set_timer(dispatch_source_t source,
* 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_block_t registration_handler);
+ dispatch_block_t _Nullable handler);
#endif /* __BLOCKS__ */
/*!
* 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_function_t registration_handler);
+ dispatch_function_t _Nullable handler);
__END_DECLS
+DISPATCH_ASSUME_NONNULL_END
+
#endif
projects / apple / libdispatch.git / blobdiff