/* * Copyright (c) 2013-2014 Apple Inc. All rights reserved. * * @APPLE_APACHE_LICENSE_HEADER_START@ * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * * @APPLE_APACHE_LICENSE_HEADER_END@ */ #ifndef __OS_VOUCHER_PRIVATE__ #define __OS_VOUCHER_PRIVATE__ #ifndef __linux__ #include <os/base.h> #include <os/availability.h> #endif #if __has_include(<mach/mach.h>) #include <os/object.h> #include <mach/mach.h> #endif #if __has_include(<bank/bank_types.h>) #include <bank/bank_types.h> #endif #if __has_include(<sys/persona.h>) #include <sys/persona.h> #endif #ifndef __DISPATCH_BUILDING_DISPATCH__ #include <dispatch/dispatch.h> #endif /* !__DISPATCH_BUILDING_DISPATCH__ */ #define OS_VOUCHER_SPI_VERSION 20150630 #if OS_VOUCHER_WEAK_IMPORT #define OS_VOUCHER_EXPORT OS_EXPORT OS_WEAK_IMPORT #else #define OS_VOUCHER_EXPORT OS_EXPORT #endif DISPATCH_ASSUME_NONNULL_BEGIN __BEGIN_DECLS /*! * @group Voucher Transport SPI * SPI intended for clients that need to transport vouchers. */ /*! * @typedef voucher_t * * @abstract * Vouchers are immutable sets of key/value attributes that can be adopted on a * thread in the current process or sent to another process. * * @discussion * Voucher objects are os_objects (c.f. <os/object.h>). They are memory-managed * with the os_retain()/os_release() functions or -[retain]/-[release] methods. */ OS_OBJECT_DECL_CLASS(voucher); /*! * @const VOUCHER_NULL * Represents the empty base voucher with no attributes. */ #define VOUCHER_NULL ((voucher_t)0) /*! * @const VOUCHER_INVALID * Represents an invalid voucher */ #define VOUCHER_INVALID ((voucher_t)-1) /*! * @function voucher_adopt * * @abstract * Adopt the specified voucher on the current thread and return the voucher * that had been adopted previously. * * @discussion * Adopted vouchers are automatically carried forward by the system to other * threads and processes (across IPC). * * Consumes a reference to the specified voucher. * Returns a reference to the previous voucher. * * @param voucher * The voucher object to adopt on the current thread. * * @result * The previously adopted voucher object. */ API_AVAILABLE(macos(10.10), ios(8.0)) OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT_NEEDS_RELEASE OS_NOTHROW voucher_t _Nullable voucher_adopt(voucher_t _Nullable voucher OS_OBJECT_CONSUMED); /*! * @function voucher_copy * * @abstract * Returns a reference to the voucher that had been adopted previously on the * current thread (or carried forward by the system). * * @result * The currently adopted voucher object. */ API_AVAILABLE(macos(10.10), ios(8.0)) OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW voucher_t _Nullable voucher_copy(void); /*! * @function voucher_copy_without_importance * * @abstract * Returns a reference to a voucher object with all the properties of the * voucher that had been adopted previously on the current thread, but * without the importance properties that are frequently attached to vouchers * carried with IPC requests. Importance properties may elevate the scheduling * of threads that adopt or retain the voucher while they service the request. * See xpc_transaction_begin(3) for further details on importance. * * @result * A copy of the currently adopted voucher object, with importance removed. */ API_AVAILABLE(macos(10.10), ios(8.0)) OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW voucher_t _Nullable voucher_copy_without_importance(void); /*! * @function voucher_replace_default_voucher * * @abstract * Replace process attributes of default voucher (used for IPC by this process * when no voucher is adopted on the sending thread) with the process attributes * of the voucher adopted on the current thread. * * @discussion * This allows a daemon to indicate from the context of an incoming IPC request * that all future outgoing IPC from the process should be marked as acting * "on behalf of" the sending process of the current IPC request (as long as the * thread sending that outgoing IPC is not itself in the direct context of an * IPC request, i.e. no voucher is adopted). * * If no voucher is adopted on the current thread or the current voucher does * not contain any process attributes, the default voucher is reset to the * default process attributes for the current process. * * CAUTION: Do NOT use this SPI without contacting the Darwin Runtime team. */ API_AVAILABLE(macos(10.10), ios(8.0)) OS_VOUCHER_EXPORT OS_NOTHROW void voucher_replace_default_voucher(void); /*! * @function voucher_decrement_importance_count4CF * * @abstract * Decrement external importance count of the mach voucher in the specified * voucher object. * * @discussion * This is only intended for use by CoreFoundation to explicitly manage the * App Nap state of an application following reception of a de-nap IPC message. * * CAUTION: Do NOT use this SPI without contacting the Darwin Runtime team. */ API_AVAILABLE(macos(10.10), ios(8.0)) OS_VOUCHER_EXPORT OS_NOTHROW void voucher_decrement_importance_count4CF(voucher_t _Nullable voucher); /*! * @group Voucher dispatch block SPI */ /*! * @typedef dispatch_block_flags_t * SPI Flags to pass to the dispatch_block_create* functions. * * @const DISPATCH_BLOCK_NO_VOUCHER * Flag indicating that a dispatch block object should not be assigned a voucher * object. If invoked directly, the block object will be executed with the * voucher adopted on the calling thread. If the block object is submitted to a * queue, this replaces the default behavior of associating the submitted block * instance with the voucher adopted at the time of submission. * This flag is ignored if a specific voucher object is assigned with the * dispatch_block_create_with_voucher* functions, and is equivalent to passing * the NULL voucher to these functions. * * @const DISPATCH_BLOCK_IF_LAST_RESET_QUEUE_QOS_OVERRIDE * Flag indicating that this dispatch block object should try to reset the * recorded maximum QoS of all currently enqueued items on a serial dispatch * queue at the base of a queue hierarchy. * * This is only works if the queue becomes empty by dequeuing the block in * question, and then allows that block to enqueue more work on this hierarchy * without perpetuating QoS overrides resulting from items previously executed * on the hierarchy. * * A dispatch block object created with this flag set cannot be used with * dispatch_block_wait() or dispatch_block_cancel(). */ #define DISPATCH_BLOCK_NO_VOUCHER (0x40ul) #define DISPATCH_BLOCK_IF_LAST_RESET_QUEUE_QOS_OVERRIDE (0x80ul) /*! * @function dispatch_block_create_with_voucher * * @abstract * Create a new dispatch block object on the heap from an existing block and * the given flags, and assign it the specified voucher object. * * @discussion * The provided block is Block_copy'ed to the heap, it and the specified voucher * object are retained by the newly created dispatch block object. * * The returned dispatch block object is intended to be submitted to a dispatch * queue with dispatch_async() and related functions, but may also be invoked * directly. Both operations can be performed an arbitrary number of times but * only the first completed execution of a dispatch block object can be waited * on with dispatch_block_wait() or observed with dispatch_block_notify(). * * The returned dispatch block will be executed with the specified voucher * adopted for the duration of the block body. If the NULL voucher is passed, * the block will be executed with the voucher adopted on the calling thread, or * with no voucher if the DISPATCH_BLOCK_DETACHED flag was also provided. * * If the returned dispatch block object is submitted to a dispatch queue, the * submitted block instance will be associated with the QOS class current at the * time of submission, unless one of the following flags assigned a specific QOS * class (or no QOS class) at the time of block creation: * - DISPATCH_BLOCK_ASSIGN_CURRENT * - DISPATCH_BLOCK_NO_QOS_CLASS * - DISPATCH_BLOCK_DETACHED * The QOS class the block object will be executed with also depends on the QOS * class assigned to the queue and which of the following flags was specified or * defaulted to: * - DISPATCH_BLOCK_INHERIT_QOS_CLASS (default for asynchronous execution) * - DISPATCH_BLOCK_ENFORCE_QOS_CLASS (default for synchronous execution) * See description of dispatch_block_flags_t for details. * * If the returned dispatch block object is submitted directly to a serial queue * and is configured to execute with a specific QOS class, the system will make * a best effort to apply the necessary QOS overrides to ensure that blocks * submitted earlier to the serial queue are executed at that same QOS class or * higher. * * @param flags * Configuration flags for the block object. * Passing a value that is not a bitwise OR of flags from dispatch_block_flags_t * results in NULL being returned. * * @param voucher * A voucher object or NULL. Passing NULL is equivalent to specifying the * DISPATCH_BLOCK_NO_VOUCHER flag. * * @param block * The block to create the dispatch block object from. * * @result * The newly created dispatch block object, or NULL. * When not building with Objective-C ARC, must be released with a -[release] * message or the Block_release() function. */ API_AVAILABLE(macos(10.10), ios(8.0)) DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_RETURNS_RETAINED_BLOCK DISPATCH_WARN_RESULT DISPATCH_NOTHROW dispatch_block_t dispatch_block_create_with_voucher(dispatch_block_flags_t flags, voucher_t _Nullable voucher, dispatch_block_t block); /*! * @function dispatch_block_create_with_voucher_and_qos_class * * @abstract * Create a new dispatch block object on the heap from an existing block and * the given flags, and assign it the specified voucher object, QOS class and * relative priority. * * @discussion * The provided block is Block_copy'ed to the heap, it and the specified voucher * object are retained by the newly created dispatch block object. * * The returned dispatch block object is intended to be submitted to a dispatch * queue with dispatch_async() and related functions, but may also be invoked * directly. Both operations can be performed an arbitrary number of times but * only the first completed execution of a dispatch block object can be waited * on with dispatch_block_wait() or observed with dispatch_block_notify(). * * The returned dispatch block will be executed with the specified voucher * adopted for the duration of the block body. If the NULL voucher is passed, * the block will be executed with the voucher adopted on the calling thread, or * with no voucher if the DISPATCH_BLOCK_DETACHED flag was also provided. * * If invoked directly, the returned dispatch block object will be executed with * the assigned QOS class as long as that does not result in a lower QOS class * than what is current on the calling thread. * * If the returned dispatch block object is submitted to a dispatch queue, the * QOS class it will be executed with depends on the QOS class assigned to the * block, the QOS class assigned to the queue and which of the following flags * was specified or defaulted to: * - DISPATCH_BLOCK_INHERIT_QOS_CLASS: default for asynchronous execution * - DISPATCH_BLOCK_ENFORCE_QOS_CLASS: default for synchronous execution * See description of dispatch_block_flags_t for details. * * If the returned dispatch block object is submitted directly to a serial queue * and is configured to execute with a specific QOS class, the system will make * a best effort to apply the necessary QOS overrides to ensure that blocks * submitted earlier to the serial queue are executed at that same QOS class or * higher. * * @param flags * Configuration flags for the block object. * Passing a value that is not a bitwise OR of flags from dispatch_block_flags_t * results in NULL being returned. * * @param voucher * A voucher object or NULL. Passing NULL is equivalent to specifying the * DISPATCH_BLOCK_NO_VOUCHER flag. * * @param qos_class * A QOS class value: * - QOS_CLASS_USER_INTERACTIVE * - QOS_CLASS_USER_INITIATED * - QOS_CLASS_DEFAULT * - QOS_CLASS_UTILITY * - QOS_CLASS_BACKGROUND * - QOS_CLASS_UNSPECIFIED * Passing QOS_CLASS_UNSPECIFIED is equivalent to specifying the * DISPATCH_BLOCK_NO_QOS_CLASS flag. Passing any other value results in NULL * being returned. * * @param relative_priority * A relative priority within the QOS class. This value is a negative * offset from the maximum supported scheduler priority for the given class. * Passing a value greater than zero or less than QOS_MIN_RELATIVE_PRIORITY * results in NULL being returned. * * @param block * The block to create the dispatch block object from. * * @result * The newly created dispatch block object, or NULL. * When not building with Objective-C ARC, must be released with a -[release] * message or the Block_release() function. */ API_AVAILABLE(macos(10.10), ios(8.0)) DISPATCH_EXPORT DISPATCH_NONNULL5 DISPATCH_RETURNS_RETAINED_BLOCK DISPATCH_WARN_RESULT DISPATCH_NOTHROW dispatch_block_t dispatch_block_create_with_voucher_and_qos_class(dispatch_block_flags_t flags, voucher_t _Nullable voucher, dispatch_qos_class_t qos_class, int relative_priority, dispatch_block_t block); /*! * @group Voucher dispatch queue SPI */ /*! * @function dispatch_queue_create_with_accounting_override_voucher * * @abstract * Deprecated, do not use, will abort process if called. */ API_DEPRECATED("removed SPI", \ macos(10.11,10.12), ios(9.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)) DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW dispatch_queue_t dispatch_queue_create_with_accounting_override_voucher( const char *_Nullable label, dispatch_queue_attr_t _Nullable attr, voucher_t _Nullable voucher); #if __has_include(<mach/mach.h>) /*! * @group Voucher Mach SPI * SPI intended for clients that need to interact with mach messages or mach * voucher ports directly. */ /*! * @function voucher_create_with_mach_msg * * @abstract * Creates a new voucher object from a mach message carrying a mach voucher port * * @discussion * Ownership of the mach voucher port in the message is transfered to the new * voucher object and the message header mach voucher field is cleared. * * @param msg * The mach message to query. * * @result * The newly created voucher object or NULL if the message was not carrying a * mach voucher. */ API_AVAILABLE(macos(10.10), ios(8.0)) OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW voucher_t _Nullable voucher_create_with_mach_msg(mach_msg_header_t *msg); /*! * @group Voucher Persona SPI * SPI intended for clients that need to interact with personas. */ struct proc_persona_info; /*! * @function voucher_get_current_persona * * @abstract * Retrieve the persona identifier of the 'originator' process for the current * voucher. * * @discussion * Retrieve the persona identifier of the ’originator’ process possibly stored * in the PERSONA_TOKEN attribute of the currently adopted voucher. * * If the thread has not adopted a voucher, or the current voucher does not * contain a PERSONA_TOKEN attribute, this function returns the persona * identifier of the current process. * * If the process is not running under a persona, then this returns * PERSONA_ID_NONE. * * @result * The persona identifier of the 'originator' process for the current voucher, * or the persona identifier of the current process * or PERSONA_ID_NONE */ API_AVAILABLE(ios(9.2)) OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW uid_t voucher_get_current_persona(void); /*! * @function voucher_get_current_persona_originator_info * * @abstract * Retrieve the ’originator’ process persona info for the currently adopted * voucher. * * @discussion * If there is no currently adopted voucher, or no PERSONA_TOKEN attribute * in that voucher, this function fails. * * @param persona_info * The proc_persona_info structure to fill in case of success * * @result * 0 on success: currently adopted voucher has a PERSONA_TOKEN * -1 on failure: persona_info is untouched/uninitialized */ API_AVAILABLE(ios(9.2)) OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW OS_NONNULL1 int voucher_get_current_persona_originator_info( struct proc_persona_info *persona_info); /*! * @function voucher_get_current_persona_proximate_info * * @abstract * Retrieve the ’proximate’ process persona info for the currently adopted * voucher. * * @discussion * If there is no currently adopted voucher, or no PERSONA_TOKEN attribute * in that voucher, this function fails. * * @param persona_info * The proc_persona_info structure to fill in case of success * * @result * 0 on success: currently adopted voucher has a PERSONA_TOKEN * -1 on failure: persona_info is untouched/uninitialized */ API_AVAILABLE(ios(9.2)) OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW OS_NONNULL1 int voucher_get_current_persona_proximate_info( struct proc_persona_info *persona_info); #endif // __has_include(<mach/mach.h>) __END_DECLS DISPATCH_ASSUME_NONNULL_END #endif // __OS_VOUCHER_PRIVATE__ #if OS_VOUCHER_ACTIVITY_SPI #include "voucher_activity_private.h" #endif