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 <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))
  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  */
 112 __API_AVAILABLE(macos(10.10), ios(8.0))
 113 int
 114 pthread_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))
 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  */
 184 __API_AVAILABLE(macos(10.10), ios(8.0))
 185 int
 186 pthread_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
 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  */
 263 __API_AVAILABLE(macos(10.10), ios(8.0))
 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  */
 291 __API_AVAILABLE(macos(10.10), ios(8.0))
 292 int
 293 pthread_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