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 _PTHREAD_QOS_H
 25#define _PTHREAD_QOS_H
 26
 27#include <sys/cdefs.h>
 28#include <sys/_pthread/_pthread_attr_t.h> /* pthread_attr_t */
 29#include <sys/_pthread/_pthread_t.h>      /* pthread_t */
 30#include <Availability.h>
 31
 32#if __DARWIN_C_LEVEL >= __DARWIN_C_FULL
 33
 34#include <sys/qos.h>
 35
 36#ifndef KERNEL
 37
 38#if __has_feature(assume_nonnull)
 39_Pragma("clang assume_nonnull begin")
 40#endif
 41__BEGIN_DECLS
 42
 43/*!
 44 * @function pthread_attr_set_qos_class_np
 45 *
 46 * @abstract
 47 * Sets the QOS class and relative priority of a pthread attribute structure
 48 * which may be used to specify the requested QOS class of newly created
 49 * threads.
 50 *
 51 * @discussion
 52 * The QOS class and relative priority represent an overall combination of
 53 * system quality of service attributes on a thread.
 54 *
 55 * Subsequent calls to interfaces such as pthread_attr_setschedparam() that are
 56 * incompatible or in conflict with the QOS class system will unset the QOS
 57 * class requested with this interface and pthread_attr_get_qos_class_np() will
 58 * return QOS_CLASS_UNSPECIFIED.
 59 *
 60 * @param __attr
 61 * The pthread attribute structure to modify.
 62 *
 63 * @param __qos_class
 64 * A QOS class value:
 65 *	- QOS_CLASS_USER_INTERACTIVE
 66 *	- QOS_CLASS_USER_INITIATED
 67 *	- QOS_CLASS_DEFAULT
 68 *	- QOS_CLASS_UTILITY
 69 *	- QOS_CLASS_BACKGROUND
 70 * EINVAL will be returned if any other value is provided.
 71 *
 72 * @param __relative_priority
 73 * A relative priority within the QOS class. This value is a negative offset
 74 * from the maximum supported scheduler priority for the given class.
 75 * EINVAL will be returned if the value is greater than zero or less than
 76 * QOS_MIN_RELATIVE_PRIORITY.
 77 *
 78 * @return
 79 * Zero if successful, otherwise an errno value.
 80 */
 81__API_AVAILABLE(macos(10.10), ios(8.0))
 82int
 83pthread_attr_set_qos_class_np(pthread_attr_t *__attr,
 84		qos_class_t __qos_class, int __relative_priority);
 85
 86/*!
 87 * @function pthread_attr_get_qos_class_np
 88 *
 89 * @abstract
 90 * Gets the QOS class and relative priority of a pthread attribute structure.
 91 *
 92 * @param __attr
 93 * The pthread attribute structure to inspect.
 94 *
 95 * @param __qos_class
 96 * On output, a QOS class value:
 97 *	- QOS_CLASS_USER_INTERACTIVE
 98 *	- QOS_CLASS_USER_INITIATED
 99 *	- QOS_CLASS_DEFAULT
100 *	- QOS_CLASS_UTILITY
101 *	- QOS_CLASS_BACKGROUND
102 *	- QOS_CLASS_UNSPECIFIED
103 * This value may be NULL in which case no value is returned.
104 *
105 * @param __relative_priority
106 * On output, a relative priority offset within the QOS class.
107 * This value may be NULL in which case no value is returned.
108 *
109 * @return
110 * Zero if successful, otherwise an errno value.
111 */
112__API_AVAILABLE(macos(10.10), ios(8.0))
113int
114pthread_attr_get_qos_class_np(pthread_attr_t * __restrict __attr,
115		qos_class_t * _Nullable __restrict __qos_class,
116		int * _Nullable __restrict __relative_priority);
117
118/*!
119 * @function pthread_set_qos_class_self_np
120 *
121 * @abstract
122 * Sets the requested QOS class and relative priority of the current thread.
123 *
124 * @discussion
125 * The QOS class and relative priority represent an overall combination of
126 * system quality of service attributes on a thread.
127 *
128 * Subsequent calls to interfaces such as pthread_setschedparam() that are
129 * incompatible or in conflict with the QOS class system will unset the QOS
130 * class requested with this interface and pthread_get_qos_class_np() will
131 * return QOS_CLASS_UNSPECIFIED thereafter. A thread so modified is permanently
132 * opted-out of the QOS class system and calls to this function to request a QOS
133 * class for such a thread will fail and return EPERM.
134 *
135 * @param __qos_class
136 * A QOS class value:
137 *	- QOS_CLASS_USER_INTERACTIVE
138 *	- QOS_CLASS_USER_INITIATED
139 *	- QOS_CLASS_DEFAULT
140 *	- QOS_CLASS_UTILITY
141 *	- QOS_CLASS_BACKGROUND
142 * EINVAL will be returned if any other value is provided.
143 *
144 * @param __relative_priority
145 * A relative priority within the QOS class. This value is a negative offset
146 * from the maximum supported scheduler priority for the given class.
147 * EINVAL will be returned if the value is greater than zero or less than
148 * QOS_MIN_RELATIVE_PRIORITY.
149 *
150 * @return
151 * Zero if successful, otherwise an errno value.
152 */
153__API_AVAILABLE(macos(10.10), ios(8.0))
154int
155pthread_set_qos_class_self_np(qos_class_t __qos_class,
156		int __relative_priority);
157
158/*!
159 * @function pthread_get_qos_class_np
160 *
161 * @abstract
162 * Gets the requested QOS class and relative priority of a thread.
163 *
164 * @param __pthread
165 * The target thread to inspect.
166 *
167 * @param __qos_class
168 * On output, a QOS class value:
169 *	- QOS_CLASS_USER_INTERACTIVE
170 *	- QOS_CLASS_USER_INITIATED
171 *	- QOS_CLASS_DEFAULT
172 *	- QOS_CLASS_UTILITY
173 *	- QOS_CLASS_BACKGROUND
174 *	- QOS_CLASS_UNSPECIFIED
175 * This value may be NULL in which case no value is returned.
176 *
177 * @param __relative_priority
178 * On output, a relative priority offset within the QOS class.
179 * This value may be NULL in which case no value is returned.
180 *
181 * @return
182 * Zero if successful, otherwise an errno value.
183 */
184__API_AVAILABLE(macos(10.10), ios(8.0))
185int
186pthread_get_qos_class_np(pthread_t __pthread,
187		qos_class_t * _Nullable __restrict __qos_class,
188		int * _Nullable __restrict __relative_priority);
189
190/*!
191 * @typedef pthread_override_t
192 *
193 * @abstract
194 * An opaque object representing a QOS class override of a thread.
195 *
196 * @discussion
197 * A QOS class override of a target thread expresses that an item of pending
198 * work classified with a specific QOS class and relative priority depends on
199 * the completion of the work currently being executed by the thread (e.g. due
200 * to ordering requirements).
201 *
202 * While overrides are in effect, the target thread will execute at the maximum
203 * QOS class and relative priority of all overrides and of the QOS class
204 * requested by the thread itself.
205 *
206 * A QOS class override does not modify the target thread's requested QOS class
207 * value and the effect of an override is not visible to the qos_class_self()
208 * and pthread_get_qos_class_np() interfaces.
209 */
210
211typedef struct pthread_override_s* pthread_override_t;
212
213/*!
214 * @function pthread_override_qos_class_start_np
215 *
216 * @abstract
217 * Starts a QOS class override of the specified target thread.
218 *
219 * @discussion
220 * Starting a QOS class override of the specified target thread expresses that
221 * an item of pending work classified with the specified QOS class and relative
222 * priority depends on the completion of the work currently being executed by
223 * the thread (e.g. due to ordering requirements).
224 *
225 * While overrides are in effect, the specified target thread will execute at
226 * the maximum QOS class and relative priority of all overrides and of the QOS
227 * class requested by the thread itself.
228 *
229 * Starting a QOS class override does not modify the target thread's requested
230 * QOS class value and the effect of an override is not visible to the
231 * qos_class_self() and pthread_get_qos_class_np() interfaces.
232 *
233 * The returned newly allocated override object is intended to be associated
234 * with the item of pending work in question. Once the dependency has been
235 * satisfied and enabled that work to begin executing, the QOS class override
236 * must be ended by passing the associated override object to
237 * pthread_override_qos_class_end_np(). Failure to do so will result in the
238 * associated resources to be leaked and the target thread to be permanently
239 * executed at an inappropriately elevated QOS class.
240 *
241 * @param __pthread
242 * The target thread to modify.
243 *
244 * @param __qos_class
245 * A QOS class value:
246 *	- QOS_CLASS_USER_INTERACTIVE
247 *	- QOS_CLASS_USER_INITIATED
248 *	- QOS_CLASS_DEFAULT
249 *	- QOS_CLASS_UTILITY
250 *	- QOS_CLASS_BACKGROUND
251 * NULL will be returned if any other value is provided.
252 *
253 * @param __relative_priority
254 * A relative priority within the QOS class. This value is a negative offset
255 * from the maximum supported scheduler priority for the given class.
256 * NULL will be returned if the value is greater than zero or less than
257 * QOS_MIN_RELATIVE_PRIORITY.
258 *
259 * @return
260 * A newly allocated override object if successful, or NULL if the override
261 * could not be started.
262 */
263__API_AVAILABLE(macos(10.10), ios(8.0))
264pthread_override_t
265pthread_override_qos_class_start_np(pthread_t __pthread,
266		qos_class_t __qos_class, int __relative_priority);
267
268/*!
269 * @function pthread_override_qos_class_end_np
270 *
271 * @abstract
272 * Ends a QOS class override.
273 *
274 * @discussion
275 * Passing an override object returned by pthread_override_qos_class_start_np()
276 * ends the QOS class override started by that call and deallocates all
277 * associated resources as well as the override object itself.
278 *
279 * The thread starting and the thread ending a QOS class override need not be
280 * identical. If the thread ending the override is the the target thread of the
281 * override itself, it should take care to elevate its requested QOS class
282 * appropriately with pthread_set_qos_class_self_np() before ending the
283 * override.
284 *
285 * @param __override
286 * An override object returned by pthread_override_qos_class_start_np().
287 *
288 * @return
289 * Zero if successful, otherwise an errno value.
290 */
291__API_AVAILABLE(macos(10.10), ios(8.0))
292int
293pthread_override_qos_class_end_np(pthread_override_t __override);
294
295__END_DECLS
296#if __has_feature(assume_nonnull)
297_Pragma("clang assume_nonnull end")
298#endif
299
300#endif // KERNEL
301
302#endif // __DARWIN_C_LEVEL >= __DARWIN_C_FULL
303
304#endif // _PTHREAD_QOS_H