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