#include <os/signpost.h>

os/signpost.h

@header os_signpost The os_signpost APIs let clients add lightweight instrumentation to code for collection and visualization by performance analysis tooling. Clients of os_signpost can instrument interesting periods of time ('intervals') and single points in time ('events'). Intervals can span processes, be specific to one process, or be specific to a single thread. Intervals and events include an os_log-style format string and arguments which can be used to convey contextual information.

includes: os/log.h

15 macros · 4 functions · 2 typedefs · 1 enum

typedefos_signpost_id_t

@typedef os_signpost_id_t @brief The type to represent a signpost ID. @discussion . Any 64-bit value can be cast to an os_signpost_id_t except for the OS_SIGNPOST_ID_NULL and OS_SIGNPOST_ID_INVALID reserved values. @const OS_SIGNPOST_ID_NULL Represents the null (absent) signpost ID. It is used by the signpost subsystem when a given signpost is disabled. @const OS_SIGNPOST_ID_INVALID Represents an invalid signpost ID, which signals that an error has occurred. @const OS_SIGNPOST_ID_EXCLUSIVE A convenience value for signpost intervals that will never occur concurrently.

typedef uint64_t os_signpost_id_t

macroOS_SIGNPOST_ID_NULL

#define OS_SIGNPOST_ID_NULL ((os_signpost_id_t)0)

macroOS_SIGNPOST_ID_INVALID

#define OS_SIGNPOST_ID_INVALID ((os_signpost_id_t)~0)

macroOS_SIGNPOST_ID_EXCLUSIVE

#define OS_SIGNPOST_ID_EXCLUSIVE ((os_signpost_id_t)0xEEEEB0B5B2B2EEEE)

functionos_signpost_id_make_with_pointer

API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) OS_EXPORT OS_NOTHROW os_signpost_id_t os_signpost_id_make_with_pointer(
	os_log_t log,
	const void *_Nullable ptr
)

@function os_signpost_id_make_with_pointer @abstract Make an os_signpost_id from a pointer value. @discussion Mangles the pointer to create a valid os_signpost_id, including removing address randomization. Checks that the signpost matching scope is not system-wide. @param log Log handle previously created with os_log_create. @param ptr Any pointer that disambiguates among concurrent intervals with the same os_log_t and interval names. @result Returns a valid os_signpost_id_t. Returns OS_SIGNPOST_ID_NULL if signposts are turned off. Returns OS_SIGNPOST_ID_INVALID if the log handle is system-scoped.

functionos_signpost_id_generate

API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) OS_EXPORT OS_NOTHROW OS_WARN_RESULT os_signpost_id_t os_signpost_id_generate(
	os_log_t log
)

@function os_signpost_id_generate @abstract Generates an ID guaranteed to be unique within the matching scope of the provided log handle. @discussion Each call to os_signpost_id_generate() with a given log handle and its matching scope will return a different os_signpost_id_t. @param log Log handle previously created with os_log_create. @result Returns a valid os_signpost_id_t. Returns OS_SIGNPOST_ID_NULL if signposts are disabled.

functionos_signpost_enabled

API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) OS_EXPORT OS_NOTHROW OS_PURE OS_WARN_RESULT bool os_signpost_enabled(
	os_log_t log
)

@function os_signpost_enabled @abstract Returns true if signpost log messages are enabled for a particular log handle. @discussion Returns true if signpost log messages are enabled for a particular log. Use this to avoid doing expensive argument marshalling leading into a call to os_signpost_* @param log Log handle previously created with os_log_create. @result Returns ‘true’ if signpost log messages are enabled.

macroos_signpost_interval_begin

@function os_signpost_interval_begin @abstract Begins a signposted interval. @param log Log handle previously created with os_log_create. @param interval_id An ID for the event, see Signpost IDs above. @param name The name of this event. This must be a string literal. @param ... (format + arguments) Additional information to include with this signpost. This format string must be a string literal, as with the os_log family of functions.

#define os_signpost_interval_begin(log, interval_id, name, ...) os_signpost_emit_with_type(log, OS_SIGNPOST_INTERVAL_BEGIN,
                interval_id, name, ##__VA_ARGS__)

macroos_signpost_animation_interval_begin

@function os_signpost_animation_interval_begin @abstract Begins a signposted interval that is tagged as an animation. @param log Log handle previously created with os_log_create. @param interval_id An ID for the event, see Signpost IDs above. @param name The name of this event. This must be a string literal. @param ... (format + arguments) Additional information to include with this signpost. This format string must be a string literal, as with the os_log family of functions.

#define os_signpost_animation_interval_begin(log, interval_id, name, ...) _os_signpost_animation_interval_begin(log, interval_id, name,
                "" __VA_ARGS__)

macroos_signpost_interval_end

@function os_signpost_interval_end @abstract Ends a signposted interval. @param log The log handle which was provided to os_signpost_interval_begin, @param interval_id The ID for the event which was provided to os_signpost_interval_begin. See Signpost IDs above. @param name The name of the event provided to os_signost_interval_begin. This must be a string literal. @param ... (format + arguments) Additional information to include with this signpost. This format string must be a string literal, as with the os_log family of functions.

#define os_signpost_interval_end(log, interval_id, name, ...) os_signpost_emit_with_type(log, OS_SIGNPOST_INTERVAL_END,
                interval_id, name, ##__VA_ARGS__)

macroos_signpost_event_emit

@function os_signpost_event_emit @abstract os_signpost_event_emit marks a point of interest in time with no duration. @param log Log handle previously created with os_log_create. @param event_id An ID for the event, see Signpost IDs above. This ID can be used to convey additional information about the event that is being emitted without incurring extra performance overhead. @param name The name of this event. This must be a string literal. @param ... (format + arguments) Additional information to include with this signpost. This format string must be a string literal, as with the os_log family of functions.

#define os_signpost_event_emit(log, event_id, name, ...) os_signpost_emit_with_type(log, OS_SIGNPOST_EVENT,
                event_id, name, ##__VA_ARGS__)

macroOS_LOG_CATEGORY_POINTS_OF_INTEREST

@const OS_LOG_CATEGORY_POINTS_OF_INTEREST Provide this value as the category to os_log_create to indicate that signposts on the resulting log handle provide high-level events that can be used to orient a developer looking at performance data. These will be displayed by default by performance tools like Instruments.app.

#define OS_LOG_CATEGORY_POINTS_OF_INTEREST "PointsOfInterest"

macroOS_LOG_CATEGORY_DYNAMIC_TRACING

@const OS_LOG_CATEGORY_DYNAMIC_TRACING Provide this value as the category to os_log_create to indicate that signposts emitted to the resulting log handle should be disabled by default, reducing the runtime overhead. os_signpost_enabled calls on the resulting log handle will only return 'true' when a performance tool like Instruments.app is recording.

#define OS_LOG_CATEGORY_DYNAMIC_TRACING "DynamicTracing"

macroOS_LOG_CATEGORY_DYNAMIC_STACK_TRACING

@const OS_LOG_CATEGORY_DYNAMIC_STACK_TRACING Provide this value as the category to os_log_create to indicate that signposts emitted to the resulting log handle should capture user backtraces. This behavior is more expensive, so os_signpost_enabled will only return 'true' when a performance tool like Instruments.app is recording.

#define OS_LOG_CATEGORY_DYNAMIC_STACK_TRACING "DynamicStackTracing"

enumos_signpost_type_t

@typedef os_signpost_type_t @brief The type of a signpost tracepoint, do not use directly.

underlying type uint8_t

OS_SIGNPOST_EVENT	0
OS_SIGNPOST_INTERVAL_BEGIN	1
OS_SIGNPOST_INTERVAL_END	2

typedefos_signpost_type_t

typedef enum os_signpost_type_t os_signpost_type_t;

macroOS_SIGNPOST_TYPE_MASK

#define OS_SIGNPOST_TYPE_MASK 0x03

macro_OS_SIGNPOST_ANIMATION_INTERVAL_TAG

#define _OS_SIGNPOST_ANIMATION_INTERVAL_TAG "isAnimation=YES"

macro_os_signpost_animation_interval_begin

#define _os_signpost_animation_interval_begin(log, spid, name, fmt, ...) os_signpost_interval_begin(log, spid, name,
                fmt " " _OS_SIGNPOST_ANIMATION_INTERVAL_TAG,
                ##__VA_ARGS__)

function_os_signpost_emit_with_name_impl

API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) OS_EXPORT OS_NOTHROW OS_NOT_TAIL_CALLED void _os_signpost_emit_with_name_impl(
	void *dso,
	os_log_t log,
	os_signpost_type_t type,
	os_signpost_id_t spid,
	const char *name,
	const char *format,
	uint8_t *buf,
	uint32_t size
)

macro_os_signpost_emit_with_type

#define _os_signpost_emit_with_type(emitfn, log, type, spid, name, ...) __extension__({
        os_log_t _log_tmp = (log);
        os_signpost_type_t _type_tmp = (type);
        os_signpost_id_t _spid_tmp = (spid);
        if (_spid_tmp != OS_SIGNPOST_ID_NULL &&
                _spid_tmp != OS_SIGNPOST_ID_INVALID &&
                os_signpost_enabled(_log_tmp)) {
            OS_LOG_CALL_WITH_FORMAT_NAME((emitfn),
                    (&__dso_handle, _log_tmp, _type_tmp, _spid_tmp),
                    name, "" __VA_ARGS__);
        }
    })

macroos_signpost_emit_with_type

#define os_signpost_emit_with_type(log, type, spid, name, ...) _os_signpost_emit_with_type(_os_signpost_emit_with_name_impl, log,
                type, spid, name, ##__VA_ARGS__)