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)
