#include "base.h"Go to the source code of this file.
Typedefs | |
| typedef struct dispatch_queue_s * | dispatch_queue_t |
| | |
| typedef struct dispatch_queue_attr_s * | dispatch_queue_attr_t |
| Attribute and policy extensions for dispatch queues. | |
| typedef void(^ | dispatch_block_t )(void) |
| The prototype of blocks submitted to dispatch queues, which take no arguments and have no return value. | |
Enumerations | |
| enum | { DISPATCH_QUEUE_PRIORITY_HIGH = 2, DISPATCH_QUEUE_PRIORITY_DEFAULT = 0, DISPATCH_QUEUE_PRIORITY_LOW = -2 } |
Functions | |
| DISPATCH_NONNULL_ALL DISPATCH_NOTHROW void | dispatch_async (dispatch_queue_t queue, dispatch_block_t block) |
| dispatch_async | |
| DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW void | dispatch_async_f (dispatch_queue_t queue, void *context, dispatch_function_t work) |
| dispatch_async_f | |
| DISPATCH_NONNULL_ALL DISPATCH_NOTHROW void | dispatch_sync (dispatch_queue_t queue, dispatch_block_t block) |
| dispatch_sync | |
| DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW void | dispatch_sync_f (dispatch_queue_t queue, void *context, dispatch_function_t work) |
| dispatch_sync_f | |
| DISPATCH_NONNULL_ALL DISPATCH_NOTHROW void | dispatch_apply (size_t iterations, dispatch_queue_t queue, void(^block)(size_t)) |
| dispatch_apply | |
| DISPATCH_NONNULL2 DISPATCH_NONNULL4 DISPATCH_NOTHROW void | dispatch_apply_f (size_t iterations, dispatch_queue_t queue, void *context, void(*work)(void *, size_t)) |
| dispatch_apply_f | |
| DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW dispatch_queue_t | dispatch_get_current_queue (void) |
| dispatch_get_current_queue | |
| dispatch_queue_t | dispatch_get_main_queue () |
| dispatch_get_main_queue | |
| DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW dispatch_queue_t | dispatch_get_global_queue (long priority, unsigned long flags) |
| dispatch_get_global_queue | |
| DISPATCH_MALLOC DISPATCH_WARN_RESULT DISPATCH_NOTHROW dispatch_queue_t | dispatch_queue_create (const char *label, dispatch_queue_attr_t attr) |
| dispatch_queue_create | |
| DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW const char * | dispatch_queue_get_label (dispatch_queue_t queue) |
| dispatch_queue_get_label | |
| DISPATCH_NONNULL_ALL DISPATCH_NOTHROW void | dispatch_set_target_queue (dispatch_object_t object, dispatch_queue_t queue) |
| dispatch_set_target_queue | |
| DISPATCH_NOTHROW DISPATCH_NORETURN void | dispatch_main (void) |
| dispatch_main | |
| DISPATCH_NONNULL2 DISPATCH_NONNULL3 DISPATCH_NOTHROW void | dispatch_after (dispatch_time_t when, dispatch_queue_t queue, dispatch_block_t block) |
| dispatch_after | |
| DISPATCH_NONNULL2 DISPATCH_NONNULL4 DISPATCH_NOTHROW void | dispatch_after_f (dispatch_time_t when, dispatch_queue_t queue, void *context, dispatch_function_t work) |
| dispatch_after_f | |
The prototype of blocks submitted to dispatch queues, which take no arguments and have no return value.
The declaration of a block allocates storage on the stack. Therefore, this is an invalid construct:
dispatch_block_t block;
if (x) { block = ^{ printf("true\n"); }; } else { block = ^{ printf("false\n"); }; } block(); // unsafe!!!
What is happening behind the scenes:
if (x) { struct Block __tmp_1 = ...; // setup details block = } else { struct Block __tmp_2 = ...; // setup details block = }
As the example demonstrates, the address of a stack variable is escaping the scope in which it is allocated. That is a classic C bug.
Dispatch is an abstract model for expressing concurrency via simple but powerful API.
At the core, dispatch provides serial FIFO queues to which blocks may be submitted. Blocks submitted to these dispatch queues are invoked on a pool of threads fully managed by the system. No guarantee is made regarding which thread a block will be invoked on; however, it is guaranteed that only one block submitted to the FIFO dispatch queue will be invoked at a time.
When multiple queues have blocks to be processed, the system is free to allocate additional threads to invoke the blocks concurrently. When the queues become empty, these threads are automatically released.
Dispatch queues invoke blocks submitted to them serially in FIFO order. A queue will only invoke one block at a time, but independent queues may each invoke their blocks concurrently with respect to each other.
Dispatch queues are lightweight objects to which blocks may be submitted. The system manages a pool of threads which process dispatch queues and invoke blocks submitted to them.
Conceptually a dispatch queue may have its own thread of execution, and interaction between queues is highly asynchronous.
Dispatch queues are reference counted via calls to dispatch_retain() and dispatch_release(). Pending blocks submitted to a queue also hold a reference to the queue until they have finished. Once all references to a queue have been released, the queue will be deallocated by the system.
| anonymous enum |
| DISPATCH_NONNULL2 DISPATCH_NONNULL3 DISPATCH_NOTHROW void dispatch_after | ( | dispatch_time_t | when, |
| dispatch_queue_t | queue, | ||
| dispatch_block_t | block | ||
| ) |
dispatch_after
Schedule a block for execution on a given queue at a specified time.
Passing DISPATCH_TIME_NOW as the "when" parameter is supported, but not as optimal as calling dispatch_async() instead. Passing DISPATCH_TIME_FOREVER is undefined.
| when | A temporal milestone returned by dispatch_time() or dispatch_walltime(). |
| queue | A queue to which the given block will be submitted at the specified time. The result of passing NULL in this parameter is undefined. |
| block | The block of code to execute. The result of passing NULL in this parameter is undefined. |
| DISPATCH_NONNULL2 DISPATCH_NONNULL4 DISPATCH_NOTHROW void dispatch_after_f | ( | dispatch_time_t | when, |
| dispatch_queue_t | queue, | ||
| void * | context, | ||
| dispatch_function_t | work | ||
| ) |
dispatch_after_f
Schedule a function for execution on a given queue at a specified time.
See dispatch_after() for details.
| when | A temporal milestone returned by dispatch_time() or dispatch_walltime(). |
| queue | A queue to which the given function will be submitted at the specified time. The result of passing NULL in this parameter is undefined. |
| context | The application-defined context parameter to pass to the function. |
| work | The application-defined function to invoke on the target queue. The first parameter passed to this function is the context provided to dispatch_after_f(). The result of passing NULL in this parameter is undefined. |
| DISPATCH_NONNULL_ALL DISPATCH_NOTHROW void dispatch_apply | ( | size_t | iterations, |
| dispatch_queue_t | queue, | ||
| void(^)(size_t) | block | ||
| ) |
dispatch_apply
Submits a block to a dispatch queue for multiple invocations.
Submits a block to a dispatch queue for multiple invocations. This function waits for the task block to complete before returning. If the target queue is a concurrent queue returned by dispatch_get_concurrent_queue(), the block may be invoked concurrently, and it must therefore be reentrant safe.
Each invocation of the block will be passed the current index of iteration.
| iterations | The number of iterations to perform. |
| queue | The target dispatch queue to which the block is submitted. The result of passing NULL in this parameter is undefined. |
| block | The block to be invoked the specified number of iterations. The result of passing NULL in this parameter is undefined. |
| DISPATCH_NONNULL2 DISPATCH_NONNULL4 DISPATCH_NOTHROW void dispatch_apply_f | ( | size_t | iterations, |
| dispatch_queue_t | queue, | ||
| void * | context, | ||
| void(*)(void *, size_t) | work | ||
| ) |
dispatch_apply_f
Submits a function to a dispatch queue for multiple invocations.
See dispatch_apply() for details.
| iterations | The number of iterations to perform. |
| queue | The target dispatch queue to which the function is submitted. The result of passing NULL in this parameter is undefined. |
| context | The application-defined context parameter to pass to the function. |
| work | The application-defined function to invoke on the target queue. The first parameter passed to this function is the context provided to dispatch_apply_f(). The second parameter passed to this function is the current index of iteration. The result of passing NULL in this parameter is undefined. |
| DISPATCH_NONNULL_ALL DISPATCH_NOTHROW void dispatch_async | ( | dispatch_queue_t | queue, |
| dispatch_block_t | block | ||
| ) |
dispatch_async
Submits a block for asynchronous execution on a dispatch queue.
The dispatch_async() function is the fundamental mechanism for submitting blocks to a dispatch queue.
Calls to dispatch_async() always return immediately after the block has been submitted, and never wait for the block to be invoked.
The target queue determines whether the block will be invoked serially or concurrently with respect to other blocks submitted to that same queue. Serial queues are processed concurrently with with respect to each other.
| queue | The target dispatch queue to which the block is submitted. The system will hold a reference on the target queue until the block has finished. The result of passing NULL in this parameter is undefined. |
| block | The block to submit to the target dispatch queue. This function performs Block_copy() and Block_release() on behalf of callers. The result of passing NULL in this parameter is undefined. |
| DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW void dispatch_async_f | ( | dispatch_queue_t | queue, |
| void * | context, | ||
| dispatch_function_t | work | ||
| ) |
dispatch_async_f
Submits a function for asynchronous execution on a dispatch queue.
See dispatch_async() for details.
| queue | The target dispatch queue to which the function is submitted. The system will hold a reference on the target queue until the function has returned. The result of passing NULL in this parameter is undefined. |
| context | The application-defined context parameter to pass to the function. |
| work | The application-defined function to invoke on the target queue. The first parameter passed to this function is the context provided to dispatch_async_f(). The result of passing NULL in this parameter is undefined. |
| DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW dispatch_queue_t dispatch_get_current_queue | ( | void | ) |
dispatch_get_current_queue
Returns the queue on which the currently executing block is running.
Returns the queue on which the currently executing block is running.
When dispatch_get_current_queue() is called outside of the context of a submitted block, it will return the default concurrent queue.
| DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW dispatch_queue_t dispatch_get_global_queue | ( | long | priority, |
| unsigned long | flags | ||
| ) |
dispatch_get_global_queue
Returns a well-known global concurrent queue of a given priority level.
The well-known global concurrent queues may not be modified. Calls to dispatch_suspend(), dispatch_resume(), dispatch_set_context(), etc., will have no effect when used with queues returned by this function.
| priority | A priority defined in dispatch_queue_priority_t |
| flags | Reserved for future use. Passing any value other than zero may result in a NULL return value. |
| dispatch_queue_t dispatch_get_main_queue | ( | ) |
dispatch_get_main_queue
Returns the default queue that is bound to the main thread.
In order to invoke blocks submitted to the main queue, the application must call dispatch_main(), NSApplicationMain(), or use a CFRunLoop on the main thread.
| DISPATCH_NOTHROW DISPATCH_NORETURN void dispatch_main | ( | void | ) |
dispatch_main
Execute blocks submitted to the main queue.
This function "parks" the main thread and waits for blocks to be submitted to the main queue. This function never returns.
Applications that call NSApplicationMain() or CFRunLoopRun() on the main thread do not need to call dispatch_main().
| DISPATCH_MALLOC DISPATCH_WARN_RESULT DISPATCH_NOTHROW dispatch_queue_t dispatch_queue_create | ( | const char * | label, |
| dispatch_queue_attr_t | attr | ||
| ) |
dispatch_queue_create
Creates a new dispatch queue to which blocks may be submitted.
Dispatch queues invoke blocks serially in FIFO order.
When the dispatch queue is no longer needed, it should be released with dispatch_release(). Note that any pending blocks submitted to a queue will hold a reference to that queue. Therefore a queue will not be deallocated until all pending blocks have finished.
| label | A string label to attach to the queue. This parameter is optional and may be NULL. |
| attr | Unused. Pass NULL for now. |
| DISPATCH_NONNULL_ALL DISPATCH_PURE DISPATCH_WARN_RESULT DISPATCH_NOTHROW const char* dispatch_queue_get_label | ( | dispatch_queue_t | queue | ) |
dispatch_queue_get_label
Returns the label of the queue that was specified when the queue was created.
| queue | The result of passing NULL in this parameter is undefined. |
| DISPATCH_NONNULL_ALL DISPATCH_NOTHROW void dispatch_set_target_queue | ( | dispatch_object_t | object, |
| dispatch_queue_t | queue | ||
| ) |
dispatch_set_target_queue
Sets the target queue for the given object.
An object's target queue is responsible for processing the object.
A dispatch queue's priority is inherited by its target queue. Use the dispatch_get_global_queue() function to obtain suitable target queue of the desired priority.
A dispatch source's target queue specifies where its event handler and cancellation handler blocks will be submitted.
The result of calling dispatch_set_target_queue() on any other type of dispatch object is undefined.
| object | The object to modify. The result of passing NULL in this parameter is undefined. |
| queue | The new target queue for the object. The queue is retained, and the previous one, if any, is released. The result of passing NULL in this parameter is undefined. |
| DISPATCH_NONNULL_ALL DISPATCH_NOTHROW void dispatch_sync | ( | dispatch_queue_t | queue, |
| dispatch_block_t | block | ||
| ) |
dispatch_sync
Submits a block for synchronous execution on a dispatch queue.
Submits a block to a dispatch queue like dispatch_async(), however dispatch_sync() will not return until the block has finished.
Calls to dispatch_sync() targeting the current queue will result in dead-lock. Use of dispatch_sync() is also subject to the same multi-party dead-lock problems that may result from the use of a mutex. Use of dispatch_async() is preferred.
Unlike dispatch_async(), no retain is performed on the target queue. Because calls to this function are synchronous, the dispatch_sync() "borrows" the reference of the caller.
As an optimization, dispatch_sync() invokes the block on the current thread when possible.
| queue | The target dispatch queue to which the block is submitted. The result of passing NULL in this parameter is undefined. |
| block | The block to be invoked on the target dispatch queue. The result of passing NULL in this parameter is undefined. |
| DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW void dispatch_sync_f | ( | dispatch_queue_t | queue, |
| void * | context, | ||
| dispatch_function_t | work | ||
| ) |
dispatch_sync_f
Submits a function for synchronous execution on a dispatch queue.
See dispatch_sync() for details.
| queue | The target dispatch queue to which the function is submitted. The result of passing NULL in this parameter is undefined. |
| context | The application-defined context parameter to pass to the function. |
| work | The application-defined function to invoke on the target queue. The first parameter passed to this function is the context provided to dispatch_sync_f(). The result of passing NULL in this parameter is undefined. |