NAME

     dispatch_group_create, dispatch_group_async, dispatch_group_wait, dispatch_group_notify —
     group blocks submitted to queues

SYNOPSIS

     #include <dispatch/dispatch.h>

     dispatch_group_t
     dispatch_group_create(void);

     void
     dispatch_group_enter(dispatch_group_t group);

     void
     dispatch_group_leave(dispatch_group_t group);

     long
     dispatch_group_wait(dispatch_group_t group, dispatch_time_t timeout);

     void
     dispatch_group_notify(dispatch_group_t group, dispatch_queue_t queue, void (^block)(void));

     void
     dispatch_group_notify_f(dispatch_group_t group, dispatch_queue_t queue, void *context,
         void (*function)(void *));

     void
     dispatch_group_async(dispatch_group_t group, dispatch_queue_t queue, void (^block)(void));

     void
     dispatch_group_async_f(dispatch_group_t group, dispatch_queue_t queue, void *context,
         void (*function)(void *));

DESCRIPTION

     A dispatch group is an association of one or more blocks submitted to dispatch queues for
     asynchronous invocation.  Applications may use dispatch groups to wait for the completion of
     blocks associated with the group.

     The dispatch_group_create() function returns a new and empty dispatch group.

     The dispatch_group_enter() and dispatch_group_leave() functions update the number of blocks
     running within a group.

     The dispatch_group_wait() function waits until all blocks associated with the group have
     completed, or until the specified timeout has elapsed.  If the group becomes empty within
     the specified amount of time, the function will return zero indicating success. Otherwise, a
     non-zero return code will be returned.  When DISPATCH_TIME_FOREVER is passed as the timeout,
     calls to this function will wait an unlimited amount of time until the group becomes empty
     and the return value is always zero.

     The dispatch_group_notify() function provides asynchronous notification of the completion of
     the blocks associated with the group by submitting the block to the specified queue once all
     blocks associated with the group have completed.  The system holds a reference to the
     dispatch group while an asynchronous notification is pending, therefore it is valid to
     release the group after setting a notification block.  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.

     The dispatch_group_async() convenience function behaves like so:

     void
     dispatch_group_async(dispatch_group_t group, dispatch_queue_t queue, dispatch_block_t block)
     {
             dispatch_retain(group);
             dispatch_group_enter(group);
             dispatch_async(queue, ^{
                     block();
                     dispatch_group_leave(group);
                     dispatch_release(group);
             });
     }

RETURN VALUE

     The dispatch_group_create() function returns NULL on failure and non-NULL on success.

     The dispatch_group_wait() function returns zero upon success and non-zero after the timeout
     expires.  If the timeout is DISPATCH_TIME_FOREVER, then dispatch_group_wait() waits forever
     and always returns zero.

MEMORY MODEL

     Dispatch groups are retained and released via calls to dispatch_retain() and
     dispatch_release().

FUNDAMENTALS

     The dispatch_group_async() and dispatch_group_notify() functions are wrappers around
     dispatch_group_async_f() and dispatch_group_notify_f() respectively.

SEE ALSO

     dispatch(3), dispatch_async(3), dispatch_object(3), dispatch_queue_create(3),
     dispatch_semaphore_create(3), dispatch_time(3)