include/sys/qos.h

   1 /*
   2  * Copyright (c) 2013-2014 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef _SYS_QOS_H
  25 #define _SYS_QOS_H
  26
  27 #include <sys/cdefs.h>
  28 #include <Availability.h>
  29
  30 /*!
  31  * @typedef qos_class_t
  32  *
  33  * @abstract
  34  * An abstract thread quality of service (QOS) classification.
  35  *
  36  * @discussion
  37  * Thread quality of service (QOS) classes are ordered abstract representations
  38  * of the nature of work that is expected to be performed by a pthread, dispatch
  39  * queue, or NSOperation. Each class specifies a maximum thread scheduling
  40  * priority for that band (which may be used in combination with a relative
  41  * priority offset within the band), as well as quality of service
  42  * characteristics for timer latency, CPU throughput, I/O throughput, network
  43  * socket traffic management behavior and more.
  44  *
  45  * A best effort is made to allocate available system resources to every QOS
  46  * class. Quality of service degredation only occurs during system resource
  47  * contention, proportionally to the QOS class. That said, QOS classes
  48  * representing user-initiated work attempt to achieve peak throughput while
  49  * QOS classes for other work attempt to achieve peak energy and thermal
  50  * efficiency, even in the absence of contention. Finally, the use of QOS
  51  * classes does not allow threads to supersede any limits that may be applied
  52  * to the overall process.
  53  */
  54
  55 /*!
  56  * @constant QOS_CLASS_USER_INTERACTIVE
  57  * @abstract A QOS class which indicates work performed by this thread
  58  * is interactive with the user.
  59  * @discussion Such work is requested to run at high priority relative to other
  60  * work on the system. Specifying this QOS class is a request to run with
  61  * nearly all available system CPU and I/O bandwidth even under contention.
  62  * This is not an energy-efficient QOS class to use for large tasks. The use of
  63  * this QOS class should be limited to critical interaction with the user such
  64  * as handling events on the main event loop, view drawing, animation, etc.
  65  *
  66  * @constant QOS_CLASS_USER_INITIATED
  67  * @abstract A QOS class which indicates work performed by this thread
  68  * was initiated by the user and that the user is likely waiting for the
  69  * results.
  70  * @discussion Such work is requested to run at a priority below critical user-
  71  * interactive work, but relatively higher than other work on the system. This
  72  * is not an energy-efficient QOS class to use for large tasks. Its use
  73  * should be limited to operations of short enough duration that the user is
  74  * unlikely to switch tasks while waiting for the results. Typical
  75  * user-initiated work will have progress indicated by the display of
  76  * placeholder content or modal user interface.
  77  *
  78  * @constant QOS_CLASS_DEFAULT
  79  * @abstract A default QOS class used by the system in cases where more specific
  80  * QOS class information is not available.
  81  * @discussion Such work is requested to run at a priority below critical user-
  82  * interactive and user-initiated work, but relatively higher than utility and
  83  * background tasks. Threads created by pthread_create() without an attribute
  84  * specifying a QOS class will default to QOS_CLASS_DEFAULT. This QOS class
  85  * value is not intended to be used as a work classification, it should only be
  86  * set when propagating or restoring QOS class values provided by the system.
  87  *
  88  * @constant QOS_CLASS_UTILITY
  89  * @abstract A QOS class which indicates work performed by this thread
  90  * may or may not be initiated by the user and that the user is unlikely to be
  91  * immediately waiting for the results.
  92  * @discussion Such work is requested to run at a priority below critical user-
  93  * interactive and user-initiated work, but relatively higher than low-level
  94  * system maintenance tasks. The use of this QOS class indicates the work
  95  * should be run in an energy and thermally-efficient manner. The progress of
  96  * utility work may or may not be indicated to the user, but the effect of such
  97  * work is user-visible.
  98  *
  99  * @constant QOS_CLASS_BACKGROUND
 100  * @abstract A QOS class which indicates work performed by this thread was not
 101  * initiated by the user and that the user may be unaware of the results.
 102  * @discussion Such work is requested to run at a priority below other work.
 103  * The use of this QOS class indicates the work should be run in the most energy
 104  * and thermally-efficient manner.
 105  *
 106  * @constant QOS_CLASS_UNSPECIFIED
 107  * @abstract A QOS class value which indicates the absence or removal of QOS
 108  * class information.
 109  * @discussion As an API return value, may indicate that threads or pthread
 110  * attributes were configured with legacy API incompatible or in conflict with
 111  * the QOS class system.
 112  */
 113
 114 #define __QOS_ENUM(name, type, ...) enum { __VA_ARGS__ }; typedef type name##_t
 115 #define __QOS_CLASS_AVAILABLE(...)
 116
 117 #if defined(__cplusplus) || defined(__OBJC__) || __LP64__
 118 #if defined(__has_feature) && defined(__has_extension)
 119 #if __has_feature(objc_fixed_enum) || __has_extension(cxx_strong_enums)
 120 #undef __QOS_ENUM
 121 #define __QOS_ENUM(name, type, ...) typedef enum : type { __VA_ARGS__ } name##_t
 122 #endif
 123 #endif
 124 #if __has_feature(enumerator_attributes)
 125 #undef __QOS_CLASS_AVAILABLE
 126 #define __QOS_CLASS_AVAILABLE __API_AVAILABLE
 127 #endif
 128 #endif
 129
 130 __QOS_ENUM(qos_class, unsigned int,
 131         QOS_CLASS_USER_INTERACTIVE
 132                         __QOS_CLASS_AVAILABLE(macos(10.10), ios(8.0)) = 0x21,
 133         QOS_CLASS_USER_INITIATED
 134                         __QOS_CLASS_AVAILABLE(macos(10.10), ios(8.0)) = 0x19,
 135         QOS_CLASS_DEFAULT
 136                         __QOS_CLASS_AVAILABLE(macos(10.10), ios(8.0)) = 0x15,
 137         QOS_CLASS_UTILITY
 138                         __QOS_CLASS_AVAILABLE(macos(10.10), ios(8.0)) = 0x11,
 139         QOS_CLASS_BACKGROUND
 140                         __QOS_CLASS_AVAILABLE(macos(10.10), ios(8.0)) = 0x09,
 141         QOS_CLASS_UNSPECIFIED
 142                         __QOS_CLASS_AVAILABLE(macos(10.10), ios(8.0)) = 0x00,
 143 );
 144
 145 #undef __QOS_ENUM
 146
 147 /*!
 148  * @constant QOS_MIN_RELATIVE_PRIORITY
 149  * @abstract The minimum relative priority that may be specified within a
 150  * QOS class. These priorities are relative only within a given QOS class
 151  * and meaningful only for the current process.
 152  */
 153 #define QOS_MIN_RELATIVE_PRIORITY (-15)
 154
 155 /* Userspace (only) definitions */
 156
 157 #ifndef KERNEL
 158
 159 __BEGIN_DECLS
 160
 161 /*!
 162  * @function qos_class_self
 163  *
 164  * @abstract
 165  * Returns the requested QOS class of the current thread.
 166  *
 167  * @return
 168  * One of the QOS class values in qos_class_t.
 169  */
 170 __API_AVAILABLE(macos(10.10), ios(8.0))
 171 qos_class_t
 172 qos_class_self(void);
 173
 174 /*!
 175  * @function qos_class_main
 176  *
 177  * @abstract
 178  * Returns the initial requested QOS class of the main thread.
 179  *
 180  * @discussion
 181  * The QOS class that the main thread of a process is created with depends on
 182  * the type of process (e.g. application or daemon) and on how it has been
 183  * launched.
 184  *
 185  * This function returns that initial requested QOS class value chosen by the
 186  * system to enable propagation of that classification to matching work not
 187  * executing on the main thread.
 188  *
 189  * @return
 190  * One of the QOS class values in qos_class_t.
 191  */
 192 __API_AVAILABLE(macos(10.10), ios(8.0))
 193 qos_class_t
 194 qos_class_main(void);
 195
 196 __END_DECLS
 197
 198 #endif // KERNEL
 199
 200 #endif // _SYS_QOS_H