290 lines
8.7 KiB
C
290 lines
8.7 KiB
C
/*
|
|
* 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
|
|
DISPATCH_ASSUME_ABI_SINGLE_BEGIN
|
|
|
|
/*!
|
|
* @typedef dispatch_group_t
|
|
* @abstract
|
|
* A group of blocks submitted to queues for asynchronous invocation.
|
|
*/
|
|
DISPATCH_DECL_SWIFT(dispatch_group, DispatchGroup);
|
|
|
|
__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_SWIFT_NAME(DispatchGroup.init())
|
|
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
|
|
DISPATCH_REFINED_FOR_SWIFT
|
|
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
|
|
DISPATCH_SWIFT_UNAVAILABLE("Use DispatchQueue.async(self:group:qos:flags:execute:)")
|
|
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
|
|
DISPATCH_REFINED_FOR_SWIFT
|
|
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
|
|
DISPATCH_REFINED_FOR_SWIFT
|
|
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
|
|
DISPATCH_SWIFT_UNAVAILABLE("Use DispatchGroup.notify(self:qos:flags:queue:execute:)")
|
|
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
|
|
DISPATCH_SWIFT_NAME(DispatchGroup.enter(self:))
|
|
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
|
|
DISPATCH_SWIFT_NAME(DispatchGroup.leave(self:))
|
|
void
|
|
dispatch_group_leave(dispatch_group_t group);
|
|
|
|
__END_DECLS
|
|
|
|
DISPATCH_ASSUME_ABI_SINGLE_END
|
|
DISPATCH_ASSUME_NONNULL_END
|
|
|
|
#endif
|