Function

dispatch_block_create

Creates a new dispatch block on the heap using an existing block and the given flags.

Declaration

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.

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 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 or observed with 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:

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:

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 for more information.

See Also

Creating a Work Item

dispatch_block_create_with_qos_class

Creates a new dispatch block from an existing block and the given flags, and assigns it the specified quality-of-service class and relative priority.

dispatch_block_t

The prototype of blocks submitted to dispatch queues, which take no arguments and have no return value.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software