private/voucher_private.h

   1 /*
   2  * Copyright (c) 2013-2014 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_APACHE_LICENSE_HEADER_START@
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  * @APPLE_APACHE_LICENSE_HEADER_END@
  19  */
  20
  21 #ifndef __OS_VOUCHER_PRIVATE__
  22 #define __OS_VOUCHER_PRIVATE__
  23
  24 #include <os/base.h>
  25 #include <os/object.h>
  26
  27 #define OS_VOUCHER_SPI_VERSION 20141203
  28
  29 #if OS_VOUCHER_WEAK_IMPORT
  30 #define OS_VOUCHER_EXPORT OS_EXPORT OS_WEAK_IMPORT
  31 #else
  32 #define OS_VOUCHER_EXPORT OS_EXPORT
  33 #endif
  34
  35 __BEGIN_DECLS
  36
  37 /*!
  38  * @group Voucher Transport SPI
  39  * SPI intended for clients that need to transport vouchers.
  40  */
  41
  42 /*!
  43  * @typedef voucher_t
  44  *
  45  * @abstract
  46  * Vouchers are immutable sets of key/value attributes that can be adopted on a
  47  * thread in the current process or sent to another process.
  48  *
  49  * @discussion
  50  * Voucher objects are os_objects (c.f. <os/object.h>). They are memory-managed
  51  * with the os_retain()/os_release() functions or -[retain]/-[release] methods.
  52  */
  53 #if OS_OBJECT_USE_OBJC
  54 OS_OBJECT_DECL(voucher);
  55 #else
  56 typedef struct voucher_s *voucher_t;
  57 #endif
  58
  59 /*!
  60  * @function voucher_adopt
  61  *
  62  * @abstract
  63  * Adopt the specified voucher on the current thread and return the voucher
  64  * that had been adopted previously.
  65  *
  66  * @discussion
  67  * Adopted vouchers are automatically carried forward by the system to other
  68  * threads and processes (across IPC).
  69  *
  70  * Consumes a reference to the specified voucher.
  71  * Returns a reference to the previous voucher.
  72  *
  73  * @param voucher
  74  * The voucher object to adopt on the current thread.
  75  *
  76  * @result
  77  * The previously adopted voucher object.
  78  */
  79 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
  80 OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT_NEEDS_RELEASE
  81 OS_NOTHROW
  82 voucher_t
  83 voucher_adopt(voucher_t voucher OS_OBJECT_CONSUMED);
  84
  85 /*!
  86  * @function voucher_copy
  87  *
  88  * @abstract
  89  * Returns a reference to the voucher that had been adopted previously on the
  90  * current thread (or carried forward by the system).
  91  *
  92  * @result
  93  * The currently adopted voucher object.
  94  */
  95 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
  96 OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
  97 voucher_t
  98 voucher_copy(void);
  99
 100 /*!
 101  * @function voucher_copy_without_importance
 102  *
 103  * @abstract
 104  * Returns a reference to a voucher object with all the properties of the
 105  * voucher that had been adopted previously on the current thread, but
 106  * without the importance properties that are frequently attached to vouchers
 107  * carried with IPC requests. Importance properties may elevate the scheduling
 108  * of threads that adopt or retain the voucher while they service the request.
 109  * See xpc_transaction_begin(3) for further details on importance.
 110  *
 111  * @result
 112  * A copy of the currently adopted voucher object, with importance removed.
 113  */
 114 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 115 OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
 116 voucher_t
 117 voucher_copy_without_importance(void);
 118
 119 /*!
 120  * @function voucher_replace_default_voucher
 121  *
 122  * @abstract
 123  * Replace process attributes of default voucher (used for IPC by this process
 124  * when no voucher is adopted on the sending thread) with the process attributes
 125  * of the voucher adopted on the current thread.
 126  *
 127  * @discussion
 128  * This allows a daemon to indicate from the context of an incoming IPC request
 129  * that all future outgoing IPC from the process should be marked as acting
 130  * "on behalf of" the sending process of the current IPC request (as long as the
 131  * thread sending that outgoing IPC is not itself in the direct context of an
 132  * IPC request, i.e. no voucher is adopted).
 133  *
 134  * If no voucher is adopted on the current thread or the current voucher does
 135  * not contain any process attributes, the default voucher is reset to the
 136  * default process attributes for the current process.
 137  *
 138  * CAUTION: Do NOT use this SPI without contacting the Darwin Runtime team.
 139  */
 140 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 141 OS_VOUCHER_EXPORT OS_NOTHROW
 142 void
 143 voucher_replace_default_voucher(void);
 144
 145 /*!
 146  * @function voucher_decrement_importance_count4CF
 147  *
 148  * @abstract
 149  * Decrement external importance count of the mach voucher in the specified
 150  * voucher object.
 151  *
 152  * @discussion
 153  * This is only intended for use by CoreFoundation to explicitly manage the
 154  * App Nap state of an application following receiption of a de-nap IPC message.
 155  *
 156  * CAUTION: Do NOT use this SPI without contacting the Darwin Runtime team.
 157  */
 158 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 159 OS_VOUCHER_EXPORT OS_NOTHROW
 160 void
 161 voucher_decrement_importance_count4CF(voucher_t voucher);
 162
 163 /*!
 164  * @group Voucher dispatch block SPI
 165  */
 166
 167 #ifndef __DISPATCH_BUILDING_DISPATCH__
 168 #include <dispatch/dispatch.h>
 169 #endif /* !__DISPATCH_BUILDING_DISPATCH__ */
 170
 171 /*!
 172  * @typedef dispatch_block_flags_t
 173  * SPI Flags to pass to the dispatch_block_create* functions.
 174  *
 175  * @const DISPATCH_BLOCK_NO_VOUCHER
 176  * Flag indicating that a dispatch block object should not be assigned a voucher
 177  * object. If invoked directly, the block object will be executed with the
 178  * voucher adopted on the calling thread. If the block object is submitted to a
 179  * queue, this replaces the default behavior of associating the submitted block
 180  * instance with the voucher adopted at the time of submission.
 181  * This flag is ignored if a specific voucher object is assigned with the
 182  * dispatch_block_create_with_voucher* functions, and is equivalent to passing
 183  * the NULL voucher to these functions.
 184  */
 185 #define DISPATCH_BLOCK_NO_VOUCHER (0x40)
 186
 187 /*!
 188  * @function dispatch_block_create_with_voucher
 189  *
 190  * @abstract
 191  * Create a new dispatch block object on the heap from an existing block and
 192  * the given flags, and assign it the specified voucher object.
 193  *
 194  * @discussion
 195  * The provided block is Block_copy'ed to the heap, it and the specified voucher
 196  * object are retained by the newly created dispatch block object.
 197  *
 198  * The returned dispatch block object is intended to be submitted to a dispatch
 199  * queue with dispatch_async() and related functions, but may also be invoked
 200  * directly. Both operations can be performed an arbitrary number of times but
 201  * only the first completed execution of a dispatch block object can be waited
 202  * on with dispatch_block_wait() or observed with dispatch_block_notify().
 203  *
 204  * The returned dispatch block will be executed with the specified voucher
 205  * adopted for the duration of the block body. If the NULL voucher is passed,
 206  * the block will be executed with the voucher adopted on the calling thread, or
 207  * with no voucher if the DISPATCH_BLOCK_DETACHED flag was also provided.
 208  *
 209  * If the returned dispatch block object is submitted to a dispatch queue, the
 210  * submitted block instance will be associated with the QOS class current at the
 211  * time of submission, unless one of the following flags assigned a specific QOS
 212  * class (or no QOS class) at the time of block creation:
 213  *  - DISPATCH_BLOCK_ASSIGN_CURRENT
 214  *  - DISPATCH_BLOCK_NO_QOS_CLASS
 215  *  - DISPATCH_BLOCK_DETACHED
 216  * The QOS class the block object will be executed with also depends on the QOS
 217  * class assigned to the queue and which of the following flags was specified or
 218  * defaulted to:
 219  *  - DISPATCH_BLOCK_INHERIT_QOS_CLASS (default for asynchronous execution)
 220  *  - DISPATCH_BLOCK_ENFORCE_QOS_CLASS (default for synchronous execution)
 221  * See description of dispatch_block_flags_t for details.
 222  *
 223  * If the returned dispatch block object is submitted directly to a serial queue
 224  * and is configured to execute with a specific QOS class, the system will make
 225  * a best effort to apply the necessary QOS overrides to ensure that blocks
 226  * submitted earlier to the serial queue are executed at that same QOS class or
 227  * higher.
 228  *
 229  * @param flags
 230  * Configuration flags for the block object.
 231  * Passing a value that is not a bitwise OR of flags from dispatch_block_flags_t
 232  * results in NULL being returned.
 233  *
 234  * @param voucher
 235  * A voucher object or NULL. Passing NULL is equivalent to specifying the
 236  * DISPATCH_BLOCK_NO_VOUCHER flag.
 237  *
 238  * @param block
 239  * The block to create the dispatch block object from.
 240  *
 241  * @result
 242  * The newly created dispatch block object, or NULL.
 243  * When not building with Objective-C ARC, must be released with a -[release]
 244  * message or the Block_release() function.
 245  */
 246 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
 247 DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_RETURNS_RETAINED_BLOCK
 248 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 249 dispatch_block_t
 250 dispatch_block_create_with_voucher(dispatch_block_flags_t flags,
 251                 voucher_t voucher, dispatch_block_t block);
 252
 253 /*!
 254  * @function dispatch_block_create_with_voucher_and_qos_class
 255  *
 256  * @abstract
 257  * Create a new dispatch block object on the heap from an existing block and
 258  * the given flags, and assign it the specified voucher object, QOS class and
 259  * relative priority.
 260  *
 261  * @discussion
 262  * The provided block is Block_copy'ed to the heap, it and the specified voucher
 263  * object are retained by the newly created dispatch block object.
 264  *
 265  * The returned dispatch block object is intended to be submitted to a dispatch
 266  * queue with dispatch_async() and related functions, but may also be invoked
 267  * directly. Both operations can be performed an arbitrary number of times but
 268  * only the first completed execution of a dispatch block object can be waited
 269  * on with dispatch_block_wait() or observed with dispatch_block_notify().
 270  *
 271  * The returned dispatch block will be executed with the specified voucher
 272  * adopted for the duration of the block body. If the NULL voucher is passed,
 273  * the block will be executed with the voucher adopted on the calling thread, or
 274  * with no voucher if the DISPATCH_BLOCK_DETACHED flag was also provided.
 275  *
 276  * If invoked directly, the returned dispatch block object will be executed with
 277  * the assigned QOS class as long as that does not result in a lower QOS class
 278  * than what is current on the calling thread.
 279  *
 280  * If the returned dispatch block object is submitted to a dispatch queue, the
 281  * QOS class it will be executed with depends on the QOS class assigned to the
 282  * block, the QOS class assigned to the queue and which of the following flags
 283  * was specified or defaulted to:
 284  *  - DISPATCH_BLOCK_INHERIT_QOS_CLASS: default for asynchronous execution
 285  *  - DISPATCH_BLOCK_ENFORCE_QOS_CLASS: default for synchronous execution
 286  * See description of dispatch_block_flags_t for details.
 287  *
 288  * If the returned dispatch block object is submitted directly to a serial queue
 289  * and is configured to execute with a specific QOS class, the system will make
 290  * a best effort to apply the necessary QOS overrides to ensure that blocks
 291  * submitted earlier to the serial queue are executed at that same QOS class or
 292  * higher.
 293  *
 294  * @param flags
 295  * Configuration flags for the block object.
 296  * Passing a value that is not a bitwise OR of flags from dispatch_block_flags_t
 297  * results in NULL being returned.
 298  *
 299  * @param voucher
 300  * A voucher object or NULL. Passing NULL is equivalent to specifying the
 301  * DISPATCH_BLOCK_NO_VOUCHER flag.
 302  *
 303  * @param qos_class
 304  * A QOS class value:
 305  *  - QOS_CLASS_USER_INTERACTIVE
 306  *  - QOS_CLASS_USER_INITIATED
 307  *  - QOS_CLASS_DEFAULT
 308  *  - QOS_CLASS_UTILITY
 309  *  - QOS_CLASS_BACKGROUND
 310  *  - QOS_CLASS_UNSPECIFIED
 311  * Passing QOS_CLASS_UNSPECIFIED is equivalent to specifying the
 312  * DISPATCH_BLOCK_NO_QOS_CLASS flag. Passing any other value results in NULL
 313  * being returned.
 314  *
 315  * @param relative_priority
 316  * A relative priority within the QOS class. This value is a negative
 317  * offset from the maximum supported scheduler priority for the given class.
 318  * Passing a value greater than zero or less than QOS_MIN_RELATIVE_PRIORITY
 319  * results in NULL being returned.
 320  *
 321  * @param block
 322  * The block to create the dispatch block object from.
 323  *
 324  * @result
 325  * The newly created dispatch block object, or NULL.
 326  * When not building with Objective-C ARC, must be released with a -[release]
 327  * message or the Block_release() function.
 328  */
 329 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
 330 DISPATCH_EXPORT DISPATCH_NONNULL5 DISPATCH_RETURNS_RETAINED_BLOCK
 331 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 332 dispatch_block_t
 333 dispatch_block_create_with_voucher_and_qos_class(dispatch_block_flags_t flags,
 334                 voucher_t voucher, dispatch_qos_class_t qos_class,
 335                 int relative_priority, dispatch_block_t block);
 336
 337 /*!
 338  * @group Voucher dispatch queue SPI
 339  */
 340
 341 /*!
 342  * @function dispatch_queue_create_with_accounting_override_voucher
 343  *
 344  * @abstract
 345  * Creates a new dispatch queue with an accounting override voucher created
 346  * from the specified voucher.
 347  *
 348  * @discussion
 349  * See dispatch_queue_create() headerdoc for generic details on queue creation.
 350  *
 351  * The resource accounting attributes of the specified voucher are extracted
 352  * and used to create an accounting override voucher for the new queue.
 353  *
 354  * Every block executed on the returned queue will initially have this override
 355  * voucher adopted, any voucher automatically associated with or explicitly
 356  * assigned to the block will NOT be used and released immediately before block
 357  * execution starts.
 358  *
 359  * The accounting override voucher will be automatically propagated to any
 360  * asynchronous work generated from the queue following standard voucher
 361  * propagation rules.
 362  *
 363  * NOTE: this SPI should only be used in special circumstances when a subsystem
 364  * has complete control over all workitems submitted to a queue (e.g. no client
 365  * block is ever submitted to the queue) and if and only if such queues have a
 366  * one-to-one mapping with resource accounting identities.
 367  *
 368  * CAUTION: use of this SPI represents a potential voucher propagation hole. It
 369  * is the responsibility of the caller to ensure that any callbacks into client
 370  * code from the queue have the correct client voucher applied (rather than the
 371  * automatically propagated accounting override voucher), e.g. by use of the
 372  * dispatch_block_create() API to capture client state at the time the callback
 373  * is registered.
 374  *
 375  * @param label
 376  * A string label to attach to the queue.
 377  * This parameter is optional and may be NULL.
 378  *
 379  * @param attr
 380  * DISPATCH_QUEUE_SERIAL, DISPATCH_QUEUE_CONCURRENT, or the result of a call to
 381  * the function dispatch_queue_attr_make_with_qos_class().
 382  *
 383  * @param voucher
 384  * A voucher whose resource accounting attributes are used to create the
 385  * accounting override voucher attached to the queue.
 386  *
 387  * @result
 388  * The newly created dispatch queue.
 389  */
 390 __OSX_AVAILABLE_STARTING(__MAC_10_11,__IPHONE_9_0)
 391 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 392 DISPATCH_NOTHROW
 393 dispatch_queue_t
 394 dispatch_queue_create_with_accounting_override_voucher(const char *label,
 395         dispatch_queue_attr_t attr, voucher_t voucher);
 396
 397 /*!
 398  * @group Voucher Mach SPI
 399  * SPI intended for clients that need to interact with mach messages or mach
 400  * voucher ports directly.
 401  */
 402
 403 #include <mach/mach.h>
 404
 405 /*!
 406  * @function voucher_create_with_mach_msg
 407  *
 408  * @abstract
 409  * Creates a new voucher object from a mach message carrying a mach voucher port
 410  *
 411  * @discussion
 412  * Ownership of the mach voucher port in the message is transfered to the new
 413  * voucher object and the message header mach voucher field is cleared.
 414  *
 415  * @param msg
 416  * The mach message to query.
 417  *
 418  * @result
 419  * The newly created voucher object or NULL if the message was not carrying a
 420  * mach voucher.
 421  */
 422 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 423 OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
 424 voucher_t
 425 voucher_create_with_mach_msg(mach_msg_header_t *msg);
 426
 427 __END_DECLS
 428
 429 #endif // __OS_VOUCHER_PRIVATE__
 430
 431 #if (OS_VOUCHER_ACTIVITY_SPI || OS_VOUCHER_ACTIVITY_BUFFER_SPI) && \
 432                 !defined(__DISPATCH_BUILDING_DISPATCH__) && \
 433                 !defined(__OS_VOUCHER_ACTIVITY_PRIVATE__)
 434 #include <os/voucher_activity_private.h>
 435 #endif