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 277