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

.\" Copyright (c) 2008-2009 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
Commit	Line	Data
0ab74447 A	1	.\" Copyright (c) 2008-2009 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
e85f4437	87	.Fa queue
0ab74447 A	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.
c093abd6 A	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".
0ab74447	174	.Sh SEE ALSO
e85f4437	175	.Xr dispatch 3 ,
0ab74447	176	.Xr dispatch_async 3 ,
e85f4437	177	.Xr dispatch_object 3 ,
0ab74447	178	.Xr dispatch_queue_create 3 ,
e85f4437 A	179	.Xr dispatch_semaphore_create 3 ,
e85f4437 A	180	.Xr dispatch_time 3