blob 8d74ada2 (8412B) - Raw
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