dispatch_block_create

dispatch2

Function dispatch_block_create 

Source 
pub unsafe extern "C" fn dispatch_block_create(
    flags: dispatch_block_flags_t,
    block: dispatch_block_t,
) -> dispatch_block_t
Expand description

Create a new dispatch block object on the heap from an existing block and the given flags.

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.

Parameter 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.

Parameter block: The block to create the dispatch block object from.

Returns: 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.