dispatch/block.h - third_party/swift-corelibs-libdispatch - Git at Google

 /*
  * Copyright (c) 2014 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_BLOCK__
 #define __DISPATCH_BLOCK__

 #ifndef __DISPATCH_INDIRECT__
 #error "Please #include <dispatch/dispatch.h> instead of this file directly."
 #include <dispatch/base.h> // for HeaderDoc
 #endif

 #ifdef __BLOCKS__

 /*!
  * @group Dispatch block objects
  */

 DISPATCH_ASSUME_NONNULL_BEGIN

 __BEGIN_DECLS

 /*!
  * @typedef dispatch_block_flags_t
  * Flags to pass to the dispatch_block_create* functions.
  *
  * @const DISPATCH_BLOCK_BARRIER
  * Flag indicating that a dispatch block object should act as a barrier block
  * when submitted to a DISPATCH_QUEUE_CONCURRENT queue.
  * See dispatch_barrier_async() for details.
  * This flag has no effect when the dispatch block object is invoked directly.
  *
  * @const DISPATCH_BLOCK_DETACHED
  * Flag indicating that a dispatch block object should execute disassociated
  * from current execution context attributes such as QOS class, os_activity_t
  * and properties of the current IPC request (if any). If invoked directly, the
  * block object will remove these attributes from the calling thread for the
  * duration of the block body (before applying attributes assigned to the block
  * object, if any). If submitted to a queue, the block object will be executed
  * with the attributes of the queue (or any attributes specifically assigned to
  * the block object).
  *
  * @const DISPATCH_BLOCK_ASSIGN_CURRENT
  * Flag indicating that a dispatch block object should be assigned the execution
  * context attributes that are current at the time the block object is created.
  * This applies to attributes such as QOS class, os_activity_t and properties of
  * the current IPC request (if any). If invoked directly, the block object will
  * apply these attributes to the calling thread for the duration of the block
  * body. If the block object is submitted to a queue, this flag replaces the
  * default behavior of associating the submitted block instance with the
  * execution context attributes that are current at the time of submission.
  * If a specific QOS class is assigned with DISPATCH_BLOCK_NO_QOS_CLASS or
  * dispatch_block_create_with_qos_class(), that QOS class takes precedence over
  * the QOS class assignment indicated by this flag.
  *
  * @const DISPATCH_BLOCK_NO_QOS_CLASS
  * Flag indicating that a dispatch block object should be not be assigned a QOS
  * class. If invoked directly, the block object will be executed with the QOS
  * class of the calling thread. If the block object is submitted to a queue,
  * this replaces the default behavior of associating the submitted block
  * instance with the QOS class current at the time of submission.
  * This flag is ignored if a specific QOS class is assigned with
  * dispatch_block_create_with_qos_class().
  *
  * @const DISPATCH_BLOCK_INHERIT_QOS_CLASS
  * Flag indicating that execution of a dispatch block object submitted to a
  * queue should prefer the QOS class assigned to the queue over the QOS class
  * assigned to the block (resp. associated with the block at the time of
  * submission). The latter will only be used if the queue in question does not
  * have an assigned QOS class, as long as doing so does not result in a QOS
  * class lower than the QOS class inherited from the queue's target queue.
  * This flag is the default when a dispatch block object is submitted to a queue
  * for asynchronous execution and has no effect when the dispatch block object
  * is invoked directly. It is ignored if DISPATCH_BLOCK_ENFORCE_QOS_CLASS is
  * also passed.
  *
  * @const DISPATCH_BLOCK_ENFORCE_QOS_CLASS
  * Flag indicating that execution of a dispatch block object submitted to a
  * queue should prefer the QOS class assigned to the block (resp. associated
  * with the block at the time of submission) over the QOS class assigned to the
  * queue, as long as doing so will not result in a lower QOS class.
  * This flag is the default when a dispatch block object is submitted to a queue
  * for synchronous execution or when the dispatch block object is invoked
  * directly.
  */
 DISPATCH_ENUM(dispatch_block_flags, unsigned long,
 	DISPATCH_BLOCK_BARRIER
 			DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x1,
 	DISPATCH_BLOCK_DETACHED
 			DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x2,
 	DISPATCH_BLOCK_ASSIGN_CURRENT
 			DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x4,
 	DISPATCH_BLOCK_NO_QOS_CLASS
 			DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x8,
 	DISPATCH_BLOCK_INHERIT_QOS_CLASS
 			DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x10,
 	DISPATCH_BLOCK_ENFORCE_QOS_CLASS
 			DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x20,
 );

 /*!
  * @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_NONNULL2 DISPATCH_RETURNS_RETAINED_BLOCK
 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 dispatch_block_t
 dispatch_block_create(dispatch_block_flags_t flags, 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_NONNULL4 DISPATCH_RETURNS_RETAINED_BLOCK
 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 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_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_NONNULL2 DISPATCH_NOTHROW
 void
 dispatch_block_perform(dispatch_block_flags_t flags,
 		DISPATCH_NOESCAPE dispatch_block_t block);

 /*!
  * @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_NONNULL1 DISPATCH_NOTHROW
 long
 dispatch_block_wait(dispatch_block_t block, dispatch_time_t timeout);

 /*!
  * @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
 void
 dispatch_block_notify(dispatch_block_t block, dispatch_queue_t queue,
 		dispatch_block_t notification_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_NOTHROW
 void
 dispatch_block_cancel(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.
  */
 API_AVAILABLE(macos(10.10), ios(8.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
 DISPATCH_NOTHROW
 long
 dispatch_block_testcancel(dispatch_block_t block);

 __END_DECLS

 DISPATCH_ASSUME_NONNULL_END

 #endif // __BLOCKS__

 #endif // __DISPATCH_BLOCK__
	/*
	* Copyright (c) 2014 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_BLOCK__
	#define __DISPATCH_BLOCK__

	#ifndef __DISPATCH_INDIRECT__
	#error "Please #include <dispatch/dispatch.h> instead of this file directly."
	#include <dispatch/base.h> // for HeaderDoc
	#endif

	#ifdef __BLOCKS__

	/*!
	* @group Dispatch block objects
	*/

	DISPATCH_ASSUME_NONNULL_BEGIN

	__BEGIN_DECLS

	/*!
	* @typedef dispatch_block_flags_t
	* Flags to pass to the dispatch_block_create* functions.
	*
	* @const DISPATCH_BLOCK_BARRIER
	* Flag indicating that a dispatch block object should act as a barrier block
	* when submitted to a DISPATCH_QUEUE_CONCURRENT queue.
	* See dispatch_barrier_async() for details.
	* This flag has no effect when the dispatch block object is invoked directly.
	*
	* @const DISPATCH_BLOCK_DETACHED
	* Flag indicating that a dispatch block object should execute disassociated
	* from current execution context attributes such as QOS class, os_activity_t
	* and properties of the current IPC request (if any). If invoked directly, the
	* block object will remove these attributes from the calling thread for the
	* duration of the block body (before applying attributes assigned to the block
	* object, if any). If submitted to a queue, the block object will be executed
	* with the attributes of the queue (or any attributes specifically assigned to
	* the block object).
	*
	* @const DISPATCH_BLOCK_ASSIGN_CURRENT
	* Flag indicating that a dispatch block object should be assigned the execution
	* context attributes that are current at the time the block object is created.
	* This applies to attributes such as QOS class, os_activity_t and properties of
	* the current IPC request (if any). If invoked directly, the block object will
	* apply these attributes to the calling thread for the duration of the block
	* body. If the block object is submitted to a queue, this flag replaces the
	* default behavior of associating the submitted block instance with the
	* execution context attributes that are current at the time of submission.
	* If a specific QOS class is assigned with DISPATCH_BLOCK_NO_QOS_CLASS or
	* dispatch_block_create_with_qos_class(), that QOS class takes precedence over
	* the QOS class assignment indicated by this flag.
	*
	* @const DISPATCH_BLOCK_NO_QOS_CLASS
	* Flag indicating that a dispatch block object should be not be assigned a QOS
	* class. If invoked directly, the block object will be executed with the QOS
	* class of the calling thread. If the block object is submitted to a queue,
	* this replaces the default behavior of associating the submitted block
	* instance with the QOS class current at the time of submission.
	* This flag is ignored if a specific QOS class is assigned with
	* dispatch_block_create_with_qos_class().
	*
	* @const DISPATCH_BLOCK_INHERIT_QOS_CLASS
	* Flag indicating that execution of a dispatch block object submitted to a
	* queue should prefer the QOS class assigned to the queue over the QOS class
	* assigned to the block (resp. associated with the block at the time of
	* submission). The latter will only be used if the queue in question does not
	* have an assigned QOS class, as long as doing so does not result in a QOS
	* class lower than the QOS class inherited from the queue's target queue.
	* This flag is the default when a dispatch block object is submitted to a queue
	* for asynchronous execution and has no effect when the dispatch block object
	* is invoked directly. It is ignored if DISPATCH_BLOCK_ENFORCE_QOS_CLASS is
	* also passed.
	*
	* @const DISPATCH_BLOCK_ENFORCE_QOS_CLASS
	* Flag indicating that execution of a dispatch block object submitted to a
	* queue should prefer the QOS class assigned to the block (resp. associated
	* with the block at the time of submission) over the QOS class assigned to the
	* queue, as long as doing so will not result in a lower QOS class.
	* This flag is the default when a dispatch block object is submitted to a queue
	* for synchronous execution or when the dispatch block object is invoked
	* directly.
	*/
	DISPATCH_ENUM(dispatch_block_flags, unsigned long,
	DISPATCH_BLOCK_BARRIER
	DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x1,
	DISPATCH_BLOCK_DETACHED
	DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x2,
	DISPATCH_BLOCK_ASSIGN_CURRENT
	DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x4,
	DISPATCH_BLOCK_NO_QOS_CLASS
	DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x8,
	DISPATCH_BLOCK_INHERIT_QOS_CLASS
	DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x10,
	DISPATCH_BLOCK_ENFORCE_QOS_CLASS
	DISPATCH_ENUM_API_AVAILABLE(macos(10.10), ios(8.0)) = 0x20,
	);

	/*!
	* @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_NONNULL2 DISPATCH_RETURNS_RETAINED_BLOCK
	DISPATCH_WARN_RESULT DISPATCH_NOTHROW
	dispatch_block_t
	dispatch_block_create(dispatch_block_flags_t flags, 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_NONNULL4 DISPATCH_RETURNS_RETAINED_BLOCK
	DISPATCH_WARN_RESULT DISPATCH_NOTHROW
	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_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_NONNULL2 DISPATCH_NOTHROW
	void
	dispatch_block_perform(dispatch_block_flags_t flags,
	DISPATCH_NOESCAPE dispatch_block_t block);

	/*!
	* @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_NONNULL1 DISPATCH_NOTHROW
	long
	dispatch_block_wait(dispatch_block_t block, dispatch_time_t timeout);

	/*!
	* @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
	void
	dispatch_block_notify(dispatch_block_t block, dispatch_queue_t queue,
	dispatch_block_t notification_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_NOTHROW
	void
	dispatch_block_cancel(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.
	*/
	API_AVAILABLE(macos(10.10), ios(8.0))
	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_WARN_RESULT DISPATCH_PURE
	DISPATCH_NOTHROW
	long
	dispatch_block_testcancel(dispatch_block_t block);

	__END_DECLS

	DISPATCH_ASSUME_NONNULL_END

	#endif // __BLOCKS__

	#endif // __DISPATCH_BLOCK__