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
 29DISPATCH_ASSUME_NONNULL_BEGIN
 30DISPATCH_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 */
 37DISPATCH_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 */
 55API_AVAILABLE(macos(10.6), ios(4.0))
 56DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 57DISPATCH_NOTHROW
 58DISPATCH_SWIFT_NAME(DispatchGroup.init())
 59dispatch_group_t
 60dispatch_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__
 86API_AVAILABLE(macos(10.6), ios(4.0))
 87DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 88DISPATCH_REFINED_FOR_SWIFT
 89void
 90dispatch_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 */
121API_AVAILABLE(macos(10.6), ios(4.0))
122DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4
123DISPATCH_NOTHROW
124DISPATCH_SWIFT_UNAVAILABLE("Use DispatchQueue.async(self:group:qos:flags:execute:)")
125void
126dispatch_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 */
165API_AVAILABLE(macos(10.6), ios(4.0))
166DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
167DISPATCH_REFINED_FOR_SWIFT
168intptr_t
169dispatch_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__
202API_AVAILABLE(macos(10.6), ios(4.0))
203DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
204DISPATCH_REFINED_FOR_SWIFT
205void
206dispatch_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 */
233API_AVAILABLE(macos(10.6), ios(4.0))
234DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL2 DISPATCH_NONNULL4
235DISPATCH_NOTHROW
236DISPATCH_SWIFT_UNAVAILABLE("Use DispatchGroup.notify(self:qos:flags:queue:execute:)")
237void
238dispatch_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 */
258API_AVAILABLE(macos(10.6), ios(4.0))
259DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
260DISPATCH_SWIFT_NAME(DispatchGroup.enter(self:))
261void
262dispatch_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 */
278API_AVAILABLE(macos(10.6), ios(4.0))
279DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
280DISPATCH_SWIFT_NAME(DispatchGroup.leave(self:))
281void
282dispatch_group_leave(dispatch_group_t group);
283
284__END_DECLS
285
286DISPATCH_ASSUME_ABI_SINGLE_END
287DISPATCH_ASSUME_NONNULL_END
288
289#endif