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))
171qos_class_t
172qos_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))
193qos_class_t
194qos_class_main(void);
195
196__END_DECLS
197
198#endif // KERNEL
199
200#endif // _SYS_QOS_H