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