# dispatch_block_create Creates a new dispatch block on the heap using an existing block and the given flags. ``` extern dispatch_block_t dispatch_block_create(dispatch_block_flags_t flags, dispatch_block_t block); ``` ## Parameters `flags` Configuration flags for the block object. For possible values, see [`dispatch_block_flags_t`](/documentation/Dispatch/dispatch_block_flags_t). Passing a value that is not a bitwise OR of valid flags results in `NULL` being returned. `block` The block to create the dispatch block from. ## Return Value The newly created dispatch block, or `NULL`. ## Discussion The provided block is copied to the heap and retained by the newly created dispatch block. The returned dispatch block is intended to be submitted to a dispatch queue with [`dispatch_async`](/documentation/Dispatch/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 can be waited on with [`dispatch_block_wait`](/documentation/Dispatch/dispatch_block_wait) or observed with [`dispatch_block_notify`](/documentation/Dispatch/dispatch_block_notify). If the returned dispatch block is submitted to a dispatch queue, the submitted block instance is 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`](/documentation/Dispatch/dispatch_block_flags_t/DISPATCH_BLOCK_ASSIGN_CURRENT) - [`DISPATCH_BLOCK_NO_QOS_CLASS`](/documentation/Dispatch/dispatch_block_flags_t/DISPATCH_BLOCK_NO_QOS_CLASS) - [`DISPATCH_BLOCK_DETACHED`](/documentation/Dispatch/dispatch_block_flags_t/DISPATCH_BLOCK_DETACHED) The QoS class the block object is 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`](/documentation/Dispatch/dispatch_block_flags_t/DISPATCH_BLOCK_INHERIT_QOS_CLASS) (default for asynchronous execution) - [`DISPATCH_BLOCK_ENFORCE_QOS_CLASS`](/documentation/Dispatch/dispatch_block_flags_t/DISPATCH_BLOCK_ENFORCE_QOS_CLASS) (default for synchronous execution) If the returned dispatch block is submitted directly to a serial queue and is configured to execute with a specific QoS class, the system makes 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. See [`dispatch_block_flags_t`](/documentation/Dispatch/dispatch_block_flags_t) for more information. --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)