XDispatch 0.7.2
Defines | Typedefs | Enumerations | Functions
libdispatch

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.

Detailed Description

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.

Usage

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 Documentation

#define __DISPATCH_BUILD_FEATURE (   X)    X

Definition at line 45 of file dispatch.h.

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

parseOnly

Definition at line 71 of file base.h.

#define DISPATCH_EXTERN   extern

Definition at line 90 of file base.h.

#define DISPATCH_TIME_FOREVER   (~0ull)

Definition at line 72 of file time.h.

#define DISPATCH_TIME_NOW   0ull

Definition at line 71 of file time.h.

#define NSEC_PER_MSEC   (uint64_t)1000000

Definition at line 58 of file time.h.

#define NSEC_PER_SEC   (uint64_t)1000000000

Definition at line 57 of file time.h.

#define NSEC_PER_USEC   (uint64_t)1000

Definition at line 60 of file time.h.

#define USEC_PER_SEC   (uint64_t)1000000

Definition at line 59 of file time.h.


Typedef Documentation

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.

Definition at line 89 of file queue.h.

typedef void(* dispatch_function_t)(void *)

Definition at line 65 of file base.h.

typedef struct dispatch_group_s* dispatch_group_t

A group of blocks submitted to queues for asynchronous invocation.

Definition at line 37 of file group.h.

typedef void* dispatch_object_t

Definition at line 60 of file base.h.

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.

Definition at line 40 of file once.h.

typedef struct dispatch_queue_attr_s* dispatch_queue_attr_t

Attribute and policy extensions for dispatch queues.

Definition at line 57 of file queue.h.

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.

Definition at line 52 of file queue.h.

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

  • data add
  • data or
  • timer

Linux

  • data add
  • data or
  • read
  • signal
  • timer
  • vnode
  • write

Mac OS

  • data add
  • data or
  • mach send
  • mach recv
  • proc
  • read
  • signal
  • timer
  • vnode
  • write

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.

Definition at line 145 of file source.h.

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.

Definition at line 155 of file source.h.

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.

Definition at line 69 of file time.h.


Enumeration Type Documentation

anonymous enum
Enumerator:
DISPATCH_QUEUE_PRIORITY_HIGH 

Items dispatched to the queue will run at high priority, i.e.

the queue will be scheduled for execution before any default priority or low priority queue.

DISPATCH_QUEUE_PRIORITY_DEFAULT 

Items dispatched to the queue will run at the default priority, i.e.

the queue will be scheduled for execution after all high priority queues have been scheduled, but before any low priority queues have been scheduled.

DISPATCH_QUEUE_PRIORITY_LOW 

Items dispatched to the queue will run at low priority, i.e.

the queue will be scheduled for execution after all default priority and high priority queues have been scheduled.

Definition at line 300 of file queue.h.

anonymous enum
Enumerator:
DISPATCH_MACH_SEND_DEAD 

The receive right corresponding to the given send right was destroyed.

Definition at line 322 of file source.h.

anonymous enum
Enumerator:
DISPATCH_PROC_EXIT 

The process has exited (perhaps cleanly, perhaps not).

DISPATCH_PROC_FORK 

The process has created one or more child processes.

DISPATCH_PROC_EXEC 

The process has become another executable image via exec*() or posix_spawn*().

DISPATCH_PROC_SIGNAL 

A Unix signal was delivered to the process.

Definition at line 329 of file source.h.

anonymous enum
Enumerator:
DISPATCH_VNODE_DELETE 

The filesystem object was deleted from the namespace.

DISPATCH_VNODE_WRITE 

The filesystem object data changed.

DISPATCH_VNODE_EXTEND 

The filesystem object changed in size.

DISPATCH_VNODE_ATTRIB 

The filesystem object metadata changed.

DISPATCH_VNODE_LINK 

The filesystem object link count changed.

DISPATCH_VNODE_RENAME 

The filesystem object was renamed in the namespace.

DISPATCH_VNODE_REVOKE 

The filesystem object was revoked.

Definition at line 339 of file source.h.


Function Documentation

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.

Parameters:
whenA temporal milestone returned by dispatch_time() or dispatch_walltime().
queueA queue to which the given block will be submitted at the specified time. The result of passing NULL in this parameter is undefined.
blockThe 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.

Parameters:
whenA temporal milestone returned by dispatch_time() or dispatch_walltime().
queueA queue to which the given function will be submitted at the specified time. The result of passing NULL in this parameter is undefined.
contextThe application-defined context parameter to pass to the function.
workThe 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.

Parameters:
iterationsThe number of iterations to perform.
queueThe target dispatch queue to which the block is submitted. The result of passing NULL in this parameter is undefined.
blockThe 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.

See also:
dispatch_apply
Parameters:
iterationsThe number of iterations to perform.
queueThe target dispatch queue to which the function is submitted. The result of passing NULL in this parameter is undefined.
contextThe application-defined context parameter to pass to the function.
workThe 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.

Parameters:
queueThe 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.
blockThe 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.

Parameters:
queueThe 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.
contextThe application-defined context parameter to pass to the function.
workThe 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.

Parameters:
objectThe object to introspect.
messageThe message to log above and beyond the introspection.
void dispatch_debugv ( dispatch_object_t  object,
const char *  message,
va_list  ap 
)

Returns the application defined context of the object.

The result of passing NULL in this parameter is undefined.

Returns:
The context of the object; may be NULL.

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.

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

Parameters:
priorityA priority defined in dispatch_queue_priority_t
flagsReserved for future use. Passing any value other than zero may result in a NULL return value.
Returns:
Returns the requested global 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.

Returns:
Returns the main queue. This queue is created automatically on behalf of the main thread before main() is called.

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.

Parameters:
groupA dispatch group to associate with the submitted block. The result of passing NULL in this parameter is undefined.
queueThe dispatch queue to which the block will be submitted for asynchronous invocation.
blockThe 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.

See also:
dispatch_group_async
Parameters:
groupA dispatch group to associate with the submitted function. The result of passing NULL in this parameter is undefined.
queueThe dispatch queue to which the function will be submitted for asynchronous invocation.
contextThe application-defined context parameter to pass to the function.
workThe 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().

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().

Returns:
The newly created group, or NULL on failure.

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().

Parameters:
groupThe dispatch group to update. The result of passing NULL in this parameter is undefined.

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().

Parameters:
groupThe dispatch group to update. The result of passing NULL in this parameter is undefined.

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.

Parameters:
groupThe dispatch group to observe. The result of passing NULL in this parameter is undefined.
queueThe queue to which the supplied block will be submitted when the group completes.
blockThe 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.

See also:
dispatch_group_notify
Parameters:
groupThe dispatch group to observe. The result of passing NULL in this parameter is undefined.
contextThe application-defined context parameter to pass to the function.
workThe 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.

Parameters:
groupThe dispatch group to wait on. The result of passing NULL in this parameter is undefined.
timeoutWhen to timeout (see dispatch_time). As a convenience, there are the DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants.
Returns:
Returns zero on success (all blocks associated with the group completed within the specified timeout) or non-zero on error (i.e. timed out).
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.

Remarks:
Applications that call NSApplicationMain() or CFRunLoopRun() on the main thread, call xdispatch::exec() or exec() on a QDispatchApplication object do not need to call dispatch_main().
void dispatch_once ( dispatch_once_t predicate,
dispatch_block_t  block 
)

Execute a block once and only once.

Parameters:
predicateA pointer to a dispatch_once_t that is used to test whether the block has completed or not.
blockThe 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.

Parameters:
labelA string label to attach to the queue. This parameter is optional and may be NULL.
attrUnused. Pass NULL for now.
Returns:
The newly created dispatch queue.

Returns the label of the queue that was specified when the queue was created.

Parameters:
queueThe result of passing NULL in this parameter is undefined.
Returns:
The label of the queue. The result may be NULL.

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.

Parameters:
objectThe object to release. The result of passing NULL in this parameter is undefined.

Resumes the invocation of blocks on a dispatch object.

Parameters:
objectThe object to be resumed. The result of passing NULL in this parameter is undefined.

Increment the reference count of a dispatch object.

Calls to dispatch_retain() must be balanced with calls to dispatch_release().

Parameters:
objectThe object to retain. The result of passing NULL in this parameter is undefined.

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.

Parameters:
valueThe starting value for the semaphore. Passing a value less than zero will cause NULL to be returned.
Returns:
The newly created semaphore, or NULL on failure.

Signal (increment) a semaphore.

Increment the counting semaphore. If the previous value was less than zero, this function wakes a waiting thread before returning.

Parameters:
dsemaThe counting semaphore. The result of passing NULL in this parameter is undefined.
Returns:
This function returns non-zero if a thread is woken. Otherwise, zero is returned.

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.

Parameters:
dsemaThe semaphore. The result of passing NULL in this parameter is undefined.
timeoutWhen to timeout (see dispatch_time). As a convenience, there are the DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants.
Returns:
Returns zero on success, or non-zero if the timeout occurred.
void dispatch_set_context ( dispatch_object_t  object,
void *  context 
)

Associates an application defined context with the object.

Parameters:
objectThe result of passing NULL in this parameter is undefined.
contextThe new client defined context for the object. This may be NULL.

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.

Parameters:
objectThe dispatch object to modify. The result of passing NULL in this parameter is undefined.
finalizerThe finalizer function pointer.

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.

Parameters:
objectThe object to modify. The result of passing NULL in this parameter is undefined.
queueThe 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.

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.

Parameters:
sourceThe 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.

Parameters:
typeDeclares the type of the dispatch source. Must be one of the defined dispatch_source_type_t constants.
handleThe underlying system handle to monitor. The interpretation of this argument is determined by the constant provided in the type parameter.
maskA mask of flags specifying which events are desired. The interpretation of this argument is determined by the constant provided in the type parameter.
queueThe 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.

Parameters:
sourceThe result of passing NULL in this parameter is undefined.
Returns:
The return value should be interpreted according to the type of the dispatch source, and may be one of the following:

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

Returns the underlying system handle associated with this dispatch source.

Parameters:
sourceThe result of passing NULL in this parameter is undefined.
Returns:
The return value should be interpreted according to the type of the dispatch source, and may be one of the following handles:

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.

Parameters:
sourceThe result of passing NULL in this parameter is undefined.
Returns:
The return value should be interpreted according to the type of the dispatch source, and may be one of the following flag sets:

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.

Parameters:
sourceThe result of passing NULL in this parameter is undefined.
valueThe 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.

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.

Remarks:
A cancellation handler is required for file descriptor and mach port based sources in order to safely close the descriptor or destroy the port. Closing the descriptor or port before the cancellation handler may result in a race condition. If a new descriptor is allocated with the same value as the recently closed descriptor while the source's event handler is still running, the event handler may read/write data to the wrong descriptor.
Parameters:
sourceThe dispatch source to modify. The result of passing NULL in this parameter is undefined.
cancel_handlerThe cancellation handler block to submit to the source's target queue.

Sets the cancellation handler function for the given dispatch source.

See dispatch_source_set_cancel_handler() for more details.

Parameters:
sourceThe dispatch source to modify. The result of passing NULL in this parameter is undefined.
cancel_handlerThe 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.

Sets the event handler block for the given dispatch source.

Parameters:
sourceThe dispatch source to modify. The result of passing NULL in this parameter is undefined.
handlerThe event handler block to submit to the source's target queue.

Sets the event handler function for the given dispatch source.

Parameters:
sourceThe dispatch source to modify. The result of passing NULL in this parameter is undefined.
handlerThe 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).

Parameters:
startThe start time of the timer. See dispatch_time() and dispatch_walltime() for more information.
intervalThe nanosecond interval for the timer.
leewayA 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.

Tests whether the given dispatch source has been canceled.

Parameters:
sourceThe dispatch source to be tested. The result of passing NULL in this parameter is undefined.
Returns:
Non-zero if canceled and zero if not canceled.

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().

Parameters:
objectThe 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.

Parameters:
queueThe target dispatch queue to which the block is submitted. The result of passing NULL in this parameter is undefined.
blockThe 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.

Parameters:
queueThe target dispatch queue to which the function is submitted. The result of passing NULL in this parameter is undefined.
contextThe application-defined context parameter to pass to the function.
workThe 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().

Parameters:
whenAn optional dispatch_time_t to add nanoseconds to. If zero is passed, then dispatch_time() will use the result of mach_absolute_time().
deltaNanoseconds to add.
Returns:
A new dispatch_time_t.
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).

Parameters:
whenA struct timespect to add time to. If NULL is passed, then dispatch_walltime() will use the result of gettimeofday(3).
deltaNanoseconds to add.
Returns:
A new dispatch_time_t.
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on Sun Jan 27 2013 21:21:52 for XDispatch by Doxygen 1.7.6.1
© 2010-2013 MLBA (about | privacy) All Rights reserved.