libdispatch-703.30.5.tar.gz

[apple/libdispatch.git] / man / dispatch_group_create.3

diff --git a/man/dispatch_group_create.3 b/man/dispatch_group_create.3
index 5cca4ca8a772a409a9a0e5d1f3fa88ad7cf10b19..d82391e825f053571b73ac3429e897e942bb5354 100644 (file)
--- a/man/dispatch_group_create.3
+++ b/man/dispatch_group_create.3
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2008-2009 Apple Inc. All rights reserved.
+.\" Copyright (c) 2008-2012 Apple Inc. All rights reserved.
 .Dd May 1, 2009
 .Dt dispatch_group_create 3
 .Os Darwin
@@ -84,7 +84,7 @@ associated with the
 by submitting the
 .Fa block
 to the specified
-.Fa queue 
+.Fa queue
 once all blocks associated with the
 .Fa group
 have completed.
@@ -141,9 +141,40 @@ functions are wrappers around
 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_object 3 ,
+.Xr dispatch 3 ,
 .Xr dispatch_async 3 ,
-.Xr dispatch_time 3 ,
+.Xr dispatch_object 3 ,
 .Xr dispatch_queue_create 3 ,
-.Xr dispatch_semaphore_create 3
+.Xr dispatch_semaphore_create 3 ,
+.Xr dispatch_time 3