[apple/libpthread.git] / pthread / qos.h

/*
 * Copyright (c) 2013-2014 Apple Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_LICENSE_HEADER_END@
 */

#ifndef _PTHREAD_QOS_H
#define _PTHREAD_QOS_H

#include <sys/cdefs.h>
#include <Availability.h>

#if __DARWIN_C_LEVEL >= __DARWIN_C_FULL

#include <sys/qos.h>

#ifndef KERNEL

#if __has_feature(assume_nonnull)
_Pragma("clang assume_nonnull begin")
#endif
__BEGIN_DECLS

/*!
 * @function pthread_attr_set_qos_class_np
 *
 * @abstract
 * Sets the QOS class and relative priority of a pthread attribute structure
 * which may be used to specify the requested QOS class of newly created
 * threads.
 *
 * @discussion
 * The QOS class and relative priority represent an overall combination of
 * system quality of service attributes on a thread.
 *
 * Subsequent calls to interfaces such as pthread_attr_setschedparam() that are
 * incompatible or in conflict with the QOS class system will unset the QOS
 * class requested with this interface and pthread_attr_get_qos_class_np() will
 * return QOS_CLASS_UNSPECIFIED.
 *
 * @param __attr
 * The pthread attribute structure to modify.
 *
 * @param __qos_class
 * A QOS class value:
 *	- QOS_CLASS_USER_INTERACTIVE
 *	- QOS_CLASS_USER_INITIATED
 *	- QOS_CLASS_DEFAULT
 *	- QOS_CLASS_UTILITY
 *	- QOS_CLASS_BACKGROUND
 * EINVAL will be returned if any other value is provided.
 *
 * @param __relative_priority
 * A relative priority within the QOS class. This value is a negative offset
 * from the maximum supported scheduler priority for the given class.
 * EINVAL will be returned if the value is greater than zero or less than
 * QOS_MIN_RELATIVE_PRIORITY.
 *
 * @return
 * Zero if successful, otherwise an errno value.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
int
pthread_attr_set_qos_class_np(pthread_attr_t *__attr,
		qos_class_t __qos_class, int __relative_priority);

/*!
 * @function pthread_attr_get_qos_class_np
 *
 * @abstract
 * Gets the QOS class and relative priority of a pthread attribute structure.
 *
 * @param __attr
 * The pthread attribute structure to inspect.
 *
 * @param __qos_class
 * On output, a QOS class value:
 *	- QOS_CLASS_USER_INTERACTIVE
 *	- QOS_CLASS_USER_INITIATED
 *	- QOS_CLASS_DEFAULT
 *	- QOS_CLASS_UTILITY
 *	- QOS_CLASS_BACKGROUND
 *	- QOS_CLASS_UNSPECIFIED
 * This value may be NULL in which case no value is returned.
 *
 * @param __relative_priority
 * On output, a relative priority offset within the QOS class.
 * This value may be NULL in which case no value is returned.
 *
 * @return
 * Zero if successful, otherwise an errno value.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
int
pthread_attr_get_qos_class_np(pthread_attr_t * __restrict __attr,
		qos_class_t * _Nullable __restrict __qos_class,
		int * _Nullable __restrict __relative_priority);

/*!
 * @function pthread_set_qos_class_self_np
 *
 * @abstract
 * Sets the requested QOS class and relative priority of the current thread.
 *
 * @discussion
 * The QOS class and relative priority represent an overall combination of
 * system quality of service attributes on a thread.
 *
 * Subsequent calls to interfaces such as pthread_setschedparam() that are
 * incompatible or in conflict with the QOS class system will unset the QOS
 * class requested with this interface and pthread_get_qos_class_np() will
 * return QOS_CLASS_UNSPECIFIED thereafter. A thread so modified is permanently
 * opted-out of the QOS class system and calls to this function to request a QOS
 * class for such a thread will fail and return EPERM.
 *
 * @param __qos_class
 * A QOS class value:
 *	- QOS_CLASS_USER_INTERACTIVE
 *	- QOS_CLASS_USER_INITIATED
 *	- QOS_CLASS_DEFAULT
 *	- QOS_CLASS_UTILITY
 *	- QOS_CLASS_BACKGROUND
 * EINVAL will be returned if any other value is provided.
 *
 * @param __relative_priority
 * A relative priority within the QOS class. This value is a negative offset
 * from the maximum supported scheduler priority for the given class.
 * EINVAL will be returned if the value is greater than zero or less than
 * QOS_MIN_RELATIVE_PRIORITY.
 *
 * @return
 * Zero if successful, otherwise an errno value.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
int
pthread_set_qos_class_self_np(qos_class_t __qos_class,
		int __relative_priority);

/*!
 * @function pthread_get_qos_class_np
 *
 * @abstract
 * Gets the requested QOS class and relative priority of a thread.
 *
 * @param __pthread
 * The target thread to inspect.
 *
 * @param __qos_class
 * On output, a QOS class value:
 *	- QOS_CLASS_USER_INTERACTIVE
 *	- QOS_CLASS_USER_INITIATED
 *	- QOS_CLASS_DEFAULT
 *	- QOS_CLASS_UTILITY
 *	- QOS_CLASS_BACKGROUND
 *	- QOS_CLASS_UNSPECIFIED
 * This value may be NULL in which case no value is returned.
 *
 * @param __relative_priority
 * On output, a relative priority offset within the QOS class.
 * This value may be NULL in which case no value is returned.
 *
 * @return
 * Zero if successful, otherwise an errno value.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
int
pthread_get_qos_class_np(pthread_t __pthread,
		qos_class_t * _Nullable __restrict __qos_class,
		int * _Nullable __restrict __relative_priority);

/*!
 * @typedef pthread_override_t
 *
 * @abstract
 * An opaque object representing a QOS class override of a thread.
 *
 * @discussion
 * A QOS class override of a target thread expresses that an item of pending
 * work classified with a specific QOS class and relative priority depends on
 * the completion of the work currently being executed by the thread (e.g. due
 * to ordering requirements).
 *
 * While overrides are in effect, the target thread will execute at the maximum
 * QOS class and relative priority of all overrides and of the QOS class
 * requested by the thread itself.
 *
 * A QOS class override does not modify the target thread's requested QOS class
 * value and the effect of an override is not visible to the qos_class_self()
 * and pthread_get_qos_class_np() interfaces.
 */

typedef struct pthread_override_s* pthread_override_t;

/*!
 * @function pthread_override_qos_class_start_np
 *
 * @abstract
 * Starts a QOS class override of the specified target thread.
 *
 * @discussion
 * Starting a QOS class override of the specified target thread expresses that
 * an item of pending work classified with the specified QOS class and relative
 * priority depends on the completion of the work currently being executed by
 * the thread (e.g. due to ordering requirements).
 *
 * While overrides are in effect, the specified target thread will execute at
 * the maximum QOS class and relative priority of all overrides and of the QOS
 * class requested by the thread itself.
 *
 * Starting a QOS class override does not modify the target thread's requested
 * QOS class value and the effect of an override is not visible to the
 * qos_class_self() and pthread_get_qos_class_np() interfaces.
 *
 * The returned newly allocated override object is intended to be associated
 * with the item of pending work in question. Once the dependency has been
 * satisfied and enabled that work to begin executing, the QOS class override
 * must be ended by passing the associated override object to
 * pthread_override_qos_class_end_np(). Failure to do so will result in the
 * associated resources to be leaked and the target thread to be permanently
 * executed at an inappropriately elevated QOS class.
 *
 * @param __pthread
 * The target thread to modify.
 *
 * @param __qos_class
 * A QOS class value:
 *	- QOS_CLASS_USER_INTERACTIVE
 *	- QOS_CLASS_USER_INITIATED
 *	- QOS_CLASS_DEFAULT
 *	- QOS_CLASS_UTILITY
 *	- QOS_CLASS_BACKGROUND
 * NULL will be returned if any other value is provided.
 *
 * @param __relative_priority
 * A relative priority within the QOS class. This value is a negative offset
 * from the maximum supported scheduler priority for the given class.
 * NULL will be returned if the value is greater than zero or less than
 * QOS_MIN_RELATIVE_PRIORITY.
 *
 * @return
 * A newly allocated override object if successful, or NULL if the override
 * could not be started.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
pthread_override_t
pthread_override_qos_class_start_np(pthread_t __pthread,
		qos_class_t __qos_class, int __relative_priority);

/*!
 * @function pthread_override_qos_class_end_np
 *
 * @abstract
 * Ends a QOS class override.
 *
 * @discussion
 * Passing an override object returned by pthread_override_qos_class_start_np()
 * ends the QOS class override started by that call and deallocates all
 * associated resources as well as the override object itself.
 *
 * The thread starting and the thread ending a QOS class override need not be
 * identical. If the thread ending the override is the the target thread of the
 * override itself, it should take care to elevate its requested QOS class
 * appropriately with pthread_set_qos_class_self_np() before ending the
 * override.
 *
 * @param __override
 * An override object returned by pthread_override_qos_class_start_np().
 *
 * @return
 * Zero if successful, otherwise an errno value.
 */
__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
int
pthread_override_qos_class_end_np(pthread_override_t __override);

__END_DECLS
#if __has_feature(assume_nonnull)
_Pragma("clang assume_nonnull end")
#endif

#endif // KERNEL

#endif // __DARWIN_C_LEVEL >= __DARWIN_C_FULL

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