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