man/dispatch_group_create.3

   1 .\" Copyright (c) 2008-2012 Apple Inc. All rights reserved.
   2 .Dd May 1, 2009
   3 .Dt dispatch_group_create 3
   4 .Os Darwin
   5 .Sh NAME
   6 .Nm dispatch_group_create ,
   7 .Nm dispatch_group_async ,
   8 .Nm dispatch_group_wait ,
   9 .Nm dispatch_group_notify
  10 .Nd group blocks submitted to queues
  11 .Sh SYNOPSIS
  12 .Fd #include <dispatch/dispatch.h>
  13 .Ft dispatch_group_t
  14 .Fo dispatch_group_create
  15 .Fa void
  16 .Fc
  17 .Ft void
  18 .Fo dispatch_group_enter
  19 .Fa "dispatch_group_t group"
  20 .Fc
  21 .Ft void
  22 .Fo dispatch_group_leave
  23 .Fa "dispatch_group_t group"
  24 .Fc
  25 .Ft long
  26 .Fo dispatch_group_wait
  27 .Fa "dispatch_group_t group" "dispatch_time_t timeout"
  28 .Fc
  29 .Ft void
  30 .Fo dispatch_group_notify
  31 .Fa "dispatch_group_t group" "dispatch_queue_t queue" "void (^block)(void)"
  32 .Fc
  33 .Ft void
  34 .Fo dispatch_group_notify_f
  35 .Fa "dispatch_group_t group" "dispatch_queue_t queue" "void *context" "void (*function)(void *)"
  36 .Fc
  37 .Ft void
  38 .Fo dispatch_group_async
  39 .Fa "dispatch_group_t group" "dispatch_queue_t queue" "void (^block)(void)"
  40 .Fc
  41 .Ft void
  42 .Fo dispatch_group_async_f
  43 .Fa "dispatch_group_t group" "dispatch_queue_t queue" "void *context" "void (*function)(void *)"
  44 .Fc
  45 .Sh DESCRIPTION
  46 A dispatch group is an association of one or more blocks submitted to dispatch
  47 queues for asynchronous invocation.
  48 Applications may use dispatch groups to
  49 wait for the completion of blocks associated with the group.
  50 .Pp
  51 The
  52 .Fn dispatch_group_create
  53 function returns a new and empty dispatch group.
  54 .Pp
  55 The
  56 .Fn dispatch_group_enter
  57 and
  58 .Fn dispatch_group_leave
  59 functions update the number of blocks running within a group.
  60 .Pp
  61 The
  62 .Fn dispatch_group_wait
  63 function waits until all blocks associated with the
  64 .Fa group
  65 have completed, or until the specified
  66 .Fa timeout
  67 has elapsed.
  68 If the
  69 .Fa group
  70 becomes empty within the specified amount of time, the function will return zero
  71 indicating success. Otherwise, a non-zero return code will be returned.
  72 When
  73 .Va DISPATCH_TIME_FOREVER
  74 is passed as the
  75 .Fa timeout ,
  76 calls to this function will wait an unlimited amount of time until the group
  77 becomes empty and the return value is always zero.
  78 .Pp
  79 The
  80 .Fn dispatch_group_notify
  81 function provides asynchronous notification of the completion of the blocks
  82 associated with the
  83 .Fa group
  84 by submitting the
  85 .Fa block
  86 to the specified
  87 .Fa queue
  88 once all blocks associated with the
  89 .Fa group
  90 have completed.
  91 The system holds a reference to the dispatch group while an asynchronous
  92 notification is pending, therefore it is valid to release the
  93 .Fa group
  94 after setting a notification block.
  95 The group will be empty at the time the notification block is submitted to the
  96 target queue. The group may either be released with
  97 .Fn dispatch_release
  98 or reused for additional operations.
  99 .Pp
 100 The
 101 .Fn dispatch_group_async
 102 convenience function behaves like so:
 103 .Bd -literal
 104 void
 105 dispatch_group_async(dispatch_group_t group, dispatch_queue_t queue, dispatch_block_t block)
 106 {
 107         dispatch_retain(group);
 108         dispatch_group_enter(group);
 109         dispatch_async(queue, ^{
 110                 block();
 111                 dispatch_group_leave(group);
 112                 dispatch_release(group);
 113         });
 114 }
 115 .Ed
 116 .Sh RETURN VALUE
 117 The
 118 .Fn dispatch_group_create
 119 function returns NULL on failure and non-NULL on success.
 120 .Pp
 121 The
 122 .Fn dispatch_group_wait
 123 function returns zero upon success and non-zero after the timeout expires.
 124 If the timeout is
 125 .Va DISPATCH_TIME_FOREVER ,
 126 then
 127 .Fn dispatch_group_wait
 128 waits forever and always returns zero.
 129 .Sh MEMORY MODEL
 130 Dispatch groups are retained and released via calls to
 131 .Fn dispatch_retain
 132 and
 133 .Fn dispatch_release .
 134 .Sh FUNDAMENTALS
 135 The
 136 .Fn dispatch_group_async
 137 and
 138 .Fn dispatch_group_notify
 139 functions are wrappers around
 140 .Fn dispatch_group_async_f
 141 and
 142 .Fn dispatch_group_notify_f
 143 respectively.
 144 .Sh CAVEATS
 145 In order to ensure deterministic behavior, it is recommended to call
 146 .Fn dispatch_group_wait
 147 only once all blocks have been submitted to the group. If it is later
 148 determined that new blocks should be run, it is recommended not to reuse an
 149 already-running group, but to create a new group.
 150 .Pp
 151 .Fn dispatch_group_wait
 152 returns as soon as there are exactly zero
 153 .Em enqueued or running
 154 blocks associated with a group (more precisely, as soon as every
 155 .Fn dispatch_group_enter
 156 call has been balanced by a
 157 .Fn dispatch_group_leave
 158 call). If one thread waits for a group while another thread submits
 159 new blocks to the group, then the count of associated blocks might
 160 momentarily reach zero before all blocks have been submitted. If this happens,
 161 .Fn dispatch_group_wait
 162 will return too early: some blocks associated with the group have finished,
 163 but some have not yet been submitted or run.
 164 .Pp
 165 However, as a special case, a block associated with a group may submit new
 166 blocks associated with its own group. In this case, the behavior is
 167 deterministic: a waiting thread will
 168 .Em not
 169 wake up until the newly submitted blocks have also finished.
 170 .Pp
 171 All of the foregoing also applies to
 172 .Fn dispath_group_notify
 173 as well, with "block to be submitted" substituted for "waiting thread".
 174 .Sh SEE ALSO
 175 .Xr dispatch 3 ,
 176 .Xr dispatch_async 3 ,
 177 .Xr dispatch_object 3 ,
 178 .Xr dispatch_queue_create 3 ,
 179 .Xr dispatch_semaphore_create 3 ,
 180 .Xr dispatch_time 3