src/group.h

   1 /*
   2  * Copyright (c) 2008-2009 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_NA)
  53 DISPATCH_WARN_RESULT
  54 dispatch_group_t
  55 dispatch_group_create(void);
  56
  57 /*!
  58  * @function dispatch_group_async
  59  *
  60  * @abstract
  61  * Submits a block to a dispatch queue and associates the block with the given
  62  * dispatch group.
  63  *
  64  * @discussion
  65  * Submits a block to a dispatch queue and associates the block with the given
  66  * dispatch group. The dispatch group may be used to wait for the completion
  67  * of the blocks it references.
  68  *
  69  * @param group
  70  * A dispatch group to associate with the submitted block.
  71  * The result of passing NULL in this parameter is undefined.
  72  *
  73  * @param queue
  74  * The dispatch queue to which the block will be submitted for asynchronous
  75  * invocation.
  76  *
  77  * @param block
  78  * The block to perform asynchronously.
  79  */
  80 #ifdef __BLOCKS__
  81 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
  82 DISPATCH_NONNULL_ALL
  83 void
  84 dispatch_group_async(dispatch_group_t group,
  85         dispatch_queue_t queue,
  86         dispatch_block_t block);
  87 #endif /* __BLOCKS__ */
  88
  89 /*!
  90  * @function dispatch_group_async_f
  91  *
  92  * @abstract
  93  * Submits a function to a dispatch queue and associates the block with the
  94  * given dispatch group.
  95  *
  96  * @discussion
  97  * See dispatch_group_async() for details.
  98  *
  99  * @param group
 100  * A dispatch group to associate with the submitted function.
 101  * The result of passing NULL in this parameter is undefined.
 102  *
 103  * @param queue
 104  * The dispatch queue to which the function will be submitted for asynchronous
 105  * invocation.
 106  *
 107  * @param context
 108  * The application-defined context parameter to pass to the function.
 109  *
 110  * @param work
 111  * The application-defined function to invoke on the target queue. The first
 112  * parameter passed to this function is the context provided to
 113  * dispatch_group_async_f().
 114  */
 115 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
 116 DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4
 117 void
 118 dispatch_group_async_f(dispatch_group_t group,
 119         dispatch_queue_t queue,
 120         void *context,
 121         dispatch_function_t work);
 122
 123 /*!
 124  * @function dispatch_group_wait
 125  *
 126  * @abstract
 127  * Wait synchronously for the previously submitted blocks to complete;
 128  * returns if the blocks have not completed within the specified timeout.
 129  *
 130  * @discussion
 131  * This function waits  for the completion of the blocks associated with the
 132  * given dispatch group, and returns after all blocks have completed or when
 133  * the specified timeout has elapsed. When a timeout occurs, the group is
 134  * restored to its original state.
 135  *
 136  * This function will return immediately if there are no blocks associated
 137  * with the dispatch group (i.e. the group is empty).
 138  *
 139  * The result of calling this function from mulitple threads simultaneously
 140  * with the same dispatch group is undefined.
 141  *
 142  * After the successful return of this function, the dispatch group is empty.
 143  * It may either be released with dispatch_release() or re-used for additional
 144  * blocks. See dispatch_group_async() for more information.
 145  *
 146  * @param group
 147  * The dispatch group to wait on.
 148  * The result of passing NULL in this parameter is undefined.
 149  *
 150  * @param timeout
 151  * When to timeout (see dispatch_time). As a convenience, there are the
 152  * DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER constants.
 153  *
 154  * @result
 155  * Returns zero on success (all blocks associated with the group completed
 156  * within the specified timeout) or non-zero on error (i.e. timed out).
 157  */
 158 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
 159 DISPATCH_NONNULL_ALL
 160 long
 161 dispatch_group_wait(dispatch_group_t group, dispatch_time_t timeout);
 162
 163 /*!
 164  * @function dispatch_group_notify
 165  *
 166  * @abstract
 167  * Schedule a block to be submitted to a queue when a group of previously
 168  * submitted blocks have completed.
 169  *
 170  * @discussion
 171  * This function schedules a notification block to be submitted to the specified
 172  * queue once all blocks associated with the dispatch group have completed.
 173  *
 174  * If no blocks are associated with the dispatch group (i.e. the group is empty)
 175  * then the notification block will be submitted immediately.
 176  *
 177  * The group will be empty at the time the notification block is submitted to
 178  * the target queue. The group may either be released with dispatch_release()
 179  * or reused for additional operations.
 180  * See dispatch_group_async() for more information.
 181  *
 182  * @param group
 183  * The dispatch group to observe.
 184  * The result of passing NULL in this parameter is undefined.
 185  *
 186  * @param queue
 187  * The queue to which the supplied block will be submitted when the group
 188  * completes.
 189  *
 190  * @param block
 191  * The block to submit when the group completes.
 192  */
 193 #ifdef __BLOCKS__
 194 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
 195 DISPATCH_NONNULL_ALL
 196 void
 197 dispatch_group_notify(dispatch_group_t group,
 198         dispatch_queue_t queue,
 199         dispatch_block_t block);
 200 #endif /* __BLOCKS__ */
 201
 202 /*!
 203  * @function dispatch_group_notify_f
 204  *
 205  * @abstract
 206  * Schedule a function to be submitted to a queue when a group of previously
 207  * submitted functions have completed.
 208  *
 209  * @discussion
 210  * See dispatch_group_notify() for details.
 211  *
 212  * @param group
 213  * The dispatch group to observe.
 214  * The result of passing NULL in this parameter is undefined.
 215  *
 216  * @param context
 217  * The application-defined context parameter to pass to the function.
 218  *
 219  * @param work
 220  * The application-defined function to invoke on the target queue. The first
 221  * parameter passed to this function is the context provided to
 222  * dispatch_group_notify_f().
 223  */
 224 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
 225 DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4
 226 void
 227 dispatch_group_notify_f(dispatch_group_t group,
 228         dispatch_queue_t queue,
 229         void *context,
 230         dispatch_function_t work);
 231
 232 /*!
 233  * @function dispatch_group_enter
 234  *
 235  * @abstract
 236  * Manually indicate a block has entered the group
 237  *
 238  * @discussion
 239  * Calling this function indicates another block has joined the group through
 240  * a means other than dispatch_group_async(). Calls to this function must be
 241  * balanced with dispatch_group_leave().
 242  *
 243  * @param group
 244  * The dispatch group to update.
 245  * The result of passing NULL in this parameter is undefined.
 246  */
 247 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
 248 DISPATCH_NOTHROW DISPATCH_NONNULL_ALL
 249 void
 250 dispatch_group_enter(dispatch_group_t group);
 251
 252 /*!
 253  * @function dispatch_group_leave
 254  *
 255  * @abstract
 256  * Manually indicate a block in the group has completed
 257  *
 258  * @discussion
 259  * Calling this function indicates block has completed and left the dispatch
 260  * groupJ by a means other than dispatch_group_async().
 261  *
 262  * @param group
 263  * The dispatch group to update.
 264  * The result of passing NULL in this parameter is undefined.
 265  */
 266 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
 267 DISPATCH_NOTHROW DISPATCH_NONNULL_ALL
 268 void
 269 dispatch_group_leave(dispatch_group_t group);
 270
 271 __END_DECLS
 272
 273 #endif