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