dispatch_group_create(3)

1dispatch_group_create(3) BSD Library Functions Manual dispatch_group_create(3)
2

NAME

4     dispatch_group_create, dispatch_group_async, dispatch_group_wait,
5     dispatch_group_notify — group blocks submitted to queues
6

SYNOPSIS

8     #include <dispatch/dispatch.h>
9
10     dispatch_group_t
11     dispatch_group_create(void);
12
13     void
14     dispatch_group_enter(dispatch_group_t group);
15
16     void
17     dispatch_group_leave(dispatch_group_t group);
18
19     long
20     dispatch_group_wait(dispatch_group_t group, dispatch_time_t timeout);
21
22     void
23     dispatch_group_notify(dispatch_group_t group, dispatch_queue_t queue,
24         void (^block)(void));
25
26     void
27     dispatch_group_notify_f(dispatch_group_t group, dispatch_queue_t queue,
28         void *context, void (*function)(void *));
29
30     void
31     dispatch_group_async(dispatch_group_t group, dispatch_queue_t queue,
32         void (^block)(void));
33
34     void
35     dispatch_group_async_f(dispatch_group_t group, dispatch_queue_t queue,
36         void *context, void (*function)(void *));
37

DESCRIPTION

39     A dispatch group is an association of one or more blocks submitted to
40     dispatch queues for asynchronous invocation.  Applications may use dis‐
41     patch groups to wait for the completion of blocks associated with the
42     group.
43
44     The dispatch_group_create() function returns a new and empty dispatch
45     group.
46
47     The dispatch_group_enter() and dispatch_group_leave() functions update
48     the number of blocks running within a group.
49
50     The dispatch_group_wait() function waits until all blocks associated with
51     the group have completed, or until the specified timeout has elapsed.  If
52     the group becomes empty within the specified amount of time, the function
53     will return zero indicating success. Otherwise, a non-zero return code
54     will be returned.  When DISPATCH_TIME_FOREVER is passed as the timeout,
55     calls to this function will wait an unlimited amount of time until the
56     group becomes empty and the return value is always zero.
57
58     The dispatch_group_notify() function provides asynchronous notification
59     of the completion of the blocks associated with the group by submitting
60     the block to the specified queue once all blocks associated with the
61     group have completed.  The system holds a reference to the dispatch group
62     while an asynchronous notification is pending, therefore it is valid to
63     release the group after setting a notification block.  The group will be
64     empty at the time the notification block is submitted to the target
65     queue. The group may either be released with dispatch_release() or reused
66     for additional operations.
67
68     The dispatch_group_async() convenience function behaves like so:
69
70     void
71     dispatch_group_async(dispatch_group_t group, dispatch_queue_t queue, dispatch_block_t block)
72     {
73             dispatch_retain(group);
74             dispatch_group_enter(group);
75             dispatch_async(queue, ^{
76                     block();
77                     dispatch_group_leave(group);
78                     dispatch_release(group);
79             });
80     }
81

RETURN VALUE

83     The dispatch_group_create() function returns NULL on failure and non-NULL
84     on success.
85
86     The dispatch_group_wait() function returns zero upon success and non-zero
87     after the timeout expires.  If the timeout is DISPATCH_TIME_FOREVER, then
88     dispatch_group_wait() waits forever and always returns zero.
89

MEMORY MODEL

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

FUNDAMENTALS

95     The dispatch_group_async() and dispatch_group_notify() functions are
96     wrappers around dispatch_group_async_f() and dispatch_group_notify_f()
97     respectively.
98

CAVEATS

100     In order to ensure deterministic behavior, it is recommended to call
101     dispatch_group_wait() only once all blocks have been submitted to the
102     group. If it is later determined that new blocks should be run, it is
103     recommended not to reuse an already-running group, but to create a new
104     group.
105
106     dispatch_group_wait() returns as soon as there are exactly zero enqueued
107     or running blocks associated with a group (more precisely, as soon as
108     every dispatch_group_enter() call has been balanced by a
109     dispatch_group_leave() call). If one thread waits for a group while
110     another thread submits new blocks to the group, then the count of associ‐
111     ated blocks might momentarily reach zero before all blocks have been sub‐
112     mitted. If this happens, dispatch_group_wait() will return too early:
113     some blocks associated with the group have finished, but some have not
114     yet been submitted or run.
115
116     However, as a special case, a block associated with a group may submit
117     new blocks associated with its own group. In this case, the behavior is
118     deterministic: a waiting thread will not wake up until the newly submit‐
119     ted blocks have also finished.
120
121     All of the foregoing also applies to dispath_group_notify() as well, with
122     "block to be submitted" substituted for "waiting thread".
123