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 20140425 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 54OS_OBJECT_DECL(voucher); 55#else 56typedef 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) 80OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT_NEEDS_RELEASE 81OS_NOTHROW 82voucher_t 83voucher_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) 96OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW 97voucher_t 98voucher_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) 115OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW 116voucher_t 117voucher_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) 141OS_VOUCHER_EXPORT OS_NOTHROW 142void 143voucher_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) 159OS_VOUCHER_EXPORT OS_NOTHROW 160void 161voucher_decrement_importance_count4CF(voucher_t voucher); 162 163/*! 164 * @group Dispatch block objects 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) 247DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_RETURNS_RETAINED_BLOCK 248DISPATCH_WARN_RESULT DISPATCH_NOTHROW 249dispatch_block_t 250dispatch_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) 330DISPATCH_EXPORT DISPATCH_NONNULL5 DISPATCH_RETURNS_RETAINED_BLOCK 331DISPATCH_WARN_RESULT DISPATCH_NOTHROW 332dispatch_block_t 333dispatch_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 Mach SPI 339 * SPI intended for clients that need to interact with mach messages or mach 340 * voucher ports directly. 341 */ 342 343#include <mach/mach.h> 344 345/*! 346 * @function voucher_create_with_mach_msg 347 * 348 * @abstract 349 * Creates a new voucher object from a mach message carrying a mach voucher port 350 * 351 * @discussion 352 * Ownership of the mach voucher port in the message is transfered to the new 353 * voucher object and the message header mach voucher field is cleared. 354 * 355 * @param msg 356 * The mach message to query. 357 * 358 * @result 359 * The newly created voucher object or NULL if the message was not carrying a 360 * mach voucher. 361 */ 362__OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0) 363OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW 364voucher_t 365voucher_create_with_mach_msg(mach_msg_header_t *msg); 366 367__END_DECLS 368 369#endif // __OS_VOUCHER_PRIVATE__ 370 371#if (OS_VOUCHER_ACTIVITY_SPI || OS_VOUCHER_ACTIVITY_BUFFER_SPI) && \ 372 !defined(__DISPATCH_BUILDING_DISPATCH__) && \ 373 !defined(__OS_VOUCHER_ACTIVITY_PRIVATE__) 374#include <os/voucher_activity_private.h> 375#endif 376