| /* |
| * 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__ |