private/queue_private.h

   1 /*
   2  * Copyright (c) 2008-2010 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 /*!
  39  * @enum dispatch_queue_flags_t
  40  *
  41  * @constant DISPATCH_QUEUE_OVERCOMMIT
  42  * The queue will create a new thread for invoking blocks, regardless of how
  43  * busy the computer is.
  44  */
  45 enum {
  46         DISPATCH_QUEUE_OVERCOMMIT = 0x2ull,
  47 };
  48
  49 #define DISPATCH_QUEUE_FLAGS_MASK (DISPATCH_QUEUE_OVERCOMMIT)
  50
  51 /*!
  52  * @function dispatch_queue_set_width
  53  *
  54  * @abstract
  55  * Set the width of concurrency for a given queue. The width of a serial queue
  56  * is one.
  57  *
  58  * @discussion
  59  * This SPI is DEPRECATED and will be removed in a future release.
  60  * Uses of this SPI to make a queue concurrent by setting its width to LONG_MAX
  61  * should be replaced by passing DISPATCH_QUEUE_CONCURRENT to
  62  * dispatch_queue_create().
  63  * Uses of this SPI to limit queue concurrency are not recommended and should
  64  * be replaced by alternative mechanisms such as a dispatch semaphore created
  65  * with the desired concurrency width.
  66  *
  67  * @param queue
  68  * The queue to adjust. Passing the main queue or a global concurrent queue
  69  * will be ignored.
  70  *
  71  * @param width
  72  * The new maximum width of concurrency depending on available resources.
  73  * If zero is passed, then the value is promoted to one.
  74  * Negative values are magic values that map to automatic width values.
  75  * Unknown negative values default to DISPATCH_QUEUE_WIDTH_MAX_LOGICAL_CPUS.
  76  */
  77 #define DISPATCH_QUEUE_WIDTH_ACTIVE_CPUS                -1
  78 #define DISPATCH_QUEUE_WIDTH_MAX_PHYSICAL_CPUS  -2
  79 #define DISPATCH_QUEUE_WIDTH_MAX_LOGICAL_CPUS   -3
  80
  81 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  82 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  83 void
  84 dispatch_queue_set_width(dispatch_queue_t dq, long width); // DEPRECATED
  85
  86 /*!
  87  * @function dispatch_set_current_target_queue
  88  *
  89  * @abstract
  90  * Synchronously sets the target queue of the current serial queue.
  91  *
  92  * @discussion
  93  * This SPI is provided for a limited purpose case when calling
  94  * dispatch_set_target_queue() is not sufficient. It works similarly to
  95  * dispatch_set_target_queue() except the target queue of the current queue
  96  * is immediately changed so that pending blocks on the queue will run on the
  97  * new target queue. Calling this from outside of a block executing on a serial
  98  * queue is undefined.
  99  *
 100  * @param queue
 101  * The new target queue for the object. The queue is retained, and the
 102  * previous target queue, if any, is released.
 103  * If queue is DISPATCH_TARGET_QUEUE_DEFAULT, set the object's target queue
 104  * to the default target queue for the given object type.
 105  */
 106
 107 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0)
 108 DISPATCH_EXPORT DISPATCH_NOTHROW
 109 void
 110 dispatch_set_current_target_queue(dispatch_queue_t queue);
 111
 112 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
 113 DISPATCH_EXPORT const struct dispatch_queue_offsets_s {
 114         // always add new fields at the end
 115         const uint16_t dqo_version;
 116         const uint16_t dqo_label;
 117         const uint16_t dqo_label_size;
 118         const uint16_t dqo_flags;
 119         const uint16_t dqo_flags_size;
 120         const uint16_t dqo_serialnum;
 121         const uint16_t dqo_serialnum_size;
 122         const uint16_t dqo_width;
 123         const uint16_t dqo_width_size;
 124         const uint16_t dqo_running;
 125         const uint16_t dqo_running_size;
 126 } dispatch_queue_offsets;
 127
 128 /*!
 129  * @function dispatch_flush_continuation_cache
 130  *
 131  * @abstract
 132  * Flushes the current thread's cache of continuation objects, if any.
 133  *
 134  * @discussion
 135  * Warning: this function is subject to change in a future release.
 136  * Please contact the GCD team before using it in your code.
 137  */
 138
 139 __OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_NA)
 140 DISPATCH_EXPORT DISPATCH_NOTHROW
 141 void
 142 dispatch_flush_continuation_cache(void);
 143
 144 __END_DECLS
 145
 146 #endif