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