this repo has no description
Add os/log.h and os/activity.h headers
+1044
+571
src/libc/os/activity.h
+571
src/libc/os/activity.h
···
1
+
/*
2
+
* Copyright (c) 2013-2016 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 __OS_ACTIVITY_H__
25
+
#define __OS_ACTIVITY_H__
26
+
27
+
#include <os/object.h>
28
+
#include <stdint.h>
29
+
#include <stdbool.h>
30
+
#include <mach-o/loader.h>
31
+
32
+
__BEGIN_DECLS
33
+
34
+
#if ((defined(__IPHONE_OS_VERSION_MIN_REQUIRED) && __IPHONE_OS_VERSION_MIN_REQUIRED >= __IPHONE_10_0) \
35
+
|| (defined(__WATCH_OS_VERSION_MIN_REQUIRED) && __WATCH_OS_VERSION_MIN_REQUIRED >= __WATCHOS_3_0) \
36
+
|| (defined(__TV_OS_VERSION_MIN_REQUIRED) && __TV_OS_VERSION_MIN_REQUIRED >= __TVOS_10_0) \
37
+
|| (defined(__MAC_OS_X_VERSION_MIN_REQUIRED) && __MAC_OS_X_VERSION_MIN_REQUIRED >= __MAC_10_12))
38
+
#define OS_ACTIVITY_OBJECT_API 1
39
+
#else
40
+
#if OS_ACTIVITY_OBJECT_API
41
+
#error Please change your minimum OS requirements because OS_ACTIVITY_OBJECT_API is not available
42
+
#endif // OS_ACTIVITY_OBJECT_API
43
+
#define OS_ACTIVITY_OBJECT_API 0
44
+
#endif
45
+
46
+
extern void* __dso_handle;
47
+
48
+
#define OS_LOG_STRING(_var, _str) \
49
+
_Static_assert(__builtin_constant_p(_str), "formatters/labels/descriptions must be a constant string"); \
50
+
__attribute__((section("__TEXT,__oslogstring,cstring_literals"),internal_linkage)) static const char _var[] __asm(OS_STRINGIFY(OS_CONCAT(LOSACTIVITY_, __COUNTER__))) = _str
51
+
52
+
/*!
53
+
* @typedef os_breadcrumb_t
54
+
* An opaque value for the breadcrumb ID.
55
+
*/
56
+
__API_DEPRECATED("No longer supported", macosx(10.10, 10.12), ios(8.0, 10.0), watchos(2.0, 3.0), tvos(9.0, 10.0))
57
+
typedef uint32_t os_breadcrumb_t;
58
+
59
+
#define OS_ACTIVITY_NULL 0
60
+
61
+
/*!
62
+
* @enum os_activity_flag_t
63
+
*
64
+
* @discussion
65
+
* Support flags for os_activity_create or os_activity_start.
66
+
*
67
+
* @constant OS_ACTIVITY_FLAG_DEFAULT
68
+
* Use the default flags.
69
+
*
70
+
* @constant OS_ACTIVITY_FLAG_DETACHED
71
+
* Detach the newly created activity from the provided activity (if any). If passed in conjunction
72
+
* with an exiting activity, the activity will only note what activity "created" the new one, but
73
+
* will make the new activity a top level activity. This allows users to see what activity triggered
74
+
* work without actually relating the activities.
75
+
*
76
+
* @constant OS_ACTIVITY_FLAG_IF_NONE_PRESENT
77
+
* Will only create a new activity if none present. If an activity ID is already present, a new object
78
+
* will be returned with the same activity ID underneath.
79
+
*/
80
+
OS_ENUM(os_activity_flag, uint32_t,
81
+
OS_ACTIVITY_FLAG_DEFAULT = 0,
82
+
OS_ACTIVITY_FLAG_DETACHED = 0x1,
83
+
OS_ACTIVITY_FLAG_IF_NONE_PRESENT = 0x2
84
+
);
85
+
86
+
#if OS_ACTIVITY_OBJECT_API
87
+
88
+
#define OS_ACTIVITY_NULL NULL
89
+
90
+
/*!
91
+
* @typedef os_activity_t
92
+
* An opaque activity object.
93
+
*/
94
+
__API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0))
95
+
#if OS_OBJECT_USE_OBJC
96
+
OS_OBJECT_DECL(os_activity);
97
+
#else
98
+
typedef struct os_activity_s *os_activity_t;
99
+
#endif /* OS_OBJECT_USE_OBJC */
100
+
101
+
/*!
102
+
* @const OS_ACTIVITY_NONE
103
+
*
104
+
* @discussion
105
+
* Create activity with no current traits, this is the equivalent of a
106
+
* detached activity.
107
+
*/
108
+
#define OS_ACTIVITY_NONE OS_OBJECT_GLOBAL_OBJECT(os_activity_t, _os_activity_none)
109
+
__API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0))
110
+
OS_EXPORT
111
+
const struct os_activity_s _os_activity_none;
112
+
113
+
/*!
114
+
* @const OS_ACTIVITY_CURRENT
115
+
*
116
+
* @discussion
117
+
* Create activity and links to the current activity if one is present.
118
+
* If no activity is present it is treated as if it is detached.
119
+
*/
120
+
#define OS_ACTIVITY_CURRENT OS_OBJECT_GLOBAL_OBJECT(os_activity_t, _os_activity_current)
121
+
__API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0))
122
+
OS_EXPORT
123
+
const struct os_activity_s _os_activity_current;
124
+
125
+
#else // !OS_ACTIVITY_OBJECT_API
126
+
127
+
#define OS_ACTIVITY_NULL 0
128
+
129
+
/*!
130
+
* @typedef os_activity_t
131
+
* An opaque activity identifier.
132
+
*/
133
+
__API_AVAILABLE(macosx(10.10), ios(8.0), watchos(2.0), tvos(9.0))
134
+
typedef uint64_t os_activity_t;
135
+
136
+
#endif // OS_ACTIVITY_OBJECT_API
137
+
138
+
/*!
139
+
* @typedef os_activity_id_t
140
+
* An value representing the activity ID assigned to an newly created activity.
141
+
*/
142
+
__API_AVAILABLE(macosx(10.10), ios(8.0), watchos(2.0), tvos(9.0))
143
+
typedef uint64_t os_activity_id_t;
144
+
145
+
#if !defined(__TRACE_BUILDING_TRACE__)
146
+
/*!
147
+
* @typedef os_activity_scope_state_t
148
+
* Structure that is populated by os_activity_scope_enter and restored using
149
+
* os_activity_scope_leave.
150
+
*/
151
+
__API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0))
152
+
typedef struct os_activity_scope_state_s {
153
+
uint64_t opaque[2];
154
+
} *os_activity_scope_state_t;
155
+
#else
156
+
typedef struct os_activity_scope_state_s *os_activity_scope_state_t;
157
+
#endif
158
+
159
+
#pragma mark - Internal support functions
160
+
161
+
#if OS_ACTIVITY_OBJECT_API
162
+
__API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0))
163
+
OS_EXPORT OS_NOTHROW OS_WARN_RESULT_NEEDS_RELEASE OS_NOT_TAIL_CALLED OS_OBJECT_RETURNS_RETAINED
164
+
os_activity_t
165
+
_os_activity_create(void *dso, const char *description, os_activity_t activity, os_activity_flag_t flags);
166
+
#endif
167
+
168
+
/*!
169
+
* @function _os_activity_label_useraction
170
+
*
171
+
* @abstract
172
+
* Internal function for use by os_activity_label_useraction. Do not use directly.
173
+
*/
174
+
__API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0))
175
+
OS_EXPORT OS_NOTHROW OS_NOT_TAIL_CALLED
176
+
void
177
+
_os_activity_label_useraction(void *dso, const char *name);
178
+
179
+
/*!
180
+
* @function _os_activity_initiate
181
+
*
182
+
* @abstract
183
+
* Do not use directly because your description will not be preserved.
184
+
*/
185
+
__API_AVAILABLE(macosx(10.10), ios(8.0), watchos(2.0), tvos(9.0))
186
+
OS_EXPORT OS_NOTHROW OS_NOT_TAIL_CALLED
187
+
void
188
+
_os_activity_initiate(void *dso, const char *description, os_activity_flag_t flags, os_block_t activity_block OS_NOESCAPE);
189
+
190
+
/*!
191
+
* @function _os_activity_initiate_f
192
+
*
193
+
* @abstract
194
+
* Do not use directly because your description will not be preserved.
195
+
*/
196
+
__API_AVAILABLE(macosx(10.10), ios(8.0), watchos(2.0), tvos(9.0))
197
+
OS_EXPORT OS_NOTHROW OS_NOT_TAIL_CALLED
198
+
void
199
+
_os_activity_initiate_f(void *dso, const char *description, os_activity_flag_t flags, void *context, os_function_t function);
200
+
201
+
#pragma mark - Internal deprecated function support
202
+
203
+
/*!
204
+
* @function _os_activity_set_breadcrumb
205
+
*
206
+
* @abstract
207
+
* Internal function for setting breadcrumb. Do not use directly.
208
+
*/
209
+
__API_DEPRECATED_WITH_REPLACEMENT("os_activity_label_useraction", macosx(10.10, 10.12), ios(8.0, 10.0), watchos(2.0, 3.0), tvos(9.0, 10.0))
210
+
OS_EXPORT OS_NOTHROW OS_NOT_TAIL_CALLED
211
+
void
212
+
_os_activity_set_breadcrumb(void *dso, const char *name);
213
+
214
+
/*!
215
+
* @function _os_activity_start
216
+
*
217
+
* @abstract
218
+
* Internal function for activity start, do not use directly will not preserve
219
+
* description.
220
+
*/
221
+
__API_DEPRECATED("use combination of os_activity_create and os_activity_apply/os_activity_scope", macosx(10.10, 10.12), ios(8.0, 10.0), watchos(2.0, 3.0), tvos(9.0, 10.0))
222
+
OS_EXPORT OS_NOTHROW OS_WARN_RESULT OS_NOT_TAIL_CALLED
223
+
os_activity_t
224
+
_os_activity_start(void *dso, const char *description, os_activity_flag_t flags);
225
+
226
+
#pragma mark - activity related
227
+
228
+
/*!
229
+
* @function os_activity_initiate
230
+
*
231
+
* @abstract
232
+
* Synchronously initiates an activity using provided block.
233
+
*
234
+
* @discussion
235
+
* Synchronously initiates an activity using the provided block and creates
236
+
* a tracing buffer as appropriate. All new activities are created as a
237
+
* subactivity of an existing activity on the current thread.
238
+
*
239
+
* os_activity_initiate("indexing database", OS_ACTIVITY_FLAG_DEFAULT, ^(void) {
240
+
* // either do work directly or issue work asynchronously
241
+
* });
242
+
*
243
+
* @param description
244
+
* A constant string describing the activity, e.g., "performClick" or
245
+
* "menuSelection".
246
+
*
247
+
* @param flags
248
+
* Flags to be used when initiating the activity, typically OS_ACTIVITY_FLAG_DEFAULT.
249
+
*
250
+
* @param activity_block
251
+
* The block to execute a given activity
252
+
*/
253
+
#define os_activity_initiate(description, flags, activity_block) __extension__({ \
254
+
OS_LOG_STRING(__description, description); \
255
+
_os_activity_initiate(&__dso_handle, __description, flags, activity_block); \
256
+
})
257
+
258
+
/*!
259
+
* @function os_activity_initiate_f
260
+
*
261
+
* @abstract
262
+
* Synchronously initiates an activity using the provided function.
263
+
*
264
+
* @discussion
265
+
* Synchronously initiates an activity using the provided function and creates
266
+
* a tracing buffer as appropriate. All new activities are created as a
267
+
* subactivity of an existing activity on the current thread.
268
+
*
269
+
* os_activity_initiate_f("indexing database", OS_ACTIVITY_FLAG_DEFAULT, context, function);
270
+
*
271
+
* @param description
272
+
* A constant string describing the activity, e.g., "performClick" or
273
+
* "menuSelection".
274
+
*
275
+
* @param flags
276
+
* Flags to be used when initiating the activity, typically OS_ACTIVITY_FLAG_DEFAULT.
277
+
*
278
+
* @param context
279
+
* An optional context that will be supplied to the activity function.
280
+
*
281
+
* @param activity_func
282
+
* The function to execute for the new activity.
283
+
*/
284
+
#define os_activity_initiate_f(description, flags, context, function) __extension__({ \
285
+
OS_LOG_STRING(__description, description); \
286
+
_os_activity_initiate_f(&__dso_handle, __description, flags, context, function); \
287
+
})
288
+
289
+
#if OS_ACTIVITY_OBJECT_API
290
+
/*!
291
+
* @function os_activity_create
292
+
*
293
+
* @abstract
294
+
* Creates an os_activity_t object which can be passed to os_activity_apply function.
295
+
*
296
+
* @discussion
297
+
* Creates an os_activity_t object which can be passed to os_activity_apply function.
298
+
*
299
+
* @param description
300
+
* Pass a description for the activity. The description must be a constant string
301
+
* within the calling executable or library.
302
+
*
303
+
* @param parent_activity
304
+
* Depending on flags will link the newly created activity to the value passed or
305
+
* note where the activity was created. Possible activities include: OS_ACTIVITY_NONE,
306
+
* OS_ACTIVITY_CURRENT or any existing os_activity_t object created using os_activity_create.
307
+
*
308
+
* @param flags
309
+
* A valid os_activity_flag_t which will determine behavior of the newly created activity.
310
+
*
311
+
* @result
312
+
* Returns an os_activity_t object which can be used with os_activity_apply.
313
+
*/
314
+
#define os_activity_create(description, parent_activity, flags) __extension__({ \
315
+
OS_LOG_STRING(__description, description); \
316
+
os_activity_t __activity = _os_activity_create(&__dso_handle, __description, parent_activity, flags); \
317
+
__activity; \
318
+
})
319
+
320
+
/*!
321
+
* @function os_activity_apply
322
+
*
323
+
* @abstract
324
+
* Execute a block using a given activity object.
325
+
*
326
+
* @discussion
327
+
* Execute a block using a given activity object.
328
+
*
329
+
* @param activity
330
+
* There are global objects available which include: OS_ACTIVITY_NONE, OS_ACTIVITY_CURRENT
331
+
* or an existing os_activity_t object.
332
+
*
333
+
* @param block
334
+
* Pass the block to be executed within the context of the given activity.
335
+
*/
336
+
__API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0))
337
+
OS_EXPORT OS_NOTHROW
338
+
void
339
+
os_activity_apply(os_activity_t activity, os_block_t block OS_NOESCAPE);
340
+
341
+
/*!
342
+
* @function os_activity_apply_f
343
+
*
344
+
* @abstract
345
+
* Execute a given function with a provided activity.
346
+
*
347
+
* @discussion
348
+
* Execute a given function with a provided activity.
349
+
*
350
+
* @param activity
351
+
* There are global objects available which include: OS_ACTIVITY_NONE, OS_ACTIVITY_CURRENT
352
+
* or an existing os_activity_t object.
353
+
*
354
+
* @param context
355
+
* Context to pass to the function which may be NULL.
356
+
*
357
+
* @param function
358
+
* Pass the function to be executed within the context of the given activity.
359
+
*/
360
+
__API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0))
361
+
OS_EXPORT OS_NOTHROW
362
+
void
363
+
os_activity_apply_f(os_activity_t activity, void *context, os_function_t function);
364
+
365
+
/*!
366
+
* @function os_activity_scope_enter
367
+
*
368
+
* @abstract
369
+
* Will change the current execution context to use the provided activity.
370
+
*
371
+
* @discussion
372
+
* Will change the current execution context to use the provided activity. An activity
373
+
* can be created and then applied to the current scope by doing:
374
+
*
375
+
* struct os_activity_scope_state_s state;
376
+
* os_activity_t activity = os_activity_create("my new activity", 0);
377
+
* os_activity_scope_enter(activity, &state);
378
+
* ... do some work ...
379
+
* os_activity_scope_leave(&state);
380
+
*
381
+
* To auto-cleanup state call:
382
+
*
383
+
* os_activity_scope(activity);
384
+
*
385
+
* @param activity
386
+
* Pass a valid activity created with os_activity_create or any global object.
387
+
*
388
+
* @param state
389
+
* A stack-based struct os_activity_scope_state_s to store the state.
390
+
*/
391
+
__API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0))
392
+
OS_EXPORT OS_NOTHROW
393
+
void
394
+
os_activity_scope_enter(os_activity_t activity, os_activity_scope_state_t state);
395
+
396
+
/*!
397
+
* @function os_activity_scope_leave
398
+
*
399
+
* @abstract
400
+
* Will pop state up to the state provided.
401
+
*
402
+
* @discussion
403
+
* Will leave scope using the state provided. If state is not present an error will be
404
+
* generated.
405
+
*
406
+
* @param state
407
+
* Must be a valid value filled by os_activity_scope_enter call.
408
+
*/
409
+
__API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0))
410
+
OS_EXPORT OS_NOTHROW
411
+
void
412
+
os_activity_scope_leave(os_activity_scope_state_t state);
413
+
414
+
#if defined(__GNUC__)
415
+
#define _os_activity_scope(var, activity) \
416
+
struct os_activity_scope_state_s var __attribute__((__cleanup__(os_activity_scope_leave))); \
417
+
os_activity_scope_enter(activity, &var)
418
+
#define os_activity_scope(activity) _os_activity_scope(OS_CONCAT(scope, __COUNTER__), activity)
419
+
#endif
420
+
421
+
#endif // OS_ACTIVITY_OBJECT_API
422
+
423
+
/*!
424
+
* @function os_activity_start
425
+
*
426
+
* @abstract
427
+
* Starts a new activity immediately within the current context.
428
+
*
429
+
* @discussion
430
+
* Starts a new activity immediately within the current context. Deprecated please use new
431
+
* os_activity_create and os_activity_apply.
432
+
*
433
+
* os_activity_t activity = os_activity_start("indexing database", OS_ACTIVITY_FLAG_DEFAULT);
434
+
* < do some work >
435
+
* os_activity_end(activity);
436
+
*
437
+
* @param description
438
+
* A constant string describing the activity, e.g., "performClick" or
439
+
* "menuSelection".
440
+
*
441
+
* @param flags
442
+
* Flags to be used when initiating the activity, typically OS_ACTIVITY_FLAG_DEFAULT.
443
+
*
444
+
* @result
445
+
* Returns a valid os_activity_id_t or 0 on failure.
446
+
*/
447
+
#define os_activity_start(description, flags) __extension__({ \
448
+
OS_LOG_STRING(__description, description); \
449
+
os_activity_t _aid = _os_activity_start(&__dso_handle, __description, flags); \
450
+
_aid; \
451
+
})
452
+
453
+
/*!
454
+
* @function os_activity_end
455
+
*
456
+
* @abstract
457
+
* Ends the specified activity on the current thread.
458
+
*
459
+
* @discussion
460
+
* Ends the specified activity on the current thread. Does not signify anything
461
+
* other than the originator has received control back from the activity. Work
462
+
* could still be in flight related to the activity.
463
+
*
464
+
* @param activity
465
+
* An os_activity_t returned from os_activity_start.
466
+
*/
467
+
__API_DEPRECATED("use combination of os_activity_create and os_activity_apply/os_activity_scope", macosx(10.10, 10.12), ios(8.0, 10.0), watchos(2.0, 3.0), tvos(9.0, 10.0))
468
+
OS_EXPORT OS_NOTHROW
469
+
void
470
+
os_activity_end(os_activity_t activity);
471
+
472
+
/*!
473
+
* @function os_activity_get_active
474
+
*
475
+
* @abstract
476
+
* Returns the stack of nested activities associated with the current thread.
477
+
*
478
+
* @discussion
479
+
* Activities have a sense of nesting and therefore there could be more than
480
+
* one activity involved on the current thread. This should be used by
481
+
* diagnostic tools only for making additional decisions about a situation.
482
+
*
483
+
* @param entries
484
+
* Pass a buffer of sufficient size to hold the the number of os_activity_id_t
485
+
* being requested.
486
+
*
487
+
* @param count
488
+
* Pointer to the requested number of activity identifiers.
489
+
* On output will be filled with the number of activities that are available.
490
+
*
491
+
* @result
492
+
* Number of activity identifiers written to 'entries'
493
+
*/
494
+
__API_DEPRECATED("No longer supported", macosx(10.10, 10.12), ios(8.0, 10.0), watchos(2.0, 3.0), tvos(9.0, 10.0))
495
+
OS_EXPORT OS_NOTHROW
496
+
unsigned int
497
+
os_activity_get_active(os_activity_id_t *entries, unsigned int *count);
498
+
499
+
/*!
500
+
* @function os_activity_get_identifier
501
+
*
502
+
* @abstract
503
+
* Returns the current activity ID and will fill the parent_id if present.
504
+
*
505
+
* @discussion
506
+
* Returns the current activity ID and will fill the parent_id if present.
507
+
*
508
+
* @param parent_id
509
+
* If non-null will set the parent activity ID.
510
+
*
511
+
* @result
512
+
* The identifier for the provided activity.
513
+
*/
514
+
__API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0))
515
+
OS_EXPORT OS_NOTHROW OS_NONNULL1 OS_WARN_RESULT
516
+
os_activity_id_t
517
+
os_activity_get_identifier(os_activity_t activity, os_activity_id_t *parent_id);
518
+
519
+
/*!
520
+
* @function os_activity_label_useraction
521
+
*
522
+
* @abstract
523
+
* Label an activity that is auto-generated by AppKit/UIKit with a name that is useful
524
+
* for debugging macro-level user actions.
525
+
*
526
+
* @discussion
527
+
* Label an activity that is auto-generated by AppKit/UIKit with a name that is useful
528
+
* for debugging macro-level user actions. The API should be called early within the scope
529
+
* of the IBAction and before any sub-activities are created. The name provided will
530
+
* be shown in tools in additon to the underlying AppKit/UIKit provided name. This API
531
+
* can only be called once and only on the activity created by AppKit/UIKit. These actions
532
+
* help determine workflow of the user in order to reproduce problems that occur.
533
+
* For example, a control press and/or menu item selection can be labeled:
534
+
*
535
+
* os_activity_label_useraction("New mail message");
536
+
* os_activity_label_useraction("Empty trash");
537
+
*
538
+
* Where the underlying AppKit/UIKit name will be "gesture:" or "menuSelect:".
539
+
*
540
+
* @param name
541
+
* A constant string that describes the the action.
542
+
*/
543
+
#define os_activity_label_useraction(label) __extension__({ \
544
+
OS_LOG_STRING(__label, label); \
545
+
_os_activity_label_useraction(&__dso_handle, __label); \
546
+
})
547
+
548
+
#pragma mark - application breadcrumbs
549
+
550
+
/*!
551
+
* @function os_activity_set_breadcrumb
552
+
*
553
+
* @abstract
554
+
* This flags the current activity as a "breadcrumb", i.e., an interesting event.
555
+
*
556
+
* @discussion
557
+
* Not all activities are interesting events at the macro-level. Some activities
558
+
* can be flagged as a breadcrumb for evalutating cross activity interactions.
559
+
* This can only be called once per activity, other requests will be ignored.
560
+
*
561
+
* @param name
562
+
* A constant string that describes the breadcrumb.
563
+
*/
564
+
#define os_activity_set_breadcrumb(name) __extension__({ \
565
+
OS_LOG_STRING(__name, name); \
566
+
_os_activity_set_breadcrumb(&__dso_handle, __name); \
567
+
})
568
+
569
+
__END_DECLS
570
+
571
+
#endif // __OS_ACTIVITY_H__
+473
src/libc/os/log.h
+473
src/libc/os/log.h
···
1
+
/*
2
+
* Copyright (c) 2015-2016 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 __os_log_h
25
+
#define __os_log_h
26
+
27
+
#include <os/object.h>
28
+
#include <os/base.h>
29
+
#include <os/trace.h>
30
+
#include <stdint.h>
31
+
#include <stdbool.h>
32
+
#include <mach-o/loader.h>
33
+
34
+
#if !__has_builtin(__builtin_os_log_format)
35
+
#warning using os/log.h requires Xcode 8 or later
36
+
#endif
37
+
38
+
__BEGIN_DECLS
39
+
40
+
#ifdef OS_LOG_FORMAT_WARNINGS
41
+
#define OS_LOG_FORMAT_ERRORS _Pragma("clang diagnostic warning \"-Wformat\"")
42
+
#else
43
+
#define OS_LOG_FORMAT_ERRORS _Pragma("clang diagnostic error \"-Wformat\"")
44
+
#endif
45
+
46
+
extern void* __dso_handle;
47
+
48
+
#if OS_OBJECT_SWIFT3
49
+
OS_OBJECT_DECL_SWIFT(os_log);
50
+
#elif OS_OBJECT_USE_OBJC
51
+
OS_OBJECT_DECL(os_log);
52
+
#else
53
+
typedef struct os_log_s *os_log_t;
54
+
#endif /* OS_OBJECT_USE_OBJC */
55
+
56
+
/*!
57
+
* @const OS_LOG_DISABLED
58
+
*
59
+
* @discussion
60
+
* Use this to disable a specific log message.
61
+
*/
62
+
#define OS_LOG_DISABLED NULL
63
+
64
+
/*!
65
+
* @const OS_LOG_DEFAULT
66
+
*
67
+
* @discussion
68
+
* Use this to log a message in accordance with current system settings.
69
+
*/
70
+
#define OS_LOG_DEFAULT OS_OBJECT_GLOBAL_OBJECT(os_log_t, _os_log_default)
71
+
__API_AVAILABLE(macosx(10.11), ios(9.0), watchos(2.0), tvos(9.0))
72
+
OS_EXPORT
73
+
struct os_log_s _os_log_default;
74
+
75
+
/*!
76
+
* @enum os_log_type_t
77
+
*
78
+
* @discussion
79
+
* Supported log message types.
80
+
*
81
+
* @constant OS_LOG_TYPE_DEFAULT
82
+
* Equivalent type for "os_log()" messages, i.e., default messages that are always
83
+
* captured to memory or disk.
84
+
*
85
+
* @constant OS_LOG_TYPE_INFO
86
+
* Equivalent type for "os_log_info()" messages, i.e., Additional informational messages.
87
+
*
88
+
* @constant OS_LOG_TYPE_DEBUG
89
+
* Equivalent type for "os_log_debug()" messages, i.e., Debug messages.
90
+
*
91
+
* @constant OS_LOG_TYPE_ERROR
92
+
* Equivalent type for "os_log_error()" messages, i.e., local process error messages.
93
+
*
94
+
* @constant OS_LOG_TYPE_FAULT
95
+
* Equivalent type for "os_log_fault()" messages, i.e., a system error that involves
96
+
* potentially more than one process, usually used by daemons and services.
97
+
*/
98
+
OS_ENUM(os_log_type, uint8_t,
99
+
OS_LOG_TYPE_DEFAULT = 0x00,
100
+
OS_LOG_TYPE_INFO = 0x01,
101
+
OS_LOG_TYPE_DEBUG = 0x02,
102
+
OS_LOG_TYPE_ERROR = 0x10,
103
+
OS_LOG_TYPE_FAULT = 0x11);
104
+
105
+
/*!
106
+
* @function os_log_create
107
+
*
108
+
* @abstract
109
+
* Creates a log object to be used with other log related functions.
110
+
*
111
+
* @discussion
112
+
* Creates a log object to be used with other log related functions. The
113
+
* log object serves two purposes: (1) tag related messages by subsystem
114
+
* and category name for easy filtering, and (2) control logging system
115
+
* behavior for messages. The log object may be NULL if logging is disabled
116
+
* on the system.
117
+
*
118
+
* @param subsystem
119
+
* The identifier of the given subsystem should be in reverse DNS form
120
+
* (i.e., com.company.mysubsystem).
121
+
*
122
+
* @param category
123
+
* The category within the given subsystem that specifies the settings for
124
+
* the log object.
125
+
*
126
+
* @result
127
+
* Returns an os_log_t value to be passed to other os_log API calls. This
128
+
* should be called once at log initialization and rely on system to detect
129
+
* changes to settings. This object should be released when no longer used
130
+
* via os_release or -[release] method.
131
+
*
132
+
* A value will always be returned to allow for dynamic enablement.
133
+
*/
134
+
__API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0))
135
+
OS_EXPORT OS_NOTHROW OS_WARN_RESULT OS_OBJECT_RETURNS_RETAINED OS_NONNULL_ALL
136
+
os_log_t
137
+
os_log_create(const char *subsystem, const char *category);
138
+
139
+
/*!
140
+
* @function os_log_info_enabled
141
+
*
142
+
* @abstract
143
+
* Returns if additional information is enabled,
144
+
*
145
+
* @discussion
146
+
* Returns if additional information is enabled,
147
+
*
148
+
* @param log
149
+
* Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
150
+
*
151
+
* @result
152
+
* Returns ‘true’ if debug log messages are enabled.
153
+
*/
154
+
#define os_log_info_enabled(log) os_log_type_enabled(log, OS_LOG_TYPE_INFO)
155
+
156
+
/*!
157
+
* @function os_log_debug_enabled
158
+
*
159
+
* @abstract
160
+
* Returns if debug log messages are enabled for a particular log object.
161
+
*
162
+
* @discussion
163
+
* Returns if debug log messages are enabled for a particular log object.
164
+
*
165
+
* @param log
166
+
* Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
167
+
*
168
+
* @result
169
+
* Returns ‘true’ if debug log messages are enabled.
170
+
*/
171
+
#define os_log_debug_enabled(log) os_log_type_enabled(log, OS_LOG_TYPE_DEBUG)
172
+
173
+
/*!
174
+
* @function os_log_with_type
175
+
*
176
+
* @abstract
177
+
* Log a message using a specific type.
178
+
*
179
+
* @discussion
180
+
* Will log a message with the provided os_log_type_t.
181
+
*
182
+
* @param log
183
+
* Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
184
+
*
185
+
* @param type
186
+
* Pass a valid type from os_log_type_t.
187
+
*
188
+
* @param format
189
+
* A format string to generate a human-readable log message when the log
190
+
* line is decoded. This string must be a constant string, not dynamically
191
+
* generated. Supports all standard printf types in addition to %@ (objects).
192
+
*/
193
+
#if !__has_builtin(__builtin_os_log_format)
194
+
#define os_log_with_type(log, type, format, ...)
195
+
#else
196
+
#define os_log_with_type(log, type, format, ...) __extension__({ \
197
+
if (os_log_type_enabled(log, type)) { \
198
+
_Pragma("clang diagnostic push") \
199
+
_Pragma("clang diagnostic ignored \"-Wvla\"") \
200
+
OS_LOG_FORMAT_ERRORS \
201
+
__attribute__((section("__TEXT,__oslogstring,cstring_literals"),internal_linkage)) static const char __format[] __asm(OS_STRINGIFY(OS_CONCAT(LOSLOG_, __COUNTER__))) = format; \
202
+
uint8_t _os_log_buf[__builtin_os_log_format_buffer_size(format, ##__VA_ARGS__)]; \
203
+
_os_log_impl(&__dso_handle, log, type, __format, (uint8_t *) __builtin_os_log_format(_os_log_buf, format, ##__VA_ARGS__), (unsigned int) sizeof(_os_log_buf)); \
204
+
_Pragma("clang diagnostic pop") \
205
+
} \
206
+
})
207
+
#endif
208
+
209
+
/*!
210
+
* @function os_log
211
+
*
212
+
* @abstract
213
+
* Insert a log message into the Unified Logging and Tracing system.
214
+
*
215
+
* @discussion
216
+
* Insert a log message into the Unified Logging and Tracing system in
217
+
* accordance with the preferences specified by the provided log object.
218
+
* These messages cannot be disabled and therefore always captured either
219
+
* to memory or disk.
220
+
*
221
+
* When an os_activity_id_t is present, the log message will also be scoped by
222
+
* that identifier. Activities provide granular filtering of log messages
223
+
* across threads and processes.
224
+
*
225
+
* There is a physical cap of 1024 bytes per log line for dynamic content,
226
+
* such as %s and %@, that can be written to the persistence store.
227
+
* All content exceeding the limit will be truncated before it is
228
+
* written to disk.
229
+
*
230
+
* @param log
231
+
* Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
232
+
*
233
+
* @param format
234
+
* A format string to generate a human-readable log message when the log
235
+
* line is decoded. This string must be a constant string, not dynamically
236
+
* generated. Supports all standard printf types and %@ (objects).
237
+
*/
238
+
#define os_log(log, format, ...) os_log_with_type(log, OS_LOG_TYPE_DEFAULT, format, ##__VA_ARGS__)
239
+
240
+
/*!
241
+
* @function os_log_info
242
+
*
243
+
* @abstract
244
+
* Insert an additional information log message into the Unified Logging
245
+
* and Tracing system.
246
+
*
247
+
* @discussion
248
+
* Insert a log message into the Unified Logging and Tracing system in
249
+
* accordance with the preferences specified by the provided log object.
250
+
*
251
+
* When an os_activity_id_t is present, the log message will also be scoped by
252
+
* that identifier. Activities provide granular filtering of log messages
253
+
* across threads and processes.
254
+
*
255
+
* There is a physical cap of 256 bytes per entry for dynamic content,
256
+
* i.e., %s and %@, that can be written to the persistence store. As such,
257
+
* all content exceeding the limit will be truncated before written to disk.
258
+
* Live streams will continue to show the full content.
259
+
*
260
+
* @param log
261
+
* Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
262
+
*
263
+
* @param format
264
+
* A format string to generate a human-readable log message when the log
265
+
* line is decoded. This string must be a constant string, not dynamically
266
+
* generated. Supports all standard printf types and %@ (objects).
267
+
*/
268
+
#define os_log_info(log, format, ...) os_log_with_type(log, OS_LOG_TYPE_INFO, format, ##__VA_ARGS__)
269
+
270
+
/*!
271
+
* @function os_log_debug
272
+
*
273
+
* @abstract
274
+
* Insert a debug log message into the Unified Logging and Tracing system.
275
+
*
276
+
* @discussion
277
+
* Insert a debug log message into the Unified Logging and Tracing system in
278
+
* accordance with the preferences specified by the provided log object.
279
+
*
280
+
* When an os_activity_id_t is present, the log message will also be scoped by
281
+
* that identifier. Activities provide granular filtering of log messages
282
+
* across threads and processes.
283
+
*
284
+
* There is a physical cap of 256 bytes per entry for dynamic content,
285
+
* i.e., %s and %@, that can be written to the persistence store. As such,
286
+
* all content exceeding the limit will be truncated before written to disk.
287
+
* Live streams will continue to show the full content.
288
+
*
289
+
* @param log
290
+
* Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
291
+
*
292
+
* @param format
293
+
* A format string to generate a human-readable log message when the log
294
+
* line is decoded. This string must be a constant string, not dynamically
295
+
* generated. Supports all standard printf types and %@ (objects).
296
+
*/
297
+
#define os_log_debug(log, format, ...) os_log_with_type(log, OS_LOG_TYPE_DEBUG, format, ##__VA_ARGS__)
298
+
299
+
/*!
300
+
* @function os_log_error
301
+
*
302
+
* @abstract
303
+
* Insert an error log message into the Unified Logging and Tracing system.
304
+
*
305
+
* @discussion
306
+
* Insert an error log message into the Unified Logging and Tracing system.
307
+
*
308
+
* When an os_activity_id_t is present, the log message will also be scoped by
309
+
* that identifier. Activities provide granular filtering of log messages
310
+
* across threads and processes.
311
+
*
312
+
* There is a physical cap of 256 bytes per entry for dynamic content,
313
+
* i.e., %s and %@, that can be written to the persistence store. As such,
314
+
* all content exceeding the limit will be truncated before written to disk.
315
+
* Live streams will continue to show the full content.
316
+
*
317
+
* @param log
318
+
* Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
319
+
*
320
+
* @param format
321
+
* A format string to generate a human-readable log message when the log
322
+
* line is decoded. This string must be a constant string, not dynamically
323
+
* generated. Supports all standard printf types and %@ (objects).
324
+
*/
325
+
#define os_log_error(log, format, ...) os_log_with_type(log, OS_LOG_TYPE_ERROR, format, ##__VA_ARGS__)
326
+
327
+
/*!
328
+
* @function os_log_fault
329
+
*
330
+
* @abstract
331
+
* Insert a fault log message into the Unified Logging and Tracing system.
332
+
*
333
+
* @discussion
334
+
* Log a fault message issue into the Unified Logging and Tracing system
335
+
* signifying a multi-process (i.e., system error) related issue, either
336
+
* due to interaction via IPC or some other. Faults will gather information
337
+
* from the entire process chain and record it for later inspection.
338
+
*
339
+
* When an os_activity_id_t is present, the log message will also be scoped by
340
+
* that identifier. Activities provide granular filtering of log messages
341
+
* across threads and processes.
342
+
*
343
+
* There is a physical cap of 256 bytes per entry for dynamic content,
344
+
* i.e., %s and %@, that can be written to the persistence store. As such,
345
+
* all content exceeding the limit will be truncated before written to disk.
346
+
* Live streams will continue to show the full content.
347
+
*
348
+
* @param log
349
+
* Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
350
+
*
351
+
* @param format
352
+
* A format string to generate a human-readable log message when the log
353
+
* line is decoded. This string must be a constant string, not dynamically
354
+
* generated. Supports all standard printf types and %@ (objects).
355
+
*/
356
+
#define os_log_fault(log, format, ...) os_log_with_type(log, OS_LOG_TYPE_FAULT, format, ##__VA_ARGS__)
357
+
358
+
/*!
359
+
* @function os_log_type_enabled
360
+
*
361
+
* @abstract
362
+
* Evaluate if a specific log type is enabled before doing work
363
+
*
364
+
* @discussion
365
+
* Evaluate if a specific log type is enabled before doing work
366
+
*
367
+
* @param log
368
+
* Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
369
+
*
370
+
* @param type
371
+
* Pass a valid type from os_log_type_t.
372
+
*
373
+
* @result
374
+
* Will return a boolean.
375
+
*/
376
+
__API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0))
377
+
OS_EXPORT OS_NOTHROW OS_WARN_RESULT
378
+
bool
379
+
os_log_type_enabled(os_log_t oslog, os_log_type_t type);
380
+
381
+
/*!
382
+
* @function _os_log_impl
383
+
*
384
+
* @abstract
385
+
* Internal function that takes compiler generated encoding and captures the necessary content.
386
+
*/
387
+
__API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0))
388
+
OS_EXPORT OS_NOTHROW OS_NOT_TAIL_CALLED
389
+
void
390
+
_os_log_impl(void *dso, os_log_t log, os_log_type_t type, const char *format, uint8_t *buf, unsigned int size);
391
+
392
+
/*
393
+
* Support for older iteration of API for source compatibility only...
394
+
*/
395
+
396
+
__API_DEPRECATED("no longer supported, use os_log_debug(OS_LOG_DEFAULT, ...)", macosx(10.11,10.12), ios(9.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0))
397
+
OS_EXPORT OS_NOTHROW OS_NOT_TAIL_CALLED
398
+
void
399
+
_os_log_internal(void *dso, os_log_t log, os_log_type_t type, const char *message, ...);
400
+
401
+
__API_AVAILABLE(macosx(10.11), ios(9.0), watchos(2.0), tvos(9.0))
402
+
OS_EXPORT OS_NOTHROW OS_WARN_RESULT OS_OBJECT_RETURNS_RETAINED OS_NOT_TAIL_CALLED OS_NONNULL_ALL
403
+
os_log_t
404
+
_os_log_create(void *dso, const char *subsystem, const char *category);
405
+
406
+
__API_DEPRECATED("no longer suppored - always returns true", macosx(10.11,10.12), ios(9.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0))
407
+
OS_EXPORT OS_NOTHROW OS_WARN_RESULT
408
+
bool
409
+
os_log_is_enabled(os_log_t log);
410
+
411
+
__API_DEPRECATED_WITH_REPLACEMENT("os_log_debug_enabled", macosx(10.11,10.12), ios(9.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0))
412
+
OS_EXPORT OS_NOTHROW OS_WARN_RESULT
413
+
bool
414
+
os_log_is_debug_enabled(os_log_t log);
415
+
416
+
__API_DEPRECATED("no longer supported - use os_log with per-parameter privacy options", macosx(10.11,10.12), ios(9.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0))
417
+
OS_NOTHROW OS_ALWAYS_INLINE
418
+
static inline void
419
+
_os_log_sensitive_deprecated(void) { }
420
+
421
+
#define os_log_sensitive(log, format, ...) __extension__({ \
422
+
os_log_with_type(log, OS_LOG_TYPE_DEFAULT, format, ##__VA_ARGS__); \
423
+
_os_log_sensitive_deprecated(); \
424
+
})
425
+
426
+
#define os_log_sensitive_debug(log, format, ...) __extension__({ \
427
+
os_log_with_type(log, OS_LOG_TYPE_DEBUG, format, ##__VA_ARGS__); \
428
+
_os_log_sensitive_deprecated(); \
429
+
})
430
+
431
+
#define OS_LOG_RELEASE OS_OBJECT_GLOBAL_OBJECT(os_log_t, _os_log_release)
432
+
__API_DEPRECATED("use os_log(OS_LOG_DEFAULT, ...)", macosx(10.11,10.11), ios(9.0,9.0), watchos(2.0,2.0), tvos(9.0,9.0))
433
+
OS_EXPORT
434
+
struct os_log_s _os_log_release;
435
+
436
+
#define OS_LOG_DEBUG OS_OBJECT_GLOBAL_OBJECT(os_log_t, _os_log_debug)
437
+
__API_DEPRECATED("use os_log_debug(OS_LOG_DEFAULT, ...)", macosx(10.11,10.11), ios(9.0,9.0), watchos(2.0,2.0), tvos(9.0,9.0))
438
+
OS_EXPORT
439
+
struct os_log_s _os_log_debug;
440
+
441
+
#define OS_LOG_ERROR OS_OBJECT_GLOBAL_OBJECT(os_log_t, _os_log_error)
442
+
__API_DEPRECATED("use os_log_error(OS_LOG_DEFAULT, ...)", macosx(10.11,10.11), ios(9.0,9.0), watchos(2.0,2.0), tvos(9.0,9.0))
443
+
OS_EXPORT
444
+
struct os_log_s _os_log_error;
445
+
446
+
#define OS_LOG_FAULT OS_OBJECT_GLOBAL_OBJECT(os_log_t, _os_log_fault)
447
+
__API_DEPRECATED("use os_log_fault(OS_LOG_DEFAULT, ...)", macosx(10.11,10.11), ios(9.0,9.0), watchos(2.0,2.0), tvos(9.0,9.0))
448
+
OS_EXPORT
449
+
struct os_log_s _os_log_fault;
450
+
451
+
#if ((defined(__MAC_OS_X_VERSION_MIN_REQUIRED) && __MAC_OS_X_VERSION_MIN_REQUIRED < __MAC_10_12) \
452
+
|| (defined(__IPHONE_OS_VERSION_MIN_REQUIRED) && !defined(__TV_OS_VERSION_MIN_REQUIRED) \
453
+
&& !defined(__WATCH_OS_VERSION_MIN_REQUIRED) && __IPHONE_OS_VERSION_MIN_REQUIRED < __IPHONE_10_0) \
454
+
|| (defined(__TV_OS_VERSION_MIN_REQUIRED) && __TV_OS_VERSION_MIN_REQUIRED < __TVOS_10_0) \
455
+
|| (defined(__WATCH_OS_VERSION_MIN_REQUIRED) && __WATCH_OS_VERSION_MIN_REQUIRED < __WATCHOS_3_0))
456
+
#undef os_log_with_type
457
+
#define os_log_with_type(log, type, format, ...) __extension__({ \
458
+
_Pragma("clang diagnostic push") \
459
+
_Pragma("clang diagnostic error \"-Wformat\"") \
460
+
_os_log_internal(&__dso_handle, log, type, format, ##__VA_ARGS__); \
461
+
_Pragma("clang diagnostic pop") \
462
+
})
463
+
464
+
#undef os_log_debug_enabled
465
+
#define os_log_debug_enabled(...) os_log_is_debug_enabled(__VA_ARGS__)
466
+
467
+
#undef os_log_create
468
+
#define os_log_create(subsystem, category) _os_log_create(&__dso_handle, subsystem, category)
469
+
#endif
470
+
471
+
__END_DECLS
472
+
473
+
#endif /* __os_log_h */