dispatch/group.h

   1 /*
   2  * Copyright (c) 2008-2013 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_APACHE_LICENSE_HEADER_START@
   5  *
   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
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  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.
  17  *
  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.
  43  *
  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  */
  52 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  53 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
  54 DISPATCH_NOTHROW
  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__
  82 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  83 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  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  */
 116 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 117 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4
 118 DISPATCH_NOTHROW
 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
 129  * Wait synchronously until all the blocks associated with a group have
 130  * completed or until the specified timeout has elapsed.
 131  *
 132  * @discussion
 133  * This function waits for the completion of the blocks associated with the
 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 multiple 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  */
 160 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 161 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 162 long
 163 dispatch_group_wait(dispatch_group_t group, dispatch_time_t timeout);
 164
 165 /*!
 166  * @function dispatch_group_notify
 167  *
 168  * @abstract
 169  * Schedule a block to be submitted to a queue when all the blocks associated
 170  * with a group have completed.
 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.
 178  *
 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__
 196 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 197 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 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
 208  * Schedule a function to be submitted to a queue when all the blocks
 209  * associated with a group have completed.
 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  */
 226 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 227 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4
 228 DISPATCH_NOTHROW
 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  */
 250 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 251 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 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  */
 269 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 270 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 271 void
 272 dispatch_group_leave(dispatch_group_t group);
 273
 274 __END_DECLS
 275
 276 #endif