dispatch/block.h

API_AVAILABLE(macos(10.10), ios(8.0)) DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_RETURNS_RETAINED_BLOCK DISPATCH_WARN_RESULT DISPATCH_NOTHROW DISPATCH_SWIFT_UNAVAILABLE("Use DispatchWorkItem()") dispatch_block_t dispatch_block_create(
	dispatch_block_flags_t flags,
	dispatch_block_t block
)

@function dispatch_block_create @abstract Create a new dispatch block object on the heap from an existing block and the given flags. @discussion The provided block is Block_copy'ed to the heap and retained by the newly created dispatch block object. The returned dispatch block object is intended to be submitted to a dispatch queue with dispatch_async() and related functions, but may also be invoked directly. Both operations can be performed an arbitrary number of times but only the first completed execution of a dispatch block object can be waited on with dispatch_block_wait() or observed with dispatch_block_notify(). If the returned dispatch block object is submitted to a dispatch queue, the submitted block instance will be associated with the QOS class current at the time of submission, unless one of the following flags assigned a specific QOS class (or no QOS class) at the time of block creation: - DISPATCH_BLOCK_ASSIGN_CURRENT - DISPATCH_BLOCK_NO_QOS_CLASS - DISPATCH_BLOCK_DETACHED The QOS class the block object will be executed with also depends on the QOS class assigned to the queue and which of the following flags was specified or defaulted to: - DISPATCH_BLOCK_INHERIT_QOS_CLASS (default for asynchronous execution) - DISPATCH_BLOCK_ENFORCE_QOS_CLASS (default for synchronous execution) See description of dispatch_block_flags_t for details. If the returned dispatch block object is submitted directly to a serial queue and is configured to execute with a specific QOS class, the system will make a best effort to apply the necessary QOS overrides to ensure that blocks submitted earlier to the serial queue are executed at that same QOS class or higher. @param flags Configuration flags for the block object. Passing a value that is not a bitwise OR of flags from dispatch_block_flags_t results in NULL being returned. @param block The block to create the dispatch block object from. @result The newly created dispatch block object, or NULL. When not building with Objective-C ARC, must be released with a -[release] message or the Block_release() function.

API_AVAILABLE(macos(10.10), ios(8.0)) DISPATCH_EXPORT DISPATCH_NONNULL4 DISPATCH_RETURNS_RETAINED_BLOCK DISPATCH_WARN_RESULT DISPATCH_NOTHROW DISPATCH_SWIFT_UNAVAILABLE("Use DispatchWorkItem()") dispatch_block_t dispatch_block_create_with_qos_class(
	dispatch_block_flags_t flags,
	dispatch_qos_class_t qos_class,
	int relative_priority,
	dispatch_block_t block
)

@function dispatch_block_create_with_qos_class @abstract Create a new dispatch block object on the heap from an existing block and the given flags, and assign it the specified QOS class and relative priority. @discussion The provided block is Block_copy'ed to the heap and retained by the newly created dispatch block object. The returned dispatch block object is intended to be submitted to a dispatch queue with dispatch_async() and related functions, but may also be invoked directly. Both operations can be performed an arbitrary number of times but only the first completed execution of a dispatch block object can be waited on with dispatch_block_wait() or observed with dispatch_block_notify(). If invoked directly, the returned dispatch block object will be executed with the assigned QOS class as long as that does not result in a lower QOS class than what is current on the calling thread. If the returned dispatch block object is submitted to a dispatch queue, the QOS class it will be executed with depends on the QOS class assigned to the block, the QOS class assigned to the queue and which of the following flags was specified or defaulted to: - DISPATCH_BLOCK_INHERIT_QOS_CLASS: default for asynchronous execution - DISPATCH_BLOCK_ENFORCE_QOS_CLASS: default for synchronous execution See description of dispatch_block_flags_t for details. If the returned dispatch block object is submitted directly to a serial queue and is configured to execute with a specific QOS class, the system will make a best effort to apply the necessary QOS overrides to ensure that blocks submitted earlier to the serial queue are executed at that same QOS class or higher. @param flags Configuration flags for the new block object. Passing a value that is not a bitwise OR of flags from dispatch_block_flags_t results in NULL being returned. @param qos_class A QOS class value: - QOS_CLASS_USER_INTERACTIVE - QOS_CLASS_USER_INITIATED - QOS_CLASS_DEFAULT - QOS_CLASS_UTILITY - QOS_CLASS_BACKGROUND - QOS_CLASS_UNSPECIFIED Passing QOS_CLASS_UNSPECIFIED is equivalent to specifying the DISPATCH_BLOCK_NO_QOS_CLASS flag. Passing any other value results in NULL being returned. @param relative_priority A relative priority within the QOS class. This value is a negative offset from the maximum supported scheduler priority for the given class. Passing a value greater than zero or less than QOS_MIN_RELATIVE_PRIORITY results in NULL being returned. @param block The block to create the dispatch block object from. @result The newly created dispatch block object, or NULL. When not building with Objective-C ARC, must be released with a -[release] message or the Block_release() function.

API_AVAILABLE(macos(10.10), ios(8.0)) DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW DISPATCH_SWIFT_UNAVAILABLE("Use DispatchWorkItem.perform()") void dispatch_block_perform(
	dispatch_block_flags_t flags,
	DISPATCH_NOESCAPE dispatch_block_t block
)

@function dispatch_block_perform @abstract Create, synchronously execute and release a dispatch block object from the specified block and flags. @discussion Behaves identically to the sequence <code> dispatch_block_t b = dispatch_block_create(flags, block); b(); Block_release(b); </code> but may be implemented more efficiently internally by not requiring a copy to the heap of the specified block or the allocation of a new block object. @param flags Configuration flags for the temporary block object. The result of passing a value that is not a bitwise OR of flags from dispatch_block_flags_t is undefined. @param block The block to create the temporary block object from.

API_AVAILABLE(macos(10.10), ios(8.0)) DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW DISPATCH_SWIFT_UNAVAILABLE("Use DispatchWorkItem.wait(timeout:)") intptr_t dispatch_block_wait(
	dispatch_block_t block,
	dispatch_time_t timeout
)

@function dispatch_block_wait @abstract Wait synchronously until execution of the specified dispatch block object has completed or until the specified timeout has elapsed. @discussion This function will return immediately if execution of the block object has already completed. It is not possible to wait for multiple executions of the same block object with this interface; use dispatch_group_wait() for that purpose. A single dispatch block object may either be waited on once and executed once, or it may be executed any number of times. The behavior of any other combination is undefined. Submission to a dispatch queue counts as an execution, even if cancellation (dispatch_block_cancel) means the block's code never runs. The result of calling this function from multiple threads simultaneously with the same dispatch block object is undefined, but note that doing so would violate the rules described in the previous paragraph. If this function returns indicating that the specified timeout has elapsed, then that invocation does not count as the one allowed wait. If at the time this function is called, the specified dispatch block object has been submitted directly to a serial queue, the system will make a best effort to apply the necessary QOS overrides to ensure that the block and any blocks submitted earlier to that serial queue are executed at the QOS class (or higher) of the thread calling dispatch_block_wait(). @param block The dispatch block object to wait on. The result of passing NULL or a block object not returned by one of the dispatch_block_create* functions is undefined. @param timeout When to timeout (see dispatch_time). As a convenience, there are the DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants. @result Returns zero on success (the dispatch block object completed within the specified timeout) or non-zero on error (i.e. timed out).

API_AVAILABLE(macos(10.10), ios(8.0)) DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW DISPATCH_SWIFT_UNAVAILABLE("Use DispatchWorkItem.notify(queue:execute:)") void dispatch_block_notify(
	dispatch_block_t block,
	dispatch_queue_t queue,
	dispatch_block_t notification_block
)

@function dispatch_block_notify @abstract Schedule a notification block to be submitted to a queue when the execution of a specified dispatch block object has completed. @discussion This function will submit the notification block immediately if execution of the observed block object has already completed. It is not possible to be notified of multiple executions of the same block object with this interface, use dispatch_group_notify() for that purpose. A single dispatch block object may either be observed one or more times and executed once, or it may be executed any number of times. The behavior of any other combination is undefined. Submission to a dispatch queue counts as an execution, even if cancellation (dispatch_block_cancel) means the block's code never runs. If multiple notification blocks are scheduled for a single block object, there is no defined order in which the notification blocks will be submitted to their associated queues. @param block The dispatch block object to observe. The result of passing NULL or a block object not returned by one of the dispatch_block_create* functions is undefined. @param queue The queue to which the supplied notification block will be submitted when the observed block completes. @param notification_block The notification block to submit when the observed block object completes.

API_AVAILABLE(macos(10.10), ios(8.0)) DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW DISPATCH_SWIFT_UNAVAILABLE("Use DispatchWorkItem.cancel()") void dispatch_block_cancel(
	dispatch_block_t block
)

@function dispatch_block_cancel @abstract Asynchronously cancel the specified dispatch block object. @discussion Cancellation causes any future execution of the dispatch block object to return immediately, but does not affect any execution of the block object that is already in progress. Release of any resources associated with the block object will be delayed until execution of the block object is next attempted (or any execution already in progress completes). NOTE: care needs to be taken to ensure that a block object that may be canceled does not capture any resources that require execution of the block body in order to be released (e.g. memory allocated with malloc(3) that the block body calls free(3) on). Such resources will be leaked if the block body is never executed due to cancellation. @param block The dispatch block object to cancel. The result of passing NULL or a block object not returned by one of the dispatch_block_create* functions is undefined.

API_AVAILABLE(macos(10.10), ios(8.0)) DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW DISPATCH_SWIFT_UNAVAILABLE("Use DispatchWorkItem.isCancelled") intptr_t dispatch_block_testcancel(
	dispatch_block_t block
)

@function dispatch_block_testcancel @abstract Tests whether the given dispatch block object has been canceled. @param block The dispatch block object to test. The result of passing NULL or a block object not returned by one of the dispatch_block_create* functions is undefined. @result Non-zero if canceled and zero if not canceled.