pthread/qos.h

   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 #if __has_feature(assume_nonnull)
  37 _Pragma("clang assume_nonnull begin")
  38 #endif
  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,
 113                 qos_class_t * _Nullable __restrict __qos_class,
 114                 int * _Nullable __restrict __relative_priority);
 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,
 185                 qos_class_t * _Nullable __restrict __qos_class,
 186                 int * _Nullable __restrict __relative_priority);
 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
 294 #if __has_feature(assume_nonnull)
 295 _Pragma("clang assume_nonnull end")
 296 #endif
 297
 298 #endif // KERNEL
 299
 300 #endif // __DARWIN_C_LEVEL >= __DARWIN_C_FULL
 301
 302 #endif // _PTHREAD_QOS_H