[apple/libdispatch.git] / dispatch / group.h

/*
 * Copyright (c) 2008-2011 Apple Inc. All rights reserved.
 *
 * @APPLE_APACHE_LICENSE_HEADER_START@
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * @APPLE_APACHE_LICENSE_HEADER_END@
 */

#ifndef __DISPATCH_GROUP__
#define __DISPATCH_GROUP__

#ifndef __DISPATCH_INDIRECT__
#error "Please #include <dispatch/dispatch.h> instead of this file directly."
#include <dispatch/base.h> // for HeaderDoc
#endif

/*!
 * @typedef dispatch_group_t
 * @abstract
 * A group of blocks submitted to queues for asynchronous invocation.
 */
DISPATCH_DECL(dispatch_group);

__BEGIN_DECLS

/*!
 * @function dispatch_group_create
 *
 * @abstract
 * Creates new group with which blocks may be associated.
 *
 * @discussion
 * This function creates a new group with which blocks may be associated.
 * The dispatch group may be used to wait for the completion of the blocks it
 * references. The group object memory is freed with dispatch_release().
 *
 * @result
 * The newly created group, or NULL on failure.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
DISPATCH_NOTHROW
dispatch_group_t
dispatch_group_create(void);

/*!
 * @function dispatch_group_async
 *
 * @abstract
 * Submits a block to a dispatch queue and associates the block with the given
 * dispatch group.
 *
 * @discussion
 * Submits a block to a dispatch queue and associates the block with the given
 * dispatch group. The dispatch group may be used to wait for the completion
 * of the blocks it references.
 *
 * @param group
 * A dispatch group to associate with the submitted block.
 * The result of passing NULL in this parameter is undefined.
 *
 * @param queue
 * The dispatch queue to which the block will be submitted for asynchronous
 * invocation.
 *
 * @param block
 * The block to perform asynchronously.
 */
#ifdef __BLOCKS__
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
dispatch_group_async(dispatch_group_t group,
	dispatch_queue_t queue,
	dispatch_block_t block);
#endif /* __BLOCKS__ */

/*!
 * @function dispatch_group_async_f
 *
 * @abstract
 * Submits a function to a dispatch queue and associates the block with the
 * given dispatch group.
 *
 * @discussion
 * See dispatch_group_async() for details.
 *
 * @param group
 * A dispatch group to associate with the submitted function.
 * The result of passing NULL in this parameter is undefined.
 *
 * @param queue
 * The dispatch queue to which the function will be submitted for asynchronous
 * invocation.
 *
 * @param context
 * The application-defined context parameter to pass to the function.
 *
 * @param work
 * The application-defined function to invoke on the target queue. The first
 * parameter passed to this function is the context provided to
 * dispatch_group_async_f().
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4
DISPATCH_NOTHROW
void
dispatch_group_async_f(dispatch_group_t group,
	dispatch_queue_t queue,
	void *context,
	dispatch_function_t work);

/*!
 * @function dispatch_group_wait
 *
 * @abstract
 * Wait synchronously until all the blocks associated with a group have
 * completed or until the specified timeout has elapsed.
 *
 * @discussion
 * This function waits for the completion of the blocks associated with the
 * given dispatch group, and returns after all blocks have completed or when
 * the specified timeout has elapsed. When a timeout occurs, the group is
 * restored to its original state.
 *
 * This function will return immediately if there are no blocks associated
 * with the dispatch group (i.e. the group is empty).
 *
 * The result of calling this function from mulitple threads simultaneously
 * with the same dispatch group is undefined.
 *
 * After the successful return of this function, the dispatch group is empty.
 * It may either be released with dispatch_release() or re-used for additional
 * blocks. See dispatch_group_async() for more information.
 *
 * @param group
 * The dispatch group to wait on.
 * The result of passing NULL in this parameter is undefined.
 *
 * @param timeout
 * When to timeout (see dispatch_time). As a convenience, there are the
 * DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants.
 *
 * @result
 * Returns zero on success (all blocks associated with the group completed
 * within the specified timeout) or non-zero on error (i.e. timed out).
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
long
dispatch_group_wait(dispatch_group_t group, dispatch_time_t timeout);

/*!
 * @function dispatch_group_notify
 *
 * @abstract
 * Schedule a block to be submitted to a queue when all the blocks associated
 * with a group have completed.
 *
 * @discussion
 * This function schedules a notification block to be submitted to the specified
 * queue once all blocks associated with the dispatch group have completed.
 *
 * If no blocks are associated with the dispatch group (i.e. the group is empty)
 * then the notification block will be submitted immediately.
 *
 * The group will be empty at the time the notification block is submitted to
 * the target queue. The group may either be released with dispatch_release()
 * or reused for additional operations.
 * See dispatch_group_async() for more information.
 *
 * @param group
 * The dispatch group to observe.
 * The result of passing NULL in this parameter is undefined.
 *
 * @param queue
 * The queue to which the supplied block will be submitted when the group
 * completes.
 *
 * @param block
 * The block to submit when the group completes.
 */
#ifdef __BLOCKS__
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
dispatch_group_notify(dispatch_group_t group,
	dispatch_queue_t queue,
	dispatch_block_t block);
#endif /* __BLOCKS__ */

/*!
 * @function dispatch_group_notify_f
 *
 * @abstract
 * Schedule a function to be submitted to a queue when all the blocks
 * associated with a group have completed.
 *
 * @discussion
 * See dispatch_group_notify() for details.
 *
 * @param group
 * The dispatch group to observe.
 * The result of passing NULL in this parameter is undefined.
 *
 * @param context
 * The application-defined context parameter to pass to the function.
 *
 * @param work
 * The application-defined function to invoke on the target queue. The first
 * parameter passed to this function is the context provided to
 * dispatch_group_notify_f().
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4
DISPATCH_NOTHROW
void
dispatch_group_notify_f(dispatch_group_t group,
	dispatch_queue_t queue,
	void *context,
	dispatch_function_t work);

/*!
 * @function dispatch_group_enter
 *
 * @abstract
 * Manually indicate a block has entered the group
 *
 * @discussion
 * Calling this function indicates another block has joined the group through
 * a means other than dispatch_group_async(). Calls to this function must be
 * balanced with dispatch_group_leave().
 *
 * @param group
 * The dispatch group to update.
 * The result of passing NULL in this parameter is undefined.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
dispatch_group_enter(dispatch_group_t group);

/*!
 * @function dispatch_group_leave
 *
 * @abstract
 * Manually indicate a block in the group has completed
 *
 * @discussion
 * Calling this function indicates block has completed and left the dispatch
 * groupJ by a means other than dispatch_group_async().
 *
 * @param group
 * The dispatch group to update.
 * The result of passing NULL in this parameter is undefined.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
dispatch_group_leave(dispatch_group_t group);

__END_DECLS

#endif
Commit	Line	Data
0ab74447	1	/*
e85f4437	2	* Copyright (c) 2008-2011 Apple Inc. All rights reserved.
0ab74447 A	3	*
0ab74447 A	4	* @APPLE_APACHE_LICENSE_HEADER_START@
e85f4437	5	*
0ab74447 A	6	* Licensed under the Apache License, Version 2.0 (the "License");
	7	* you may not use this file except in compliance with the License.
	8	* You may obtain a copy of the License at
e85f4437	9	*
0ab74447	10	* http://www.apache.org/licenses/LICENSE-2.0
e85f4437	11	*
0ab74447 A	12	* Unless required by applicable law or agreed to in writing, software
	13	* distributed under the License is distributed on an "AS IS" BASIS,
	14	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	15	* See the License for the specific language governing permissions and
	16	* limitations under the License.
e85f4437	17	*
0ab74447 A	18	* @APPLE_APACHE_LICENSE_HEADER_END@
	19	*/
	20
	21	#ifndef __DISPATCH_GROUP__
	22	#define __DISPATCH_GROUP__
	23
	24	#ifndef __DISPATCH_INDIRECT__
	25	#error "Please #include <dispatch/dispatch.h> instead of this file directly."
	26	#include <dispatch/base.h> // for HeaderDoc
	27	#endif
	28
	29	/*!
	30	* @typedef dispatch_group_t
	31	* @abstract
	32	* A group of blocks submitted to queues for asynchronous invocation.
	33	*/
	34	DISPATCH_DECL(dispatch_group);
	35
	36	__BEGIN_DECLS
	37
	38	/*!
	39	* @function dispatch_group_create
	40	*
	41	* @abstract
	42	* Creates new group with which blocks may be associated.
e85f4437	43	*
0ab74447 A	44	* @discussion
	45	* This function creates a new group with which blocks may be associated.
	46	* The dispatch group may be used to wait for the completion of the blocks it
	47	* references. The group object memory is freed with dispatch_release().
	48	*
	49	* @result
	50	* The newly created group, or NULL on failure.
	51	*/
e85f4437	52	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
c093abd6 A	53	DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
c093abd6 A	54	DISPATCH_NOTHROW
0ab74447 A	55	dispatch_group_t
	56	dispatch_group_create(void);
	57
	58	/*!
	59	* @function dispatch_group_async
	60	*
	61	* @abstract
	62	* Submits a block to a dispatch queue and associates the block with the given
	63	* dispatch group.
	64	*
	65	* @discussion
	66	* Submits a block to a dispatch queue and associates the block with the given
	67	* dispatch group. The dispatch group may be used to wait for the completion
	68	* of the blocks it references.
	69	*
	70	* @param group
	71	* A dispatch group to associate with the submitted block.
	72	* The result of passing NULL in this parameter is undefined.
	73	*
	74	* @param queue
	75	* The dispatch queue to which the block will be submitted for asynchronous
	76	* invocation.
	77	*
	78	* @param block
	79	* The block to perform asynchronously.
	80	*/
	81	#ifdef __BLOCKS__
e85f4437 A	82	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	83	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447 A	84	void
	85	dispatch_group_async(dispatch_group_t group,
	86	dispatch_queue_t queue,
	87	dispatch_block_t block);
	88	#endif /* __BLOCKS__ */
	89
	90	/*!
	91	* @function dispatch_group_async_f
	92	*
	93	* @abstract
	94	* Submits a function to a dispatch queue and associates the block with the
	95	* given dispatch group.
	96	*
	97	* @discussion
	98	* See dispatch_group_async() for details.
	99	*
	100	* @param group
	101	* A dispatch group to associate with the submitted function.
	102	* The result of passing NULL in this parameter is undefined.
	103	*
	104	* @param queue
	105	* The dispatch queue to which the function will be submitted for asynchronous
	106	* invocation.
	107	*
	108	* @param context
	109	* The application-defined context parameter to pass to the function.
	110	*
	111	* @param work
	112	* The application-defined function to invoke on the target queue. The first
	113	* parameter passed to this function is the context provided to
	114	* dispatch_group_async_f().
	115	*/
e85f4437	116	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
c093abd6 A	117	DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4
c093abd6 A	118	DISPATCH_NOTHROW
0ab74447 A	119	void
	120	dispatch_group_async_f(dispatch_group_t group,
	121	dispatch_queue_t queue,
	122	void *context,
	123	dispatch_function_t work);
	124
	125	/*!
	126	* @function dispatch_group_wait
	127	*
	128	* @abstract
e85f4437 A	129	* Wait synchronously until all the blocks associated with a group have
e85f4437 A	130	* completed or until the specified timeout has elapsed.
0ab74447 A	131	*
0ab74447 A	132	* @discussion
e85f4437	133	* This function waits for the completion of the blocks associated with the
0ab74447 A	134	* given dispatch group, and returns after all blocks have completed or when
	135	* the specified timeout has elapsed. When a timeout occurs, the group is
	136	* restored to its original state.
	137	*
	138	* This function will return immediately if there are no blocks associated
	139	* with the dispatch group (i.e. the group is empty).
	140	*
	141	* The result of calling this function from mulitple threads simultaneously
	142	* with the same dispatch group is undefined.
	143	*
	144	* After the successful return of this function, the dispatch group is empty.
	145	* It may either be released with dispatch_release() or re-used for additional
	146	* blocks. See dispatch_group_async() for more information.
	147	*
	148	* @param group
	149	* The dispatch group to wait on.
	150	* The result of passing NULL in this parameter is undefined.
	151	*
	152	* @param timeout
	153	* When to timeout (see dispatch_time). As a convenience, there are the
	154	* DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants.
	155	*
	156	* @result
	157	* Returns zero on success (all blocks associated with the group completed
	158	* within the specified timeout) or non-zero on error (i.e. timed out).
	159	*/
e85f4437 A	160	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	161	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447 A	162	long
	163	dispatch_group_wait(dispatch_group_t group, dispatch_time_t timeout);
	164
	165	/*!
	166	* @function dispatch_group_notify
	167	*
	168	* @abstract
e85f4437 A	169	* Schedule a block to be submitted to a queue when all the blocks associated
e85f4437 A	170	* with a group have completed.
0ab74447 A	171	*
	172	* @discussion
	173	* This function schedules a notification block to be submitted to the specified
	174	* queue once all blocks associated with the dispatch group have completed.
	175	*
	176	* If no blocks are associated with the dispatch group (i.e. the group is empty)
	177	* then the notification block will be submitted immediately.
e85f4437	178	*
0ab74447 A	179	* The group will be empty at the time the notification block is submitted to
	180	* the target queue. The group may either be released with dispatch_release()
	181	* or reused for additional operations.
	182	* See dispatch_group_async() for more information.
	183	*
	184	* @param group
	185	* The dispatch group to observe.
	186	* The result of passing NULL in this parameter is undefined.
	187	*
	188	* @param queue
	189	* The queue to which the supplied block will be submitted when the group
	190	* completes.
	191	*
	192	* @param block
	193	* The block to submit when the group completes.
	194	*/
	195	#ifdef __BLOCKS__
e85f4437 A	196	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	197	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447 A	198	void
	199	dispatch_group_notify(dispatch_group_t group,
	200	dispatch_queue_t queue,
	201	dispatch_block_t block);
	202	#endif /* __BLOCKS__ */
	203
	204	/*!
	205	* @function dispatch_group_notify_f
	206	*
	207	* @abstract
e85f4437 A	208	* Schedule a function to be submitted to a queue when all the blocks
e85f4437 A	209	* associated with a group have completed.
0ab74447 A	210	*
	211	* @discussion
	212	* See dispatch_group_notify() for details.
	213	*
	214	* @param group
	215	* The dispatch group to observe.
	216	* The result of passing NULL in this parameter is undefined.
	217	*
	218	* @param context
	219	* The application-defined context parameter to pass to the function.
	220	*
	221	* @param work
	222	* The application-defined function to invoke on the target queue. The first
	223	* parameter passed to this function is the context provided to
	224	* dispatch_group_notify_f().
	225	*/
e85f4437 A	226	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
	227	DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4
	228	DISPATCH_NOTHROW
0ab74447 A	229	void
	230	dispatch_group_notify_f(dispatch_group_t group,
	231	dispatch_queue_t queue,
	232	void *context,
	233	dispatch_function_t work);
	234
	235	/*!
	236	* @function dispatch_group_enter
	237	*
	238	* @abstract
	239	* Manually indicate a block has entered the group
	240	*
	241	* @discussion
	242	* Calling this function indicates another block has joined the group through
	243	* a means other than dispatch_group_async(). Calls to this function must be
	244	* balanced with dispatch_group_leave().
	245	*
	246	* @param group
	247	* The dispatch group to update.
	248	* The result of passing NULL in this parameter is undefined.
	249	*/
e85f4437 A	250	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	251	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447 A	252	void
	253	dispatch_group_enter(dispatch_group_t group);
	254
	255	/*!
	256	* @function dispatch_group_leave
	257	*
	258	* @abstract
	259	* Manually indicate a block in the group has completed
	260	*
	261	* @discussion
	262	* Calling this function indicates block has completed and left the dispatch
	263	* groupJ by a means other than dispatch_group_async().
	264	*
	265	* @param group
	266	* The dispatch group to update.
	267	* The result of passing NULL in this parameter is undefined.
	268	*/
e85f4437 A	269	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	270	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447 A	271	void
	272	dispatch_group_leave(dispatch_group_t group);
	273
	274	__END_DECLS
	275
	276	#endif