]> git.saurik.com Git - apple/libdispatch.git/blob - private/queue_private.h
libdispatch-913.30.4.tar.gz
[apple/libdispatch.git] / private / queue_private.h
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 /*
22 * IMPORTANT: This header file describes INTERNAL interfaces to libdispatch
23 * which are subject to change in future releases of Mac OS X. Any applications
24 * relying on these interfaces WILL break.
25 */
26
27 #ifndef __DISPATCH_QUEUE_PRIVATE__
28 #define __DISPATCH_QUEUE_PRIVATE__
29
30 #ifndef __DISPATCH_INDIRECT__
31 #error "Please #include <dispatch/private.h> instead of this file directly."
32 #include <dispatch/base.h> // for HeaderDoc
33 #endif
34
35 DISPATCH_ASSUME_NONNULL_BEGIN
36
37 __BEGIN_DECLS
38
39 /*!
40 * @enum dispatch_queue_flags_t
41 *
42 * @constant DISPATCH_QUEUE_OVERCOMMIT
43 * The queue will create a new thread for invoking blocks, regardless of how
44 * busy the computer is.
45 */
46 enum {
47 DISPATCH_QUEUE_OVERCOMMIT = 0x2ull,
48 };
49
50 #define DISPATCH_QUEUE_FLAGS_MASK (DISPATCH_QUEUE_OVERCOMMIT)
51
52 /*!
53 * @function dispatch_queue_attr_make_with_overcommit
54 *
55 * @discussion
56 * Returns a dispatch queue attribute value with the overcommit flag set to the
57 * specified value.
58 *
59 * This attribute only makes sense when the specified queue is targeted at
60 * a root queue. Passing this attribute to dispatch_queue_create_with_target()
61 * with a target queue that is not a root queue will result in an assertion and
62 * the process being terminated.
63 *
64 * It is recommended to not specify a target queue at all when using this
65 * attribute and to use dispatch_queue_attr_make_with_qos_class() to select the
66 * appropriate QoS class instead.
67 *
68 * Queues created with this attribute cannot change target after having been
69 * activated. See dispatch_set_target_queue() and dispatch_activate().
70 *
71 * @param attr
72 * A queue attribute value to be combined with the overcommit flag, or NULL.
73 *
74 * @param overcommit
75 * Boolean overcommit flag.
76 *
77 * @return
78 * Returns an attribute value which may be provided to dispatch_queue_create().
79 * This new value combines the attributes specified by the 'attr' parameter and
80 * the overcommit flag.
81 */
82 API_AVAILABLE(macos(10.10), ios(8.0))
83 DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW
84 dispatch_queue_attr_t
85 dispatch_queue_attr_make_with_overcommit(dispatch_queue_attr_t _Nullable attr,
86 bool overcommit);
87
88 /*!
89 * @typedef dispatch_queue_priority_t
90 *
91 * @constant DISPATCH_QUEUE_PRIORITY_NON_INTERACTIVE
92 * Items dispatched to the queue will run at non-interactive priority.
93 * This priority level is intended for user-initiated application activity that
94 * is long-running and CPU or IO intensive and that the user is actively waiting
95 * on, but that should not interfere with interactive use of the application.
96 *
97 * This global queue priority level is mapped to QOS_CLASS_UTILITY.
98 */
99 #define DISPATCH_QUEUE_PRIORITY_NON_INTERACTIVE INT8_MIN
100
101 /*!
102 * @function dispatch_queue_set_label_nocopy
103 *
104 * @abstract
105 * Set the label for a given queue, without copying the input string.
106 *
107 * @discussion
108 * The queue must have been initially created with a NULL label, else using
109 * this function to set the queue label is undefined.
110 *
111 * The caller of this function must make sure the label pointer remains valid
112 * while it is used as the queue label and while any callers to
113 * dispatch_queue_get_label() may have obtained it. Since the queue lifetime
114 * may extend past the last release, it is advised to call this function with
115 * a constant string or NULL before the queue is released, or to destroy the
116 * label from a finalizer for that queue.
117 *
118 * This function should be called before any work item could call
119 * dispatch_queue_get_label(DISPATCH_CURRENT_QUEUE_LABEL) or from the context of
120 * the queue itself.
121 *
122 * @param queue
123 * The queue to adjust. Attempts to set the label of the main queue or a global
124 * concurrent queue will be ignored.
125 *
126 * @param label
127 * The new label for the queue.
128 */
129 API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
130 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NOTHROW
131 void
132 dispatch_queue_set_label_nocopy(dispatch_queue_t queue, const char *label);
133
134 /*!
135 * @function dispatch_queue_set_width
136 *
137 * @abstract
138 * Set the width of concurrency for a given queue. The width of a serial queue
139 * is one.
140 *
141 * @discussion
142 * This SPI is DEPRECATED and will be removed in a future release.
143 * Uses of this SPI to make a queue concurrent by setting its width to LONG_MAX
144 * should be replaced by passing DISPATCH_QUEUE_CONCURRENT to
145 * dispatch_queue_create().
146 * Uses of this SPI to limit queue concurrency are not recommended and should
147 * be replaced by alternative mechanisms such as a dispatch semaphore created
148 * with the desired concurrency width.
149 *
150 * @param queue
151 * The queue to adjust. Attempts to set the width of the main queue or a global
152 * concurrent queue will be ignored.
153 *
154 * @param width
155 * The new maximum width of concurrency depending on available resources.
156 * If zero is passed, then the value is promoted to one.
157 * Negative values are magic values that map to automatic width values.
158 * Unknown negative values default to DISPATCH_QUEUE_WIDTH_MAX_LOGICAL_CPUS.
159 */
160 #define DISPATCH_QUEUE_WIDTH_ACTIVE_CPUS -1
161 #define DISPATCH_QUEUE_WIDTH_MAX_PHYSICAL_CPUS -2
162 #define DISPATCH_QUEUE_WIDTH_MAX_LOGICAL_CPUS -3
163
164 API_DEPRECATED("Use dispatch_queue_create(name, DISPATCH_QUEUE_CONCURRENT)",
165 macos(10.6,10.10), ios(4.0,8.0))
166 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
167 void
168 dispatch_queue_set_width(dispatch_queue_t dq, long width);
169
170 #ifdef __BLOCKS__
171 /*!
172 * @function dispatch_pthread_root_queue_create
173 *
174 * @abstract
175 * Creates a new concurrent dispatch root queue with a pthread-based pool of
176 * worker threads owned by the application.
177 *
178 * @discussion
179 * Dispatch pthread root queues are similar to the global concurrent dispatch
180 * queues in that they invoke blocks concurrently, however the blocks are not
181 * executed on ordinary worker threads but use a dedicated pool of pthreads not
182 * shared with the global queues or any other pthread root queues.
183 *
184 * NOTE: this is a special-purpose facility that should only be used in very
185 * limited circumstances, in almost all cases the global concurrent queues
186 * should be preferred. While this facility allows for more flexibility in
187 * configuring worker threads for special needs it comes at the cost of
188 * increased overall memory usage due to reduced thread sharing and higher
189 * latency in worker thread bringup.
190 *
191 * Dispatch pthread root queues do not support suspension, application context
192 * and change of width or of target queue. They can however be used as the
193 * target queue for serial or concurrent queues obtained via
194 * dispatch_queue_create() or dispatch_queue_create_with_target(), which
195 * enables the blocks submitted to those queues to be processed on the root
196 * queue's pthread pool.
197 *
198 * When a dispatch pthread root queue is no longer needed, it should be
199 * released with dispatch_release(). Existing worker pthreads and pending blocks
200 * submitted to the root queue will hold a reference to the queue so it will not
201 * be deallocated until all blocks have finished and worker threads exited.
202 *
203 * @param label
204 * A string label to attach to the queue.
205 * This parameter is optional and may be NULL.
206 *
207 * @param flags
208 * Pass flags value returned by dispatch_pthread_root_queue_flags_pool_size()
209 * or 0 if unused.
210 *
211 * @param attr
212 * Attributes passed to pthread_create(3) when creating worker pthreads. This
213 * parameter is copied and can be destroyed after this call returns.
214 * This parameter is optional and may be NULL.
215 *
216 * @param configure
217 * Configuration block called on newly created worker pthreads before any blocks
218 * for the root queue are executed. The block may configure the current thread
219 * as needed.
220 * This parameter is optional and may be NULL.
221 *
222 * @result
223 * The newly created dispatch pthread root queue.
224 */
225 API_AVAILABLE(macos(10.9), ios(6.0))
226 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
227 DISPATCH_NOTHROW
228 dispatch_queue_t
229 dispatch_pthread_root_queue_create(const char *_Nullable label,
230 unsigned long flags, const pthread_attr_t *_Nullable attr,
231 dispatch_block_t _Nullable configure);
232
233 /*!
234 * @function dispatch_pthread_root_queue_flags_pool_size
235 *
236 * @abstract
237 * Returns flags argument to pass to dispatch_pthread_root_queue_create() to
238 * specify the maximum size of the pthread pool to use for a pthread root queue.
239 *
240 * @param pool_size
241 * Maximum size of the pthread pool to use for the root queue. The number of
242 * pthreads created for this root queue will never exceed this number but there
243 * is no guarantee that the specified number will be reached.
244 * Pass 0 to specify that a default pool size determined by the system should
245 * be used.
246 * NOTE: passing pool_size == 1 does NOT make the pthread root queue equivalent
247 * to a serial queue.
248 *
249 * @result
250 * The flags argument to pass to dispatch_pthread_root_queue_create().
251 */
252 DISPATCH_INLINE DISPATCH_ALWAYS_INLINE
253 unsigned long
254 dispatch_pthread_root_queue_flags_pool_size(uint8_t pool_size)
255 {
256 #define _DISPATCH_PTHREAD_ROOT_QUEUE_FLAG_POOL_SIZE (0x80000000ul)
257 return (_DISPATCH_PTHREAD_ROOT_QUEUE_FLAG_POOL_SIZE |
258 (unsigned long)pool_size);
259 }
260
261 #endif /* __BLOCKS__ */
262
263 /*!
264 * @function dispatch_pthread_root_queue_copy_current
265 *
266 * @abstract
267 * Returns a reference to the pthread root queue object that has created the
268 * currently executing thread, or NULL if the current thread is not associated
269 * to a pthread root queue.
270 *
271 * @result
272 * A new reference to a pthread root queue object or NULL.
273 */
274 API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
275 DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW
276 dispatch_queue_t _Nullable
277 dispatch_pthread_root_queue_copy_current(void);
278
279 /*!
280 * @constant DISPATCH_APPLY_CURRENT_ROOT_QUEUE
281 *
282 * @discussion
283 * This constant is deprecated, please use DISPATCH_APPLY_AUTO.
284 *
285 * DISPATCH_APPLY_AUTO also selects the current pthread root queue if
286 * applicable.
287 */
288 #define DISPATCH_APPLY_CURRENT_ROOT_QUEUE ((dispatch_queue_t _Nonnull)0)
289
290 /*!
291 * @function dispatch_async_enforce_qos_class_f
292 *
293 * @abstract
294 * Submits a function for asynchronous execution on a dispatch queue.
295 *
296 * @discussion
297 * See dispatch_async() for details. The QOS will be enforced as if
298 * this was called:
299 * <code>
300 * dispatch_async(queue, dispatch_block_create(DISPATCH_BLOCK_ENFORCE_QOS_CLASS, ^{
301 * work(context);
302 * });
303 * </code>
304 *
305 * @param queue
306 * The target dispatch queue to which the function is submitted.
307 * The system will hold a reference on the target queue until the function
308 * has returned.
309 * The result of passing NULL in this parameter is undefined.
310 *
311 * @param context
312 * The application-defined context parameter to pass to the function.
313 *
314 * @param work
315 * The application-defined function to invoke on the target queue. The first
316 * parameter passed to this function is the context provided to
317 * dispatch_async_f().
318 * The result of passing NULL in this parameter is undefined.
319 */
320 API_AVAILABLE(macos(10.11), ios(9.0))
321 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
322 void
323 dispatch_async_enforce_qos_class_f(dispatch_queue_t queue,
324 void *_Nullable context, dispatch_function_t work);
325
326
327 #ifdef __ANDROID__
328 /*!
329 * @function _dispatch_install_thread_detach_callback
330 *
331 * @param callback
332 * Function to be called before each worker thread exits to detach JVM.
333 *
334 * Hook to be able to detach threads from the Java JVM before they exit.
335 * If JNI has been used on a thread on Android it needs to have been
336 * "detached" before the thread exits or the application will crash.
337 */
338 DISPATCH_EXPORT
339 void _dispatch_install_thread_detach_callback(dispatch_function_t cb);
340 #endif
341
342 __END_DECLS
343
344 DISPATCH_ASSUME_NONNULL_END
345
346 #endif