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 __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)
  77 int
  78 pthread_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)
 108 int
 109 pthread_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)
 149 int
 150 pthread_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)
 180 int
 181 pthread_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
 206 typedef 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)
 259 pthread_override_t
 260 pthread_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)
 287 int
 288 pthread_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