afb81b8278
Some checks failed
Docker. / Ubuntu (push) Has been cancelled
User-agent updater. / User-agent (push) Failing after 15s
Lock Threads / lock (push) Failing after 10s
Waiting for answer. / waiting-for-answer (push) Failing after 22s
Close stale issues and PRs / stale (push) Successful in 13s
Needs user action. / needs-user-action (push) Failing after 8s
Can't reproduce. / cant-reproduce (push) Failing after 8s
181 lines
5.0 KiB
Groff
181 lines
5.0 KiB
Groff
.\" Copyright (c) 2008-2012 Apple Inc. All rights reserved.
|
|
.Dd May 1, 2009
|
|
.Dt dispatch_group_create 3
|
|
.Os Darwin
|
|
.Sh NAME
|
|
.Nm dispatch_group_create ,
|
|
.Nm dispatch_group_async ,
|
|
.Nm dispatch_group_wait ,
|
|
.Nm dispatch_group_notify
|
|
.Nd group blocks submitted to queues
|
|
.Sh SYNOPSIS
|
|
.Fd #include <dispatch/dispatch.h>
|
|
.Ft dispatch_group_t
|
|
.Fo dispatch_group_create
|
|
.Fa void
|
|
.Fc
|
|
.Ft void
|
|
.Fo dispatch_group_enter
|
|
.Fa "dispatch_group_t group"
|
|
.Fc
|
|
.Ft void
|
|
.Fo dispatch_group_leave
|
|
.Fa "dispatch_group_t group"
|
|
.Fc
|
|
.Ft long
|
|
.Fo dispatch_group_wait
|
|
.Fa "dispatch_group_t group" "dispatch_time_t timeout"
|
|
.Fc
|
|
.Ft void
|
|
.Fo dispatch_group_notify
|
|
.Fa "dispatch_group_t group" "dispatch_queue_t queue" "void (^block)(void)"
|
|
.Fc
|
|
.Ft void
|
|
.Fo dispatch_group_notify_f
|
|
.Fa "dispatch_group_t group" "dispatch_queue_t queue" "void *context" "void (*function)(void *)"
|
|
.Fc
|
|
.Ft void
|
|
.Fo dispatch_group_async
|
|
.Fa "dispatch_group_t group" "dispatch_queue_t queue" "void (^block)(void)"
|
|
.Fc
|
|
.Ft void
|
|
.Fo dispatch_group_async_f
|
|
.Fa "dispatch_group_t group" "dispatch_queue_t queue" "void *context" "void (*function)(void *)"
|
|
.Fc
|
|
.Sh 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.
|
|
.Pp
|
|
The
|
|
.Fn dispatch_group_create
|
|
function returns a new and empty dispatch group.
|
|
.Pp
|
|
The
|
|
.Fn dispatch_group_enter
|
|
and
|
|
.Fn dispatch_group_leave
|
|
functions update the number of blocks running within a group.
|
|
.Pp
|
|
The
|
|
.Fn dispatch_group_wait
|
|
function waits until all blocks associated with the
|
|
.Fa group
|
|
have completed, or until the specified
|
|
.Fa timeout
|
|
has elapsed.
|
|
If the
|
|
.Fa 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
|
|
.Va DISPATCH_TIME_FOREVER
|
|
is passed as the
|
|
.Fa timeout ,
|
|
calls to this function will wait an unlimited amount of time until the group
|
|
becomes empty and the return value is always zero.
|
|
.Pp
|
|
The
|
|
.Fn dispatch_group_notify
|
|
function provides asynchronous notification of the completion of the blocks
|
|
associated with the
|
|
.Fa group
|
|
by submitting the
|
|
.Fa block
|
|
to the specified
|
|
.Fa queue
|
|
once all blocks associated with the
|
|
.Fa 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
|
|
.Fa 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
|
|
.Fn dispatch_release
|
|
or reused for additional operations.
|
|
.Pp
|
|
The
|
|
.Fn dispatch_group_async
|
|
convenience function behaves like so:
|
|
.Bd -literal
|
|
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);
|
|
});
|
|
}
|
|
.Ed
|
|
.Sh RETURN VALUE
|
|
The
|
|
.Fn dispatch_group_create
|
|
function returns NULL on failure and non-NULL on success.
|
|
.Pp
|
|
The
|
|
.Fn dispatch_group_wait
|
|
function returns zero upon success and non-zero after the timeout expires.
|
|
If the timeout is
|
|
.Va DISPATCH_TIME_FOREVER ,
|
|
then
|
|
.Fn dispatch_group_wait
|
|
waits forever and always returns zero.
|
|
.Sh MEMORY MODEL
|
|
Dispatch groups are retained and released via calls to
|
|
.Fn dispatch_retain
|
|
and
|
|
.Fn dispatch_release .
|
|
.Sh FUNDAMENTALS
|
|
The
|
|
.Fn dispatch_group_async
|
|
and
|
|
.Fn dispatch_group_notify
|
|
functions are wrappers around
|
|
.Fn dispatch_group_async_f
|
|
and
|
|
.Fn dispatch_group_notify_f
|
|
respectively.
|
|
.Sh CAVEATS
|
|
In order to ensure deterministic behavior, it is recommended to call
|
|
.Fn dispatch_group_wait
|
|
only once all blocks have been submitted to the group. If it is later
|
|
determined that new blocks should be run, it is recommended not to reuse an
|
|
already-running group, but to create a new group.
|
|
.Pp
|
|
.Fn dispatch_group_wait
|
|
returns as soon as there are exactly zero
|
|
.Em enqueued or running
|
|
blocks associated with a group (more precisely, as soon as every
|
|
.Fn dispatch_group_enter
|
|
call has been balanced by a
|
|
.Fn dispatch_group_leave
|
|
call). If one thread waits for a group while another thread submits
|
|
new blocks to the group, then the count of associated blocks might
|
|
momentarily reach zero before all blocks have been submitted. If this happens,
|
|
.Fn dispatch_group_wait
|
|
will return too early: some blocks associated with the group have finished,
|
|
but some have not yet been submitted or run.
|
|
.Pp
|
|
However, as a special case, a block associated with a group may submit new
|
|
blocks associated with its own group. In this case, the behavior is
|
|
deterministic: a waiting thread will
|
|
.Em not
|
|
wake up until the newly submitted blocks have also finished.
|
|
.Pp
|
|
All of the foregoing also applies to
|
|
.Fn dispath_group_notify
|
|
as well, with "block to be submitted" substituted for "waiting thread".
|
|
.Sh SEE ALSO
|
|
.Xr dispatch 3 ,
|
|
.Xr dispatch_async 3 ,
|
|
.Xr dispatch_object 3 ,
|
|
.Xr dispatch_queue_create 3 ,
|
|
.Xr dispatch_semaphore_create 3 ,
|
|
.Xr dispatch_time 3
|