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 __BEGIN_DECLS
  36
  37 /*!
  38  * @enum dispatch_queue_flags_t
  39  *
  40  * @constant DISPATCH_QUEUE_OVERCOMMIT
  41  * The queue will create a new thread for invoking blocks, regardless of how
  42  * busy the computer is.
  43  */
  44 enum {
  45         DISPATCH_QUEUE_OVERCOMMIT = 0x2ull,
  46 };
  47
  48 #define DISPATCH_QUEUE_FLAGS_MASK (DISPATCH_QUEUE_OVERCOMMIT)
  49
  50 /*!
  51  * @function dispatch_queue_attr_make_with_overcommit
  52  *
  53  * @discussion
  54  * Returns a dispatch queue attribute value with the overcommit flag set to the
  55  * specified value.
  56  *
  57  * @param attr
  58  * A queue attribute value to be combined with the overcommit flag, or NULL.
  59  *
  60  * @param overcommit
  61  * Boolean overcommit flag.
  62  *
  63  * @return
  64  * Returns an attribute value which may be provided to dispatch_queue_create().
  65  * This new value combines the attributes specified by the 'attr' parameter and
  66  * the overcommit flag.
  67  */
  68 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
  69 DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_PURE DISPATCH_NOTHROW
  70 dispatch_queue_attr_t
  71 dispatch_queue_attr_make_with_overcommit(dispatch_queue_attr_t attr,
  72                 bool overcommit);
  73
  74 /*!
  75  * @typedef dispatch_queue_priority_t
  76  *
  77  * @constant DISPATCH_QUEUE_PRIORITY_NON_INTERACTIVE
  78  * Items dispatched to the queue will run at non-interactive priority.
  79  * This priority level is intended for user-initiated application activity that
  80  * is long-running and CPU or IO intensive and that the user is actively waiting
  81  * on, but that should not interfere with interactive use of the application.
  82  */
  83 #define DISPATCH_QUEUE_PRIORITY_NON_INTERACTIVE INT8_MIN
  84
  85 /*!
  86  * @function dispatch_queue_set_width
  87  *
  88  * @abstract
  89  * Set the width of concurrency for a given queue. The width of a serial queue
  90  * is one.
  91  *
  92  * @discussion
  93  * This SPI is DEPRECATED and will be removed in a future release.
  94  * Uses of this SPI to make a queue concurrent by setting its width to LONG_MAX
  95  * should be replaced by passing DISPATCH_QUEUE_CONCURRENT to
  96  * dispatch_queue_create().
  97  * Uses of this SPI to limit queue concurrency are not recommended and should
  98  * be replaced by alternative mechanisms such as a dispatch semaphore created
  99  * with the desired concurrency width.
 100  *
 101  * @param queue
 102  * The queue to adjust. Passing the main queue or a global concurrent queue
 103  * will be ignored.
 104  *
 105  * @param width
 106  * The new maximum width of concurrency depending on available resources.
 107  * If zero is passed, then the value is promoted to one.
 108  * Negative values are magic values that map to automatic width values.
 109  * Unknown negative values default to DISPATCH_QUEUE_WIDTH_MAX_LOGICAL_CPUS.
 110  */
 111 #define DISPATCH_QUEUE_WIDTH_ACTIVE_CPUS                -1
 112 #define DISPATCH_QUEUE_WIDTH_MAX_PHYSICAL_CPUS  -2
 113 #define DISPATCH_QUEUE_WIDTH_MAX_LOGICAL_CPUS   -3
 114
 115 __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_6,__MAC_10_10,__IPHONE_4_0,__IPHONE_8_0, \
 116                 "Use dispatch_queue_create(name, DISPATCH_QUEUE_CONCURRENT) instead")
 117 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 118 void
 119 dispatch_queue_set_width(dispatch_queue_t dq, long width);
 120
 121 /*!
 122  * @function dispatch_queue_create_with_target
 123  *
 124  * @abstract
 125  * Creates a new dispatch queue with a specified target queue.
 126  *
 127  * @discussion
 128  * Dispatch queues created with the DISPATCH_QUEUE_SERIAL or a NULL attribute
 129  * invoke blocks serially in FIFO order.
 130  *
 131  * Dispatch queues created with the DISPATCH_QUEUE_CONCURRENT attribute may
 132  * invoke blocks concurrently (similarly to the global concurrent queues, but
 133  * potentially with more overhead), and support barrier blocks submitted with
 134  * the dispatch barrier API, which e.g. enables the implementation of efficient
 135  * reader-writer schemes.
 136  *
 137  * When a dispatch queue is no longer needed, it should be released with
 138  * dispatch_release(). Note that any pending blocks submitted to a queue will
 139  * hold a reference to that queue. Therefore a queue will not be deallocated
 140  * until all pending blocks have finished.
 141  *
 142  * @param label
 143  * A string label to attach to the queue.
 144  * This parameter is optional and may be NULL.
 145  *
 146  * @param attr
 147  * DISPATCH_QUEUE_SERIAL, DISPATCH_QUEUE_CONCURRENT, or the result of a call to
 148  * the function dispatch_queue_attr_make_with_qos_class().
 149  *
 150  * @param target
 151  * The target queue for the newly created queue. The target queue is retained.
 152  * If this parameter is DISPATCH_TARGET_QUEUE_DEFAULT, sets the queue's target
 153  * queue to the default target queue for the given queue type.
 154  *
 155  * @result
 156  * The newly created dispatch queue.
 157  */
 158 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 159 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 160 DISPATCH_NOTHROW
 161 dispatch_queue_t
 162 dispatch_queue_create_with_target(const char *label,
 163         dispatch_queue_attr_t attr, dispatch_queue_t target);
 164
 165 #ifdef __BLOCKS__
 166 /*!
 167  * @function dispatch_pthread_root_queue_create
 168  *
 169  * @abstract
 170  * Creates a new concurrent dispatch root queue with a pthread-based pool of
 171  * worker threads owned by the application.
 172  *
 173  * @discussion
 174  * Dispatch pthread root queues are similar to the global concurrent dispatch
 175  * queues in that they invoke blocks concurrently, however the blocks are not
 176  * executed on ordinary worker threads but use a dedicated pool of pthreads not
 177  * shared with the global queues or any other pthread root queues.
 178  *
 179  * NOTE: this is a special-purpose facility that should only be used in very
 180  * limited circumstances, in almost all cases the global concurrent queues
 181  * should be preferred. While this facility allows for more flexibility in
 182  * configuring worker threads for special needs it comes at the cost of
 183  * increased overall memory usage due to reduced thread sharing and higher
 184  * latency in worker thread bringup.
 185  *
 186  * Dispatch pthread root queues do not support suspension, application context
 187  * and change of width or of target queue. They can however be used as the
 188  * target queue for serial or concurrent queues obtained via
 189  * dispatch_queue_create() or dispatch_queue_create_with_target(), which
 190  * enables the blocks submitted to those queues to be processed on the root
 191  * queue's pthread pool.
 192  *
 193  * When a dispatch pthread root queue is no longer needed, it should be
 194  * released with dispatch_release(). Existing worker pthreads and pending blocks
 195  * submitted to the root queue will hold a reference to the queue so it will not
 196  * be deallocated until all blocks have finished and worker threads exited.
 197  *
 198  * @param label
 199  * A string label to attach to the queue.
 200  * This parameter is optional and may be NULL.
 201  *
 202  * @param flags
 203  * Pass flags value returned by dispatch_pthread_root_queue_flags_pool_size()
 204  * or 0 if unused.
 205  *
 206  * @param attr
 207  * Attributes passed to pthread_create(3) when creating worker pthreads. This
 208  * parameter is copied and can be destroyed after this call returns.
 209  * This parameter is optional and may be NULL.
 210  *
 211  * @param configure
 212  * Configuration block called on newly created worker pthreads before any blocks
 213  * for the root queue are executed. The block may configure the current thread
 214  * as needed.
 215  * This parameter is optional and may be NULL.
 216  *
 217  * @result
 218  * The newly created dispatch pthread root queue.
 219  */
 220 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 221 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 222 DISPATCH_NOTHROW
 223 dispatch_queue_t
 224 dispatch_pthread_root_queue_create(const char *label, unsigned long flags,
 225         const pthread_attr_t *attr, dispatch_block_t configure);
 226
 227 /*!
 228  * @function dispatch_pthread_root_queue_flags_pool_size
 229  *
 230  * @abstract
 231  * Returns flags argument to pass to dispatch_pthread_root_queue_create() to
 232  * specify the maximum size of the pthread pool to use for a pthread root queue.
 233  *
 234  * @param pool_size
 235  * Maximum size of the pthread pool to use for the root queue. The number of
 236  * pthreads created for this root queue will never exceed this number but there
 237  * is no guarantee that the specified number will be reached.
 238  * Pass 0 to specify that a default pool size determined by the system should
 239  * be used.
 240  *
 241  * @result
 242  * The flags argument to pass to dispatch_pthread_root_queue_create().
 243  */
 244 DISPATCH_INLINE DISPATCH_ALWAYS_INLINE
 245 unsigned long
 246 dispatch_pthread_root_queue_flags_pool_size(uint8_t pool_size)
 247 {
 248         #define _DISPATCH_PTHREAD_ROOT_QUEUE_FLAG_POOL_SIZE (0x80000000ul)
 249         return (_DISPATCH_PTHREAD_ROOT_QUEUE_FLAG_POOL_SIZE |
 250                         (unsigned long)pool_size);
 251 }
 252
 253 #endif /* __BLOCKS__ */
 254
 255 /*!
 256  * @constant DISPATCH_APPLY_CURRENT_ROOT_QUEUE
 257  * @discussion Constant to pass to the dispatch_apply() and dispatch_apply_f()
 258  * functions to indicate that the root queue for the current thread should be
 259  * used (i.e. one of the global concurrent queues or a queue created with
 260  * dispatch_pthread_root_queue_create()). If there is no such queue, the
 261  * default priority global concurrent queue will be used.
 262  */
 263 #define DISPATCH_APPLY_CURRENT_ROOT_QUEUE NULL
 264
 265 /*!
 266  * @function dispatch_assert_queue
 267  *
 268  * @abstract
 269  * Verifies that the current block is executing on a certain dispatch queue.
 270  *
 271  * @discussion
 272  * Some code expects to be run on a specific dispatch queue. This function
 273  * verifies that expectation for debugging.
 274  *
 275  * This function will only return if the currently executing block was submitted
 276  * to the specified queue or to any queue targeting it (see
 277  * dispatch_set_target_queue()). Otherwise, it logs an explanation to the system
 278  * log, then terminates the application.
 279  *
 280  * When dispatch_assert_queue() is called outside of the context of a
 281  * submitted block, its behavior is undefined.
 282  *
 283  * Passing the result of dispatch_get_main_queue() to this function verifies
 284  * that the current block was submitted to the main queue or to a queue
 285  * targeting it.
 286  * IMPORTANT: this is NOT the same as verifying that the current block is
 287  * executing on the main thread.
 288  *
 289  * The variant dispatch_assert_queue_debug() is compiled out when the
 290  * preprocessor macro NDEBUG is defined. (See also assert(3)).
 291  *
 292  * @param queue
 293  * The dispatch queue that the current block is expected to run on.
 294  * The result of passing NULL in this parameter is undefined.
 295  */
 296 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 297 DISPATCH_EXPORT DISPATCH_NONNULL1
 298 void
 299 dispatch_assert_queue(dispatch_queue_t queue);
 300
 301 /*!
 302  * @function dispatch_assert_queue_not
 303  *
 304  * @abstract
 305  * Verifies that the current block is not executing on a certain dispatch queue.
 306  *
 307  * @discussion
 308  * This function is the equivalent of dispatch_queue_assert() with the test for
 309  * equality inverted. See discussion there.
 310  *
 311  * The variant dispatch_assert_queue_not_debug() is compiled out when the
 312  * preprocessor macro NDEBUG is defined. (See also assert(3)).
 313  *
 314  * @param queue
 315  * The dispatch queue that the current block is expected not to run on.
 316  * The result of passing NULL in this parameter is undefined.
 317  */
 318 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
 319 DISPATCH_EXPORT DISPATCH_NONNULL1
 320 void
 321 dispatch_assert_queue_not(dispatch_queue_t queue);
 322
 323 #ifdef NDEBUG
 324 #define dispatch_assert_queue_debug(q) ((void)0)
 325 #define dispatch_assert_queue_not_debug(q) ((void)0)
 326 #else
 327 #define dispatch_assert_queue_debug(q) dispatch_assert_queue(q)
 328 #define dispatch_assert_queue_not_debug(q) dispatch_assert_queue_not(q)
 329 #endif
 330
 331 __END_DECLS
 332
 333 #endif