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