#include <os/activity.h>
os/

os/activity.h

includes: os/trace_base.h
13 functions · 12 macros · 5 typedefs · 2 variables · 1 enum · 1 struct

macroOS_ACTIVITY_OBJECT_API

#define OS_ACTIVITY_OBJECT_API 1

enumos_activity_flag_t

@enum os_activity_flag_t @discussion Support flags for os_activity_create or os_activity_start. @constant OS_ACTIVITY_FLAG_DEFAULT Use the default flags. @constant OS_ACTIVITY_FLAG_DETACHED Detach the newly created activity from the provided activity (if any). If passed in conjunction with an exiting activity, the activity will only note what activity "created" the new one, but will make the new activity a top level activity. This allows users to see what activity triggered work without actually relating the activities. @constant OS_ACTIVITY_FLAG_IF_NONE_PRESENT Will only create a new activity if none present. If an activity ID is already present, a new object will be returned with the same activity ID underneath. Passing both OS_ACTIVITY_FLAG_DETACHED and OS_ACTIVITY_FLAG_IF_NONE_PRESENT is undefined.
underlying type uint32_t
OS_ACTIVITY_FLAG_DEFAULT0
OS_ACTIVITY_FLAG_DETACHED1
OS_ACTIVITY_FLAG_IF_NONE_PRESENT2

typedefos_activity_flag_t

typedef enum os_activity_flag_t os_activity_flag_t;

macroOS_ACTIVITY_NULL

#define OS_ACTIVITY_NULL NULL

typedefos_activity_t

typedef struct os_activity_s *os_activity_t

macroOS_ACTIVITY_NONE

@const OS_ACTIVITY_NONE @discussion Create activity with no current traits, this is the equivalent of a detached activity.
#define OS_ACTIVITY_NONE OS_OBJECT_GLOBAL_OBJECT(os_activity_t, _os_activity_none)

variable_os_activity_none

API_AVAILABLE(macos(10.12), ios(10.0), watchos(3.0), tvos(10.0)) OS_EXPORT struct os_activity_s _os_activity_none

macroOS_ACTIVITY_CURRENT

@const OS_ACTIVITY_CURRENT @discussion Create activity and links to the current activity if one is present. If no activity is present it is treated as if it is detached.
#define OS_ACTIVITY_CURRENT OS_OBJECT_GLOBAL_OBJECT(os_activity_t, _os_activity_current)

variable_os_activity_current

API_AVAILABLE(macos(10.12), ios(10.0), watchos(3.0), tvos(10.0)) OS_EXPORT struct os_activity_s _os_activity_current

typedefos_activity_id_t

typedef uint64_t os_activity_id_t

structos_activity_scope_state_s

size 16, align 8
uint64_t[2]opaque

typedefos_activity_scope_state_t

typedef struct os_activity_scope_state_s * os_activity_scope_state_t;

function_os_activity_create

API_AVAILABLE(macos(10.12), ios(10.0), watchos(3.0), tvos(10.0)) OS_EXPORT OS_NOTHROW OS_WARN_RESULT_NEEDS_RELEASE OS_NOT_TAIL_CALLED OS_OBJECT_RETURNS_RETAINED os_activity_t _os_activity_create(
	void *dso,
	const char *description,
	os_activity_t activity,
	os_activity_flag_t flags
)

function_os_activity_label_useraction

API_AVAILABLE(macos(10.12), ios(10.0), watchos(3.0), tvos(10.0)) OS_EXPORT OS_NOTHROW OS_NOT_TAIL_CALLED void _os_activity_label_useraction(
	void *dso,
	const char *name
)
@function _os_activity_label_useraction @abstract Internal function for use by os_activity_label_useraction. @warning Do not use directly.

function_os_activity_initiate

API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) OS_EXPORT OS_NOTHROW OS_NOT_TAIL_CALLED void _os_activity_initiate(
	void *dso,
	const char *description,
	os_activity_flag_t flags,
	os_block_t activity_block OS_NOESCAPE
)
@function _os_activity_initiate @abstract Do not use directly because your description will not be preserved.

function_os_activity_initiate_f

API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) OS_EXPORT OS_NOTHROW OS_NOT_TAIL_CALLED void _os_activity_initiate_f(
	void *dso,
	const char *description,
	os_activity_flag_t flags,
	void *context,
	os_function_t function
)
@function _os_activity_initiate_f @abstract Do not use directly because your description will not be preserved.

macroos_activity_initiate

@function os_activity_initiate @abstract Synchronously initiates an activity using provided block. @discussion Synchronously initiates an activity using the provided block and creates a tracing buffer as appropriate. All new activities are created as a subactivity of an existing activity on the current thread. <code> os_activity_initiate("indexing database", OS_ACTIVITY_FLAG_DEFAULT, ^(void) { // either do work directly or issue work asynchronously }); </code> @param description A constant string describing the activity, e.g., "performClick" or "menuSelection". @param flags Flags to be used when initiating the activity, typically OS_ACTIVITY_FLAG_DEFAULT. @param activity_block The block to execute a given activity
#define os_activity_initiate(description, flags, activity_block) __extension__({
    OS_LOG_STRING(ACT, __description, description);
    _os_activity_initiate(&__dso_handle, __description, flags, activity_block);
})

macroos_activity_initiate_f

@function os_activity_initiate_f @abstract Synchronously initiates an activity using the provided function. @discussion Synchronously initiates an activity using the provided function and creates a tracing buffer as appropriate. All new activities are created as a subactivity of an existing activity on the current thread. <code> os_activity_initiate_f("indexing database", OS_ACTIVITY_FLAG_DEFAULT, context, function); </code> @param description A constant string describing the activity, e.g., "performClick" or "menuSelection". @param flags Flags to be used when initiating the activity, typically OS_ACTIVITY_FLAG_DEFAULT. @param context An optional context that will be supplied to the activity function. @param activity_func The function to execute for the new activity.
#define os_activity_initiate_f(description, flags, context, function) __extension__({
    OS_LOG_STRING(ACT, __description, description);
    _os_activity_initiate_f(&__dso_handle, __description, flags, context, function);
})

macroos_activity_create

@function os_activity_create @abstract Creates an os_activity_t object which can be passed to os_activity_apply function. @param description Pass a description for the activity. The description must be a constant string within the calling executable or library. @param parent_activity Depending on flags will link the newly created activity to the value passed or note where the activity was created. Possible activities include: OS_ACTIVITY_NONE, OS_ACTIVITY_CURRENT or any existing os_activity_t object created using os_activity_create. @param flags A valid os_activity_flag_t which will determine behavior of the newly created activity. If the OS_ACTIVITY_FLAG_DETACHED flag is passed, the value passed to the parent_activity argument is ignored, and OS_ACTIVITY_NONE is used instead. If the OS_ACTIVITY_FLAG_IF_NONE_PRESENT flag is passed, then passing another value than OS_ACTIVITY_CURRENT to the parent_activity argument is undefined. @result Returns an os_activity_t object which can be used with os_activity_apply.
#define os_activity_create(description, parent_activity, flags) __extension__({
    OS_LOG_STRING(ACT, __description, description);
    _os_activity_create(&__dso_handle, __description, parent_activity, flags);
})

functionos_activity_apply

API_AVAILABLE(macos(10.12), ios(10.0), watchos(3.0), tvos(10.0)) OS_EXPORT OS_NOTHROW void os_activity_apply(
	os_activity_t activity,
	os_block_t block OS_NOESCAPE
)
@function os_activity_apply @abstract Execute a block using a given activity object. @param activity The given activity object created with os_activity_create() or OS_ACTIVITY_NONE. @param block Pass the block to be executed within the context of the given activity.

functionos_activity_apply_f

API_AVAILABLE(macos(10.12), ios(10.0), watchos(3.0), tvos(10.0)) OS_EXPORT OS_NOTHROW void os_activity_apply_f(
	os_activity_t activity,
	void *context,
	os_function_t function
)
@function os_activity_apply_f @abstract Execute a given function with a provided activity. @param activity The given activity object created with os_activity_create() or OS_ACTIVITY_NONE. @param context Context to pass to the function which may be NULL. @param function Pass the function to be executed within the context of the given activity.

functionos_activity_scope_enter

API_AVAILABLE(macos(10.12), ios(10.0), watchos(3.0), tvos(10.0)) OS_EXPORT OS_NOTHROW void os_activity_scope_enter(
	os_activity_t activity,
	os_activity_scope_state_t state
)
@function os_activity_scope_enter @abstract Will change the current execution context to use the provided activity. @discussion Will change the current execution context to use the provided activity. An activity can be created and then applied to the current scope by doing: <code> struct os_activity_scope_state_s state; os_activity_t activity = os_activity_create("my new activity", 0); os_activity_scope_enter(activity, &state); ... do some work ... os_activity_scope_leave(&state); </code> To auto-cleanup state call: os_activity_scope(activity); @param activity Pass a valid activity created with os_activity_create or any global object. @param state A stack-based struct os_activity_scope_state_s to store the state.

functionos_activity_scope_leave

API_AVAILABLE(macos(10.12), ios(10.0), watchos(3.0), tvos(10.0)) OS_EXPORT OS_NOTHROW void os_activity_scope_leave(
	os_activity_scope_state_t state
)
@function os_activity_scope_leave @abstract Will pop state up to the state provided. @discussion Will leave scope using the state provided. If state is not present an error will be generated. @param state Must be a valid value filled by os_activity_scope_enter call.

macro_os_activity_scope

#define _os_activity_scope(var, activity) struct os_activity_scope_state_s var __attribute__((__cleanup__(os_activity_scope_leave)));
    os_activity_scope_enter(activity, &var)

macroos_activity_scope

#define os_activity_scope(activity) _os_activity_scope(OS_CONCAT(scope, __COUNTER__), activity)

functionos_activity_get_active

API_DEPRECATED("No longer supported", macos(10.10, 10.12), ios(8.0, 10.0), watchos(2.0, 3.0), tvos(9.0, 10.0)) OS_EXPORT OS_NOTHROW unsigned int os_activity_get_active(
	os_activity_id_t *entries,
	unsigned int *count
)
deprecated
@function os_activity_get_active @abstract Returns the stack of nested activities associated with the current thread. @discussion Activities have a sense of nesting and therefore there could be more than one activity involved on the current thread. This should be used by diagnostic tools only for making additional decisions about a situation. @param entries Pass a buffer of sufficient size to hold the the number of os_activity_id_t being requested. @param count Pointer to the requested number of activity identifiers. On output will be filled with the number of activities that are available. @result Number of activity identifiers written to 'entries'

functionos_activity_get_identifier

API_AVAILABLE(macos(10.12), ios(10.0), watchos(3.0), tvos(10.0)) OS_EXPORT OS_NOTHROW OS_WARN_RESULT os_activity_id_t os_activity_get_identifier(
	os_activity_t activity,
	os_activity_id_t *_Nullable parent_id
)
@function os_activity_get_identifier @abstract Returns the current activity ID and will fill the parent_id if present. @discussion Returns the current activity ID and will fill the parent_id if present. @param parent_id If non-null will set the parent activity ID. @result The identifier for the provided activity.

macroos_activity_label_useraction

@function os_activity_label_useraction @abstract Label an activity that is auto-generated by AppKit/UIKit with a name that is useful for debugging macro-level user actions. @discussion Label an activity that is auto-generated by AppKit/UIKit with a name that is useful for debugging macro-level user actions. The API should be called early within the scope of the IBAction and before any sub-activities are created. The name provided will be shown in tools in additon to the underlying AppKit/UIKit provided name. This API can only be called once and only on the activity created by AppKit/UIKit. These actions help determine workflow of the user in order to reproduce problems that occur. For example, a control press and/or menu item selection can be labeled: <code> os_activity_label_useraction("New mail message"); os_activity_label_useraction("Empty trash"); </code> Where the underlying AppKit/UIKit name will be "gesture:" or "menuSelect:". @param name A constant string that describes the the action.
#define os_activity_label_useraction(label) __extension__({
    OS_LOG_STRING(ACT, __label, label);
    _os_activity_label_useraction(&__dso_handle, __label);
})

function_os_activity_start

API_DEPRECATED("use combination of os_activity_create and os_activity_apply/os_activity_scope", macos(10.10, 10.12), ios(8.0, 10.0), watchos(2.0, 3.0), tvos(9.0, 10.0)) OS_EXPORT OS_NOTHROW OS_WARN_RESULT OS_NOT_TAIL_CALLED os_activity_t _os_activity_start(
	void *dso,
	const char *description,
	os_activity_flag_t flags
)
deprecated
@function _os_activity_start @abstract Internal function for activity start, do not use directly will not preserve description.

macroos_activity_start

@function os_activity_start @warning Deprecated please use new os_activity_create and os_activity_apply.
#define os_activity_start(description, flags) __extension__({
    OS_LOG_STRING(ACT, __description, description);
    _os_activity_start(&__dso_handle, __description, flags);
})

functionos_activity_end

API_DEPRECATED("use combination of os_activity_create and os_activity_apply/os_activity_scope", macos(10.10, 10.12), ios(8.0, 10.0), watchos(2.0, 3.0), tvos(9.0, 10.0)) OS_EXPORT OS_NOTHROW void os_activity_end(
	os_activity_t activity
)
deprecated
@function os_activity_end @warning Deprecated please use new os_activity_create and os_activity_apply.

typedefos_breadcrumb_t

typedef uint32_t os_breadcrumb_t

function_os_activity_set_breadcrumb

API_DEPRECATED_WITH_REPLACEMENT("os_activity_label_useraction", macos(10.10, 10.12), ios(8.0, 10.0), watchos(2.0, 3.0), tvos(9.0, 10.0)) OS_EXPORT OS_NOTHROW OS_NOT_TAIL_CALLED void _os_activity_set_breadcrumb(
	void *dso,
	const char *name
)
deprecated
@function _os_activity_set_breadcrumb @warning Deprecated, please use os_activity_label_useraction.

macroos_activity_set_breadcrumb

@function os_activity_set_breadcrumb @warning Deprecated, please use os_activity_label_useraction.
#define os_activity_set_breadcrumb(name) __extension__({
    OS_LOG_STRING(ACT, __name, name);
    _os_activity_set_breadcrumb(&__dso_handle, __name);
})