/* * Copyright (c) 2008-2009 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_NA) DISPATCH_WARN_RESULT 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_NA) DISPATCH_NONNULL_ALL 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_NA) DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4 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 for the previously submitted blocks to complete; * returns if the blocks have not completed within the specified timeout. * * @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_NA) DISPATCH_NONNULL_ALL 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 a group of previously * submitted blocks 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_NA) DISPATCH_NONNULL_ALL 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 a group of previously * submitted functions 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_NA) DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4 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_NA) DISPATCH_NOTHROW DISPATCH_NONNULL_ALL 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_NA) DISPATCH_NOTHROW DISPATCH_NONNULL_ALL void dispatch_group_leave(dispatch_group_t group); __END_DECLS #endif