The library libdispatch is an abstract model for expressing concurrency via simple but powerful API. More...
Defines | |
| #define | DISPATCH_DECL(name) typedef struct name##_s *name##_t |
| parseOnly | |
| #define | DISPATCH_EXTERN extern |
| #define | __DISPATCH_BUILD_FEATURE(X) X |
| #define | DISPATCH_API_VERSION 20090501+071 |
| #define | __DISPATCH_INDIRECT__ |
| #define | NSEC_PER_SEC (uint64_t)1000000000 |
| #define | NSEC_PER_MSEC (uint64_t)1000000 |
| #define | USEC_PER_SEC (uint64_t)1000000 |
| #define | NSEC_PER_USEC (uint64_t)1000 |
| #define | DISPATCH_TIME_NOW 0ull |
| #define | DISPATCH_TIME_FOREVER (~0ull) |
Typedefs | |
| typedef void * | dispatch_object_t |
| typedef void(* | dispatch_function_t )(void *) |
| typedef struct dispatch_group_s * | dispatch_group_t |
| A group of blocks submitted to queues for asynchronous invocation. | |
| typedef intptr_t | dispatch_once_t |
| A predicate for use with dispatch_once(). | |
| typedef struct dispatch_queue_s * | dispatch_queue_t |
| Dispatch queues invoke blocks submitted to them serially in FIFO order. | |
| 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. | |
| typedef struct dispatch_semaphore_s * | dispatch_semaphore_t |
| A counting semaphore. | |
| typedef struct dispatch_source_s * | dispatch_source_t |
| The dispatch framework provides a suite of interfaces for monitoring low- level system objects (file descriptors, Mach ports, signals, VFS nodes, etc.) for activity and automatically submitting event handler blocks to dispatch queues when such activity occurs. | |
| typedef struct dispatch_source_type_s * | dispatch_source_type_t |
| Constants of this type represent the class of low-level system object that is being monitored by the dispatch source. | |
| typedef uint64_t | dispatch_time_t |
| An somewhat abstract representation of time; where zero means "now" and DISPATCH_TIME_FOREVER means "infinity" and every value in between is an opaque encoding. | |
Enumerations | |
| enum | { DISPATCH_QUEUE_PRIORITY_HIGH = 2, DISPATCH_QUEUE_PRIORITY_DEFAULT = 0, DISPATCH_QUEUE_PRIORITY_LOW = -2 } |
| enum | { DISPATCH_MACH_SEND_DEAD = 0x1 } |
| enum | { DISPATCH_PROC_EXIT = 0x80000000, DISPATCH_PROC_FORK = 0x40000000, DISPATCH_PROC_EXEC = 0x20000000, DISPATCH_PROC_SIGNAL = 0x08000000 } |
| enum | { DISPATCH_VNODE_DELETE = 0x1, DISPATCH_VNODE_WRITE = 0x2, DISPATCH_VNODE_EXTEND = 0x4, DISPATCH_VNODE_ATTRIB = 0x8, DISPATCH_VNODE_LINK = 0x10, DISPATCH_VNODE_RENAME = 0x20, DISPATCH_VNODE_REVOKE = 0x40 } |
Functions | |
| dispatch_group_t | dispatch_group_create (void) |
| Creates new group with which blocks may be associated. | |
| void | dispatch_group_async (dispatch_group_t group, dispatch_queue_t queue, dispatch_block_t block) |
| Submits a block to a dispatch queue and associates the block with the given dispatch group. | |
| void | dispatch_group_async_f (dispatch_group_t group, dispatch_queue_t queue, void *context, dispatch_function_t work) |
| Submits a function to a dispatch queue and associates the block with the given dispatch group. | |
| long | dispatch_group_wait (dispatch_group_t group, dispatch_time_t timeout) |
| Wait synchronously for the previously submitted blocks to complete; returns if the blocks have not completed within the specified timeout. | |
| void | dispatch_group_notify (dispatch_group_t group, dispatch_queue_t queue, dispatch_block_t block) |
| Schedule a block to be submitted to a queue when a group of previously submitted blocks have completed. | |
| void | dispatch_group_notify_f (dispatch_group_t group, dispatch_queue_t queue, void *context, dispatch_function_t work) |
| Schedule a function to be submitted to a queue when a group of previously submitted functions have completed. | |
| void | dispatch_group_enter (dispatch_group_t group) |
| Manually indicate a block has entered the group. | |
| void | dispatch_group_leave (dispatch_group_t group) |
| Manually indicate a block in the group has completed. | |
| void | dispatch_debug (dispatch_object_t object, const char *message,...) |
| Programmatically log debug information about a dispatch object. | |
| void | dispatch_debugv (dispatch_object_t object, const char *message, va_list ap) |
| void | dispatch_retain (dispatch_object_t object) |
| Increment the reference count of a dispatch object. | |
| void | dispatch_release (dispatch_object_t object) |
| Decrement the reference count of a dispatch object. | |
| void * | dispatch_get_context (dispatch_object_t object) |
| Returns the application defined context of the object. | |
| void | dispatch_set_context (dispatch_object_t object, void *context) |
| Associates an application defined context with the object. | |
| void | dispatch_set_finalizer_f (dispatch_object_t object, dispatch_function_t finalizer) |
| Set the finalizer function for a dispatch object. | |
| void | dispatch_suspend (dispatch_object_t object) |
| Suspends the invocation of blocks on a dispatch object. | |
| void | dispatch_resume (dispatch_object_t object) |
| Resumes the invocation of blocks on a dispatch object. | |
| void | dispatch_once (dispatch_once_t *predicate, dispatch_block_t block) |
| Execute a block once and only once. | |
| void | dispatch_once_f (dispatch_once_t *predicate, void *context, void(*function)(void *)) |
| void | dispatch_async (dispatch_queue_t queue, dispatch_block_t block) |
| Submits a block for asynchronous execution on a dispatch queue. | |
| void | dispatch_async_f (dispatch_queue_t queue, void *context, dispatch_function_t work) |
| Submits a function for asynchronous execution on a dispatch queue. | |
| void | dispatch_sync (dispatch_queue_t queue, dispatch_block_t block) |
| Submits a block for synchronous execution on a dispatch queue. | |
| void | dispatch_sync_f (dispatch_queue_t queue, void *context, dispatch_function_t work) |
| Submits a function for synchronous execution on a dispatch queue. | |
| void | dispatch_apply (size_t iterations, dispatch_queue_t queue, void(^block)(size_t)) |
| Submits a block to a dispatch queue for multiple invocations. | |
| void | dispatch_apply_f (size_t iterations, dispatch_queue_t queue, void *context, void(*work)(void *, size_t)) |
| Submits a function to a dispatch queue for multiple invocations. | |
| dispatch_queue_t | dispatch_get_current_queue (void) |
| Returns the queue on which the currently executing block is running. | |
| dispatch_queue_t | dispatch_get_main_queue () |
| Returns the default queue that is bound to the main thread. | |
| dispatch_queue_t | dispatch_get_global_queue (long priority, unsigned long flags) |
| Returns a well-known global concurrent queue of a given priority level. | |
| dispatch_queue_t | dispatch_queue_create (const char *label, dispatch_queue_attr_t attr) |
| Creates a new dispatch queue to which blocks may be submitted. | |
| const char * | dispatch_queue_get_label (dispatch_queue_t queue) |
| Returns the label of the queue that was specified when the queue was created. | |
| void | dispatch_set_target_queue (dispatch_object_t object, dispatch_queue_t queue) |
| Sets the target queue for the given object. | |
| void | dispatch_main (void) |
| Execute blocks submitted to the main queue. | |
| void | dispatch_after (dispatch_time_t when, dispatch_queue_t queue, dispatch_block_t block) |
| Schedule a block for execution on a given queue at a specified time. | |
| void | dispatch_after_f (dispatch_time_t when, dispatch_queue_t queue, void *context, dispatch_function_t work) |
| Schedule a function for execution on a given queue at a specified time. | |
| dispatch_semaphore_t | dispatch_semaphore_create (long value) |
| Creates new counting semaphore with an initial value. | |
| long | dispatch_semaphore_wait (dispatch_semaphore_t dsema, dispatch_time_t timeout) |
| Wait (decrement) for a semaphore. | |
| long | dispatch_semaphore_signal (dispatch_semaphore_t dsema) |
| Signal (increment) a semaphore. | |
| dispatch_source_t | dispatch_source_create (dispatch_source_type_t type, uintptr_t handle, unsigned long mask, dispatch_queue_t queue) |
| Creates a new dispatch source to monitor low-level system objects and auto- matically submit a handler block to a dispatch queue in response to events. | |
| void | dispatch_source_set_event_handler (dispatch_source_t source, dispatch_block_t handler) |
| Sets the event handler block for the given dispatch source. | |
| void | dispatch_source_set_event_handler_f (dispatch_source_t source, dispatch_function_t handler) |
| Sets the event handler function for the given dispatch source. | |
| void | dispatch_source_set_cancel_handler (dispatch_source_t source, dispatch_block_t cancel_handler) |
| Sets the cancellation handler block for the given dispatch source. | |
| void | dispatch_source_set_cancel_handler_f (dispatch_source_t source, dispatch_function_t cancel_handler) |
| Sets the cancellation handler function for the given dispatch source. | |
| void | dispatch_source_cancel (dispatch_source_t source) |
| Asynchronously cancel the dispatch source, preventing any further invocation of its event handler block. | |
| long | dispatch_source_testcancel (dispatch_source_t source) |
| Tests whether the given dispatch source has been canceled. | |
| uintptr_t | dispatch_source_get_handle (dispatch_source_t source) |
| Returns the underlying system handle associated with this dispatch source. | |
| unsigned long | dispatch_source_get_mask (dispatch_source_t source) |
| Returns the mask of events monitored by the dispatch source. | |
| unsigned long | dispatch_source_get_data (dispatch_source_t source) |
| Returns pending data for the dispatch source. | |
| void | dispatch_source_merge_data (dispatch_source_t source, unsigned long value) |
| Merges data into a dispatch source of type DISPATCH_SOURCE_TYPE_DATA_ADD or DISPATCH_SOURCE_TYPE_DATA_OR and submits its event handler block to its target queue. | |
| void | dispatch_source_set_timer (dispatch_source_t source, dispatch_time_t start, uint64_t interval, uint64_t leeway) |
| Sets a start time, interval, and leeway value for a timer source. | |
| dispatch_time_t | dispatch_time (dispatch_time_t when, int64_t delta) |
| Create dispatch_time_t relative to the default clock or modify an existing dispatch_time_t. | |
| dispatch_time_t | dispatch_walltime (const struct timespec *when, int64_t delta) |
| Create a dispatch_time_t using the wall clock. | |
The library libdispatch is an abstract model for expressing concurrency via simple but powerful API.
At the core, libdispatch 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.
All header files needed for using libdispatch can be included by typing
#include <dispatch/dispatch.h>
You will need to link against the dispatch library.
| #define __DISPATCH_BUILD_FEATURE | ( | X | ) | X |
Definition at line 45 of file dispatch.h.
| #define __DISPATCH_INDIRECT__ |
Definition at line 61 of file dispatch.h.
| #define DISPATCH_API_VERSION 20090501+071 |
Definition at line 58 of file dispatch.h.
| #define DISPATCH_DECL | ( | name | ) | typedef struct name##_s *name##_t |
| #define DISPATCH_EXTERN extern |
| #define DISPATCH_TIME_FOREVER (~0ull) |
| #define DISPATCH_TIME_NOW 0ull |
| #define NSEC_PER_MSEC (uint64_t)1000000 |
| #define NSEC_PER_SEC (uint64_t)1000000000 |
| #define NSEC_PER_USEC (uint64_t)1000 |
| #define USEC_PER_SEC (uint64_t)1000000 |
| typedef void(^ dispatch_block_t)(void) |
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.
| typedef void(* dispatch_function_t)(void *) |
| typedef struct dispatch_group_s* dispatch_group_t |
| typedef void* dispatch_object_t |
| typedef intptr_t dispatch_once_t |
A predicate for use with dispatch_once().
It must be initialized to zero. Note: static and global variables default to zero.
| typedef struct dispatch_queue_attr_s* dispatch_queue_attr_t |
| typedef struct dispatch_queue_s* dispatch_queue_t |
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.
A counting semaphore.
Definition at line 39 of file semaphore.h.
| typedef struct dispatch_source_s* dispatch_source_t |
The dispatch framework provides a suite of interfaces for monitoring low- level system objects (file descriptors, Mach ports, signals, VFS nodes, etc.) for activity and automatically submitting event handler blocks to dispatch queues when such activity occurs.
This suite of interfaces is known as the Dispatch Source API.
Due to technical limitations of the underlying platforms, not all source types are available on all platforms. Below you can find a all supported types, listed by operating system:
Windows
Linux
Mac OS
The availability can be queried at compiletime via the preprocessor either by using
#ifdef DISPATCH_SOURCE_TYPE_* ... #endif // e.g. for querying timer support #ifdef DISPATCH_SOURCE_TYPE_TIMER ... #endif
or
#if DISPATCH_SOURCE_HAS_* ... #endif // e.g. considering timers again #if DISPATCH_SOURCE_HAS_TIMER ... #endif
The latter will be defined to 1 when the given type is available and be equal to zero if not. Dispatch sources are used to automatically submit event handler blocks to dispatch queues in response to external events.
| typedef struct dispatch_source_type_s* dispatch_source_type_t |
Constants of this type represent the class of low-level system object that is being monitored by the dispatch source.
Constants of this type are passed as a parameter to dispatch_source_create() and determine how the handle argument is interpreted (i.e. as a file descriptor, mach port, signal number, process identifer, etc.), and how the mask arugment is interpreted.
| anonymous enum |
| anonymous enum |
| anonymous enum |
| anonymous enum |
| void dispatch_after | ( | dispatch_time_t | when, |
| dispatch_queue_t | queue, | ||
| dispatch_block_t | block | ||
| ) |
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. |
| void dispatch_after_f | ( | dispatch_time_t | when, |
| dispatch_queue_t | queue, | ||
| void * | context, | ||
| dispatch_function_t | work | ||
| ) |
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. |
| void dispatch_apply | ( | size_t | iterations, |
| dispatch_queue_t | queue, | ||
| void(^)(size_t) | block | ||
| ) |
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. |
| void dispatch_apply_f | ( | size_t | iterations, |
| dispatch_queue_t | queue, | ||
| void * | context, | ||
| void(*)(void *, size_t) | work | ||
| ) |
Submits a function to a dispatch queue for multiple invocations.
| 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. |
| void dispatch_async | ( | dispatch_queue_t | queue, |
| dispatch_block_t | block | ||
| ) |
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. |
| void dispatch_async_f | ( | dispatch_queue_t | queue, |
| void * | context, | ||
| dispatch_function_t | work | ||
| ) |
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. |
| void dispatch_debug | ( | dispatch_object_t | object, |
| const char * | message, | ||
| ... | |||
| ) |
Programmatically log debug information about a dispatch object.
| object | The object to introspect. |
| message | The message to log above and beyond the introspection. |
| void dispatch_debugv | ( | dispatch_object_t | object, |
| const char * | message, | ||
| va_list | ap | ||
| ) |
| void* dispatch_get_context | ( | dispatch_object_t | object | ) |
Returns the application defined context of the object.
The result of passing NULL in this parameter is undefined.
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_queue_t dispatch_get_global_queue | ( | long | priority, |
| unsigned long | flags | ||
| ) |
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. |
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.
| void dispatch_group_async | ( | dispatch_group_t | group, |
| dispatch_queue_t | queue, | ||
| dispatch_block_t | block | ||
| ) |
Submits a block to a dispatch queue and associates the block with the given dispatch group.
Submits a block to a dispatch queue and associates the block with the given dispatch group. The dispatch group may be used to wait for the completion of the blocks it references.
| group | A dispatch group to associate with the submitted block. The result of passing NULL in this parameter is undefined. |
| queue | The dispatch queue to which the block will be submitted for asynchronous invocation. |
| block | The block to perform asynchronously. |
| void dispatch_group_async_f | ( | dispatch_group_t | group, |
| dispatch_queue_t | queue, | ||
| void * | context, | ||
| dispatch_function_t | work | ||
| ) |
Submits a function to a dispatch queue and associates the block with the given dispatch group.
| group | A dispatch group to associate with the submitted function. The result of passing NULL in this parameter is undefined. |
| queue | The dispatch queue to which the function will be submitted for asynchronous invocation. |
| 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_group_async_f(). |
| dispatch_group_t dispatch_group_create | ( | void | ) |
Creates new group with which blocks may be associated.
This function creates a new group with which blocks may be associated. The dispatch group may be used to wait for the completion of the blocks it references. The group object memory is freed with dispatch_release().
| void dispatch_group_enter | ( | dispatch_group_t | group | ) |
Manually indicate a block has entered the group.
Calling this function indicates another block has joined the group through a means other than dispatch_group_async(). Calls to this function must be balanced with dispatch_group_leave().
| group | The dispatch group to update. The result of passing NULL in this parameter is undefined. |
| void dispatch_group_leave | ( | dispatch_group_t | group | ) |
Manually indicate a block in the group has completed.
Calling this function indicates block has completed and left the dispatch groupJ by a means other than dispatch_group_async().
| group | The dispatch group to update. The result of passing NULL in this parameter is undefined. |
| void dispatch_group_notify | ( | dispatch_group_t | group, |
| dispatch_queue_t | queue, | ||
| dispatch_block_t | block | ||
| ) |
Schedule a block to be submitted to a queue when a group of previously submitted blocks have completed.
This function schedules a notification block to be submitted to the specified queue once all blocks associated with the dispatch group have completed.
If no blocks are associated with the dispatch group (i.e. the group is empty) then the notification block will be submitted immediately.
The group will be empty at the time the notification block is submitted to the target queue. The group may either be released with dispatch_release() or reused for additional operations. See dispatch_group_async() for more information.
| group | The dispatch group to observe. The result of passing NULL in this parameter is undefined. |
| queue | The queue to which the supplied block will be submitted when the group completes. |
| block | The block to submit when the group completes. |
| void dispatch_group_notify_f | ( | dispatch_group_t | group, |
| dispatch_queue_t | queue, | ||
| void * | context, | ||
| dispatch_function_t | work | ||
| ) |
Schedule a function to be submitted to a queue when a group of previously submitted functions have completed.
| group | The dispatch group to observe. 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_group_notify_f(). |
| long dispatch_group_wait | ( | dispatch_group_t | group, |
| dispatch_time_t | timeout | ||
| ) |
Wait synchronously for the previously submitted blocks to complete; returns if the blocks have not completed within the specified timeout.
This function waits for the completion of the blocks associated with the given dispatch group, and returns after all blocks have completed or when the specified timeout has elapsed. When a timeout occurs, the group is restored to its original state.
This function will return immediately if there are no blocks associated with the dispatch group (i.e. the group is empty).
The result of calling this function from mulitple threads simultaneously with the same dispatch group is undefined.
After the successful return of this function, the dispatch group is empty. It may either be released with dispatch_release() or re-used for additional blocks. See dispatch_group_async() for more information.
| group | The dispatch group to wait on. The result of passing NULL in this parameter is undefined. |
| timeout | When to timeout (see dispatch_time). As a convenience, there are the DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants. |
| void dispatch_main | ( | void | ) |
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.
| void dispatch_once | ( | dispatch_once_t * | predicate, |
| dispatch_block_t | block | ||
| ) |
Execute a block once and only once.
| predicate | A pointer to a dispatch_once_t that is used to test whether the block has completed or not. |
| block | The block to execute once. |
Always call dispatch_once() before using or testing any variables that are initialized by the block.
| void dispatch_once_f | ( | dispatch_once_t * | predicate, |
| void * | context, | ||
| void(*)(void *) | function | ||
| ) |
| dispatch_queue_t dispatch_queue_create | ( | const char * | label, |
| dispatch_queue_attr_t | attr | ||
| ) |
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. |
| const char* dispatch_queue_get_label | ( | dispatch_queue_t | queue | ) |
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. |
| void dispatch_release | ( | dispatch_object_t | object | ) |
Decrement the reference count of a dispatch object.
A dispatch object is asynchronously deallocated once all references are released (i.e. the reference count becomes zero). The system does not guarantee that a given client is the last or only reference to a given object.
| object | The object to release. The result of passing NULL in this parameter is undefined. |
| void dispatch_resume | ( | dispatch_object_t | object | ) |
Resumes the invocation of blocks on a dispatch object.
| object | The object to be resumed. The result of passing NULL in this parameter is undefined. |
| void dispatch_retain | ( | dispatch_object_t | object | ) |
Increment the reference count of a dispatch object.
Calls to dispatch_retain() must be balanced with calls to dispatch_release().
| object | The object to retain. The result of passing NULL in this parameter is undefined. |
| dispatch_semaphore_t dispatch_semaphore_create | ( | long | value | ) |
Creates new counting semaphore with an initial value.
Passing zero for the value is useful for when two threads need to reconcile the completion of a particular event. Passing a value greather than zero is useful for managing a finite pool of resources, where the pool size is equal to the value.
| value | The starting value for the semaphore. Passing a value less than zero will cause NULL to be returned. |
| long dispatch_semaphore_signal | ( | dispatch_semaphore_t | dsema | ) |
Signal (increment) a semaphore.
Increment the counting semaphore. If the previous value was less than zero, this function wakes a waiting thread before returning.
| dsema | The counting semaphore. The result of passing NULL in this parameter is undefined. |
| long dispatch_semaphore_wait | ( | dispatch_semaphore_t | dsema, |
| dispatch_time_t | timeout | ||
| ) |
Wait (decrement) for a semaphore.
Decrement the counting semaphore. If the resulting value is less than zero, this function waits in FIFO order for a signal to occur before returning.
| dsema | The semaphore. The result of passing NULL in this parameter is undefined. |
| timeout | When to timeout (see dispatch_time). As a convenience, there are the DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants. |
| void dispatch_set_context | ( | dispatch_object_t | object, |
| void * | context | ||
| ) |
Associates an application defined context with the object.
| object | The result of passing NULL in this parameter is undefined. |
| context | The new client defined context for the object. This may be NULL. |
| void dispatch_set_finalizer_f | ( | dispatch_object_t | object, |
| dispatch_function_t | finalizer | ||
| ) |
Set the finalizer function for a dispatch object.
A dispatch object's finalizer will be invoked on the object's target queue after all references to the object have been released. This finalizer may be used by the application to release any resources associated with the object, such as freeing the object's context. The context parameter passed to the finalizer function is the current context of the dispatch object at the time the finalizer call is made.
| object | The dispatch object to modify. The result of passing NULL in this parameter is undefined. |
| finalizer | The finalizer function pointer. |
| void dispatch_set_target_queue | ( | dispatch_object_t | object, |
| dispatch_queue_t | 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. |
| void dispatch_source_cancel | ( | dispatch_source_t | source | ) |
Asynchronously cancel the dispatch source, preventing any further invocation of its event handler block.
Cancellation prevents any further invocation of the event handler block for the specified dispatch source, but does not interrupt an event handler block that is already in progress.
The cancellation handler is submitted to the source's target queue once the the source's event handler has finished, indicating it is now safe to close the source's handle (i.e. file descriptor or mach port).
See dispatch_source_set_cancel_handler() for more information.
| source | The dispatch source to be canceled. The result of passing NULL in this parameter is undefined. |
| dispatch_source_t dispatch_source_create | ( | dispatch_source_type_t | type, |
| uintptr_t | handle, | ||
| unsigned long | mask, | ||
| dispatch_queue_t | queue | ||
| ) |
Creates a new dispatch source to monitor low-level system objects and auto- matically submit a handler block to a dispatch queue in response to events.
Dispatch sources are not reentrant. Any events received while the dispatch source is suspended or while the event handler block is currently executing will be coalesced and delivered after the dispatch source is resumed or the event handler block has returned.
Dispatch sources are created in a suspended state. After creating the source and setting any desired attributes (i.e. the handler, context, etc.), a call must be made to dispatch_resume() in order to begin event delivery.
| type | Declares the type of the dispatch source. Must be one of the defined dispatch_source_type_t constants. |
| handle | The underlying system handle to monitor. The interpretation of this argument is determined by the constant provided in the type parameter. |
| mask | A mask of flags specifying which events are desired. The interpretation of this argument is determined by the constant provided in the type parameter. |
| queue | The dispatch queue to which the event handler block will be submited. |
| unsigned long dispatch_source_get_data | ( | dispatch_source_t | source | ) |
Returns pending data for the dispatch source.
This function is intended to be called from within the event handler block. The result of calling this function outside of the event handler callback is undefined.
| source | The result of passing NULL in this parameter is undefined. |
DISPATCH_SOURCE_TYPE_DATA_ADD: application defined data DISPATCH_SOURCE_TYPE_DATA_OR: application defined data DISPATCH_SOURCE_TYPE_MACH_SEND: dispatch_source_mach_send_flags_t DISPATCH_SOURCE_TYPE_MACH_RECV: n/a DISPATCH_SOURCE_TYPE_PROC: dispatch_source_proc_flags_t DISPATCH_SOURCE_TYPE_READ: estimated bytes available to read DISPATCH_SOURCE_TYPE_SIGNAL: number of signals delivered since the last handler invocation DISPATCH_SOURCE_TYPE_TIMER: number of times the timer has fired since the last handler invocation DISPATCH_SOURCE_TYPE_VNODE: dispatch_source_vnode_flags_t DISPATCH_SOURCE_TYPE_WRITE: estimated buffer space available
| uintptr_t dispatch_source_get_handle | ( | dispatch_source_t | source | ) |
Returns the underlying system handle associated with this dispatch source.
| source | The result of passing NULL in this parameter is undefined. |
DISPATCH_SOURCE_TYPE_DATA_ADD: n/a DISPATCH_SOURCE_TYPE_DATA_OR: n/a DISPATCH_SOURCE_TYPE_MACH_SEND: mach port (mach_port_t) DISPATCH_SOURCE_TYPE_MACH_RECV: mach port (mach_port_t) DISPATCH_SOURCE_TYPE_PROC: process identifier (pid_t) DISPATCH_SOURCE_TYPE_READ: file descriptor (int) DISPATCH_SOURCE_TYPE_SIGNAL: signal number (int) DISPATCH_SOURCE_TYPE_TIMER: n/a DISPATCH_SOURCE_TYPE_VNODE: file descriptor (int) DISPATCH_SOURCE_TYPE_WRITE: file descriptor (int)
| unsigned long dispatch_source_get_mask | ( | dispatch_source_t | source | ) |
Returns the mask of events monitored by the dispatch source.
| source | The result of passing NULL in this parameter is undefined. |
DISPATCH_SOURCE_TYPE_DATA_ADD: n/a DISPATCH_SOURCE_TYPE_DATA_OR: n/a DISPATCH_SOURCE_TYPE_MACH_SEND: dispatch_source_mach_send_flags_t DISPATCH_SOURCE_TYPE_MACH_RECV: n/a DISPATCH_SOURCE_TYPE_PROC: dispatch_source_proc_flags_t DISPATCH_SOURCE_TYPE_READ: n/a DISPATCH_SOURCE_TYPE_SIGNAL: n/a DISPATCH_SOURCE_TYPE_TIMER: n/a DISPATCH_SOURCE_TYPE_VNODE: dispatch_source_vnode_flags_t DISPATCH_SOURCE_TYPE_WRITE: n/a
| void dispatch_source_merge_data | ( | dispatch_source_t | source, |
| unsigned long | value | ||
| ) |
Merges data into a dispatch source of type DISPATCH_SOURCE_TYPE_DATA_ADD or DISPATCH_SOURCE_TYPE_DATA_OR and submits its event handler block to its target queue.
| source | The result of passing NULL in this parameter is undefined. |
| value | The value to coalesce with the pending data using a logical OR or an ADD as specified by the dispatch source type. A value of zero has no effect and will not result in the submission of the event handler block. |
| void dispatch_source_set_cancel_handler | ( | dispatch_source_t | source, |
| dispatch_block_t | cancel_handler | ||
| ) |
Sets the cancellation handler block for the given dispatch source.
The cancellation handler (if specified) will be submitted to the source's target queue in response to a call to dispatch_source_cancel() once the system has released all references to the source's underlying handle and the source's event handler block has returned.
| source | The dispatch source to modify. The result of passing NULL in this parameter is undefined. |
| cancel_handler | The cancellation handler block to submit to the source's target queue. |
| void dispatch_source_set_cancel_handler_f | ( | dispatch_source_t | source, |
| dispatch_function_t | cancel_handler | ||
| ) |
Sets the cancellation handler function for the given dispatch source.
See dispatch_source_set_cancel_handler() for more details.
| source | The dispatch source to modify. The result of passing NULL in this parameter is undefined. |
| cancel_handler | The cancellation handler function to submit to the source's target queue. The context parameter passed to the event handler function is the current context of the dispatch source at the time the handler call is made. |
| void dispatch_source_set_event_handler | ( | dispatch_source_t | source, |
| dispatch_block_t | handler | ||
| ) |
Sets the event handler block for the given dispatch source.
| source | The dispatch source to modify. The result of passing NULL in this parameter is undefined. |
| handler | The event handler block to submit to the source's target queue. |
| void dispatch_source_set_event_handler_f | ( | dispatch_source_t | source, |
| dispatch_function_t | handler | ||
| ) |
Sets the event handler function for the given dispatch source.
| source | The dispatch source to modify. The result of passing NULL in this parameter is undefined. |
| handler | The event handler function to submit to the source's target queue. The context parameter passed to the event handler function is the current context of the dispatch source at the time the handler call is made. The result of passing NULL in this parameter is undefined. |
| void dispatch_source_set_timer | ( | dispatch_source_t | source, |
| dispatch_time_t | start, | ||
| uint64_t | interval, | ||
| uint64_t | leeway | ||
| ) |
Sets a start time, interval, and leeway value for a timer source.
Calling this function has no effect if the timer source has already been canceled.
The start time argument also determines which clock will be used for the timer. If the start time is DISPATCH_TIME_NOW or created with dispatch_time() then the timer is based on mach_absolute_time(). Otherwise, if the start time of the timer is created with dispatch_walltime() then the timer is based on gettimeofday(3).
| start | The start time of the timer. See dispatch_time() and dispatch_walltime() for more information. |
| interval | The nanosecond interval for the timer. |
| leeway | A hint given to the system by the application for the amount of leeway, in nanoseconds, that the system may defer the timer in order to align with other system activity for improved system performance or power consumption. (For example, an application might perform a periodic task every 5 minutes, with a leeway of up to 30 seconds.) Note that some latency is to be expected for all timers even when a leeway value of zero is specified. |
| long dispatch_source_testcancel | ( | dispatch_source_t | source | ) |
Tests whether the given dispatch source has been canceled.
| source | The dispatch source to be tested. The result of passing NULL in this parameter is undefined. |
| void dispatch_suspend | ( | dispatch_object_t | object | ) |
Suspends the invocation of blocks on a dispatch object.
A suspended object will not invoke any blocks associated with it. The suspension of an object will occur after any running block associated with the object completes.
Calls to dispatch_suspend() must be balanced with calls to dispatch_resume().
| object | The object to be suspended. The result of passing NULL in this parameter is undefined. |
| void dispatch_sync | ( | dispatch_queue_t | queue, |
| dispatch_block_t | block | ||
| ) |
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. |
| void dispatch_sync_f | ( | dispatch_queue_t | queue, |
| void * | context, | ||
| dispatch_function_t | work | ||
| ) |
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. |
| dispatch_time_t dispatch_time | ( | dispatch_time_t | when, |
| int64_t | delta | ||
| ) |
Create dispatch_time_t relative to the default clock or modify an existing dispatch_time_t.
On Mac OS X the default clock is based on mach_absolute_time().
| when | An optional dispatch_time_t to add nanoseconds to. If zero is passed, then dispatch_time() will use the result of mach_absolute_time(). |
| delta | Nanoseconds to add. |
| dispatch_time_t dispatch_walltime | ( | const struct timespec * | when, |
| int64_t | delta | ||
| ) |
Create a dispatch_time_t using the wall clock.
On Mac OS X the wall clock is based on gettimeofday(3).
| when | A struct timespect to add time to. If NULL is passed, then dispatch_walltime() will use the result of gettimeofday(3). |
| delta | Nanoseconds to add. |