dispatch/group.h - third_party/swift-corelibs-libdispatch - Git at Google

 /*
  * Copyright (c) 2008-2013 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

 DISPATCH_ASSUME_NONNULL_BEGIN

 /*!
  * @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.
  */
 API_AVAILABLE(macos(10.6), ios(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__
 API_AVAILABLE(macos(10.6), ios(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().
  */
 API_AVAILABLE(macos(10.6), ios(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 *_Nullable 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.
  *
  * 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 multiple 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).
  */
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 intptr_t
 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__
 API_AVAILABLE(macos(10.6), ios(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().
  */
 API_AVAILABLE(macos(10.6), ios(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 *_Nullable 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.
  */
 API_AVAILABLE(macos(10.6), ios(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
  * group 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.
  */
 API_AVAILABLE(macos(10.6), ios(4.0))
 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 void
 dispatch_group_leave(dispatch_group_t group);

 __END_DECLS

 DISPATCH_ASSUME_NONNULL_END

 #endif
	/*
	* Copyright (c) 2008-2013 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

	DISPATCH_ASSUME_NONNULL_BEGIN

	/*!
	* @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.
	*/
	API_AVAILABLE(macos(10.6), ios(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__
	API_AVAILABLE(macos(10.6), ios(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().
	*/
	API_AVAILABLE(macos(10.6), ios(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 *_Nullable 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.
	*
	* 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 multiple 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).
	*/
	API_AVAILABLE(macos(10.6), ios(4.0))
	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
	intptr_t
	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__
	API_AVAILABLE(macos(10.6), ios(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().
	*/
	API_AVAILABLE(macos(10.6), ios(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 *_Nullable 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.
	*/
	API_AVAILABLE(macos(10.6), ios(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
	* group 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.
	*/
	API_AVAILABLE(macos(10.6), ios(4.0))
	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
	void
	dispatch_group_leave(dispatch_group_t group);

	__END_DECLS

	DISPATCH_ASSUME_NONNULL_END

	#endif