[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 <sys/_pthread/_pthread_attr_t.h> /* pthread_attr_t */
#include <sys/_pthread/_pthread_t.h>      /* pthread_t */
#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.
 */
__API_AVAILABLE(macos(10.10), ios(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.
 */
__API_AVAILABLE(macos(10.10), ios(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.
 */
__API_AVAILABLE(macos(10.10), ios(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.
 */
__API_AVAILABLE(macos(10.10), ios(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.
 */
__API_AVAILABLE(macos(10.10), ios(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.
 */
__API_AVAILABLE(macos(10.10), ios(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>
a0619f9c A	28	#include <sys/_pthread/_pthread_attr_t.h> /* pthread_attr_t */
a0619f9c A	29	#include <sys/_pthread/_pthread_t.h> /* pthread_t */
f1a1da6c A	30	#include <Availability.h>
	31
	32	#if __DARWIN_C_LEVEL >= __DARWIN_C_FULL
	33
	34	#include <sys/qos.h>
	35
	36	#ifndef KERNEL
	37
2546420a A	38	#if __has_feature(assume_nonnull)
	39	_Pragma("clang assume_nonnull begin")
	40	#endif
f1a1da6c A	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	*/
a0619f9c	81	__API_AVAILABLE(macos(10.10), ios(8.0))
f1a1da6c A	82	int
	83	pthread_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	*/
a0619f9c	112	__API_AVAILABLE(macos(10.10), ios(8.0))
f1a1da6c A	113	int
f1a1da6c A	114	pthread_attr_get_qos_class_np(pthread_attr_t * __restrict __attr,
2546420a A	115	qos_class_t * _Nullable __restrict __qos_class,
2546420a A	116	int * _Nullable __restrict __relative_priority);
f1a1da6c A	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	*/
a0619f9c	153	__API_AVAILABLE(macos(10.10), ios(8.0))
f1a1da6c A	154	int
	155	pthread_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	*/
a0619f9c	184	__API_AVAILABLE(macos(10.10), ios(8.0))
f1a1da6c A	185	int
f1a1da6c A	186	pthread_get_qos_class_np(pthread_t __pthread,
2546420a A	187	qos_class_t * _Nullable __restrict __qos_class,
2546420a A	188	int * _Nullable __restrict __relative_priority);
f1a1da6c A	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
	211	typedef 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	*/
a0619f9c	263	__API_AVAILABLE(macos(10.10), ios(8.0))
f1a1da6c A	264	pthread_override_t
	265	pthread_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	*/
a0619f9c	291	__API_AVAILABLE(macos(10.10), ios(8.0))
f1a1da6c A	292	int
	293	pthread_override_qos_class_end_np(pthread_override_t __override);
	294
	295	__END_DECLS
2546420a A	296	#if __has_feature(assume_nonnull)
	297	_Pragma("clang assume_nonnull end")
	298	#endif
f1a1da6c A	299
	300	#endif // KERNEL
	301
	302	#endif // __DARWIN_C_LEVEL >= __DARWIN_C_FULL
	303
	304	#endif // _PTHREAD_QOS_H