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