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 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_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_width
 103  *
 104  * @abstract
 105  * Set the width of concurrency for a given queue. The width of a serial queue
 106  * is one.
 107  *
 108  * @discussion
 109  * This SPI is DEPRECATED and will be removed in a future release.
 110  * Uses of this SPI to make a queue concurrent by setting its width to LONG_MAX
 111  * should be replaced by passing DISPATCH_QUEUE_CONCURRENT to
 112  * dispatch_queue_create().
 113  * Uses of this SPI to limit queue concurrency are not recommended and should
 114  * be replaced by alternative mechanisms such as a dispatch semaphore created
 115  * with the desired concurrency width.
 116  *
 117  * @param queue
 118  * The queue to adjust. Passing the main queue or a global concurrent queue
 119  * will be ignored.
 120  *
 121  * @param width
 122  * The new maximum width of concurrency depending on available resources.
 123  * If zero is passed, then the value is promoted to one.
 124  * Negative values are magic values that map to automatic width values.
 125  * Unknown negative values default to DISPATCH_QUEUE_WIDTH_MAX_LOGICAL_CPUS.
 126  */
 127 #define DISPATCH_QUEUE_WIDTH_ACTIVE_CPUS                -1
 128 #define DISPATCH_QUEUE_WIDTH_MAX_PHYSICAL_CPUS  -2
 129 #define DISPATCH_QUEUE_WIDTH_MAX_LOGICAL_CPUS   -3
 130
 131 __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_6,__MAC_10_10,__IPHONE_4_0,__IPHONE_8_0, \
 132                 "Use dispatch_queue_create(name, DISPATCH_QUEUE_CONCURRENT) instead")
 133 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 134 void
 135 dispatch_queue_set_width(dispatch_queue_t dq, long width);
 136
 137 #ifdef __BLOCKS__
 138 /*!
 139  * @function dispatch_pthread_root_queue_create
 140  *
 141  * @abstract
 142  * Creates a new concurrent dispatch root queue with a pthread-based pool of
 143  * worker threads owned by the application.
 144  *
 145  * @discussion
 146  * Dispatch pthread root queues are similar to the global concurrent dispatch
 147  * queues in that they invoke blocks concurrently, however the blocks are not
 148  * executed on ordinary worker threads but use a dedicated pool of pthreads not
 149  * shared with the global queues or any other pthread root queues.
 150  *
 151  * NOTE: this is a special-purpose facility that should only be used in very
 152  * limited circumstances, in almost all cases the global concurrent queues
 153  * should be preferred. While this facility allows for more flexibility in
 154  * configuring worker threads for special needs it comes at the cost of
 155  * increased overall memory usage due to reduced thread sharing and higher
 156  * latency in worker thread bringup.
 157  *
 158  * Dispatch pthread root queues do not support suspension, application context
 159  * and change of width or of target queue. They can however be used as the
 160  * target queue for serial or concurrent queues obtained via
 161  * dispatch_queue_create() or dispatch_queue_create_with_target(), which
 162  * enables the blocks submitted to those queues to be processed on the root
 163  * queue's pthread pool.
 164  *
 165  * When a dispatch pthread root queue is no longer needed, it should be
 166  * released with dispatch_release(). Existing worker pthreads and pending blocks
 167  * submitted to the root queue will hold a reference to the queue so it will not
 168  * be deallocated until all blocks have finished and worker threads exited.
 169  *
 170  * @param label
 171  * A string label to attach to the queue.
 172  * This parameter is optional and may be NULL.
 173  *
 174  * @param flags
 175  * Pass flags value returned by dispatch_pthread_root_queue_flags_pool_size()
 176  * or 0 if unused.
 177  *
 178  * @param attr
 179  * Attributes passed to pthread_create(3) when creating worker pthreads. This
 180  * parameter is copied and can be destroyed after this call returns.
 181  * This parameter is optional and may be NULL.
 182  *
 183  * @param configure
 184  * Configuration block called on newly created worker pthreads before any blocks
 185  * for the root queue are executed. The block may configure the current thread
 186  * as needed.
 187  * This parameter is optional and may be NULL.
 188  *
 189  * @result
 190  * The newly created dispatch pthread root queue.
 191  */
 192 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 193 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 194 DISPATCH_NOTHROW
 195 dispatch_queue_t
 196 dispatch_pthread_root_queue_create(const char *_Nullable label,
 197         unsigned long flags, const pthread_attr_t *_Nullable attr,
 198         dispatch_block_t _Nullable configure);
 199
 200 /*!
 201  * @function dispatch_pthread_root_queue_flags_pool_size
 202  *
 203  * @abstract
 204  * Returns flags argument to pass to dispatch_pthread_root_queue_create() to
 205  * specify the maximum size of the pthread pool to use for a pthread root queue.
 206  *
 207  * @param pool_size
 208  * Maximum size of the pthread pool to use for the root queue. The number of
 209  * pthreads created for this root queue will never exceed this number but there
 210  * is no guarantee that the specified number will be reached.
 211  * Pass 0 to specify that a default pool size determined by the system should
 212  * be used.
 213  * NOTE: passing pool_size == 1 does NOT make the pthread root queue equivalent
 214  *       to a serial queue.
 215  *
 216  * @result
 217  * The flags argument to pass to dispatch_pthread_root_queue_create().
 218  */
 219 DISPATCH_INLINE DISPATCH_ALWAYS_INLINE
 220 unsigned long
 221 dispatch_pthread_root_queue_flags_pool_size(uint8_t pool_size)
 222 {
 223         #define _DISPATCH_PTHREAD_ROOT_QUEUE_FLAG_POOL_SIZE (0x80000000ul)
 224         return (_DISPATCH_PTHREAD_ROOT_QUEUE_FLAG_POOL_SIZE |
 225                         (unsigned long)pool_size);
 226 }
 227
 228 #endif /* __BLOCKS__ */
 229
 230 /*!
 231  * @function dispatch_pthread_root_queue_copy_current
 232  *
 233  * @abstract
 234  * Returns a reference to the pthread root queue object that has created the
 235  * currently executing thread, or NULL if the current thread is not associated
 236  * to a pthread root queue.
 237  *
 238  * @result
 239  * A new reference to a pthread root queue object or NULL.
 240  */
 241 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 242 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 243 DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 244 dispatch_queue_t _Nullable
 245 dispatch_pthread_root_queue_copy_current(void);
 246
 247 /*!
 248  * @constant DISPATCH_APPLY_CURRENT_ROOT_QUEUE
 249  * @discussion Constant to pass to the dispatch_apply() and dispatch_apply_f()
 250  * functions to indicate that the root queue for the current thread should be
 251  * used (i.e. one of the global concurrent queues or a queue created with
 252  * dispatch_pthread_root_queue_create()). If there is no such queue, the
 253  * default priority global concurrent queue will be used.
 254  */
 255 #define DISPATCH_APPLY_CURRENT_ROOT_QUEUE ((dispatch_queue_t _Nonnull)0)
 256
 257 /*!
 258  * @function dispatch_async_enforce_qos_class_f
 259  *
 260  * @abstract
 261  * Submits a function for asynchronous execution on a dispatch queue.
 262  *
 263  * @discussion
 264  * See dispatch_async() for details. The QOS will be enforced as if
 265  * this was called:
 266  * <code>
 267  *     dispatch_async(queue, dispatch_block_create(DISPATCH_BLOCK_ENFORCE_QOS_CLASS, ^{
 268  *         work(context);
 269  *     });
 270  * </code>
 271  *
 272  * @param queue
 273  * The target dispatch queue to which the function is submitted.
 274  * The system will hold a reference on the target queue until the function
 275  * has returned.
 276  * The result of passing NULL in this parameter is undefined.
 277  *
 278  * @param context
 279  * The application-defined context parameter to pass to the function.
 280  *
 281  * @param work
 282  * The application-defined function to invoke on the target queue. The first
 283  * parameter passed to this function is the context provided to
 284  * dispatch_async_f().
 285  * The result of passing NULL in this parameter is undefined.
 286  */
 287 __OSX_AVAILABLE_STARTING(__MAC_10_11,__IPHONE_9_0)
 288 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
 289 void
 290 dispatch_async_enforce_qos_class_f(dispatch_queue_t queue,
 291         void *_Nullable context, dispatch_function_t work);
 292
 293
 294 __END_DECLS
 295
 296 DISPATCH_ASSUME_NONNULL_END
 297
 298 #endif