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 46A dispatch group is an association of one or more blocks submitted to dispatch 47queues for asynchronous invocation. 48Applications may use dispatch groups to 49wait for the completion of blocks associated with the group. 50.Pp 51The 52.Fn dispatch_group_create 53function returns a new and empty dispatch group. 54.Pp 55The 56.Fn dispatch_group_enter 57and 58.Fn dispatch_group_leave 59functions update the number of blocks running within a group. 60.Pp 61The 62.Fn dispatch_group_wait 63function waits until all blocks associated with the 64.Fa group 65have completed, or until the specified 66.Fa timeout 67has elapsed. 68If the 69.Fa group 70becomes empty within the specified amount of time, the function will return zero 71indicating success. Otherwise, a non-zero return code will be returned. 72When 73.Va DISPATCH_TIME_FOREVER 74is passed as the 75.Fa timeout , 76calls to this function will wait an unlimited amount of time until the group 77becomes empty and the return value is always zero. 78.Pp 79The 80.Fn dispatch_group_notify 81function provides asynchronous notification of the completion of the blocks 82associated with the 83.Fa group 84by submitting the 85.Fa block 86to the specified 87.Fa queue 88once all blocks associated with the 89.Fa group 90have completed. 91The system holds a reference to the dispatch group while an asynchronous 92notification is pending, therefore it is valid to release the 93.Fa group 94after setting a notification block. 95The group will be empty at the time the notification block is submitted to the 96target queue. The group may either be released with 97.Fn dispatch_release 98or reused for additional operations. 99.Pp 100The 101.Fn dispatch_group_async 102convenience function behaves like so: 103.Bd -literal 104void 105dispatch_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 117The 118.Fn dispatch_group_create 119function returns NULL on failure and non-NULL on success. 120.Pp 121The 122.Fn dispatch_group_wait 123function returns zero upon success and non-zero after the timeout expires. 124If the timeout is 125.Va DISPATCH_TIME_FOREVER , 126then 127.Fn dispatch_group_wait 128waits forever and always returns zero. 129.Sh MEMORY MODEL 130Dispatch groups are retained and released via calls to 131.Fn dispatch_retain 132and 133.Fn dispatch_release . 134.Sh FUNDAMENTALS 135The 136.Fn dispatch_group_async 137and 138.Fn dispatch_group_notify 139functions are wrappers around 140.Fn dispatch_group_async_f 141and 142.Fn dispatch_group_notify_f 143respectively. 144.Sh CAVEATS 145In order to ensure deterministic behavior, it is recommended to call 146.Fn dispatch_group_wait 147only once all blocks have been submitted to the group. If it is later 148determined that new blocks should be run, it is recommended not to reuse an 149already-running group, but to create a new group. 150.Pp 151.Fn dispatch_group_wait 152returns as soon as there are exactly zero 153.Em enqueued or running 154blocks associated with a group (more precisely, as soon as every 155.Fn dispatch_group_enter 156call has been balanced by a 157.Fn dispatch_group_leave 158call). If one thread waits for a group while another thread submits 159new blocks to the group, then the count of associated blocks might 160momentarily reach zero before all blocks have been submitted. If this happens, 161.Fn dispatch_group_wait 162will return too early: some blocks associated with the group have finished, 163but some have not yet been submitted or run. 164.Pp 165However, as a special case, a block associated with a group may submit new 166blocks associated with its own group. In this case, the behavior is 167deterministic: a waiting thread will 168.Em not 169wake up until the newly submitted blocks have also finished. 170.Pp 171All of the foregoing also applies to 172.Fn dispath_group_notify 173as 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 181