docs-6.2.0/source/lib/omnitrace-user/omnitrace/user.h File Reference

• docs-6.2.0
• source
• lib
• omnitrace-user
• omnitrace

Functions

user.h File Reference

#include "omnitrace/categories.h"
#include "omnitrace/types.h"

Go to the source code of this file.

Functions
int	omnitrace_user_start_trace (void)
	Enable tracing on this thread and all subsequently created threads. More...
int	omnitrace_user_stop_trace (void)
	Disable tracing on this thread and all subsequently created threads. More...
int	omnitrace_user_start_thread_trace (void)
	Enable tracing on this specific thread. Does not apply to subsequently created threads. More...
int	omnitrace_user_stop_thread_trace (void)
	Disable tracing on this specific thread. Does not apply to subsequently created threads. More...
int	omnitrace_user_push_region (const char *)
	Start a user defined region. More...
int	omnitrace_user_pop_region (const char *)
	End a user defined region. In general, user regions should be popped in the inverse order that they were pushed, i.e. first-in, last-out (FILO). The timemory backend was designed to accommodate asynchronous tasking, where FILO may be violated, and will thus compenstate for out-of-order popping, however, the perfetto backend will not; thus, out-of-order popping will result in different results in timemory vs. perfetto. More...
int	omnitrace_user_push_annotated_region (const char *, omnitrace_annotation_t *, unsigned long)
int	omnitrace_user_pop_annotated_region (const char *, omnitrace_annotation_t *, unsigned long)
int	omnitrace_user_progress (const char *)
	mark causal progress More...
int	omnitrace_user_annotated_progress (const char *, omnitrace_annotation_t *, unsigned long)
	mark causal progress with annotations More...
int	omnitrace_user_configure (omnitrace_user_configure_mode_t mode, omnitrace_user_callbacks_t inp, omnitrace_user_callbacks_t *out)
	Configure the function pointers invoked by the omnitrace user API. The initial callbacks are set via the omnitrace-dl library when it is loaded but the user can user this feature to turn on/off the user API or customize how the the user callbacks occur. For example, the user could maintain one set of callbacks which discard any annotation data or redirect all unannotated user regions to the annotated user regions with annotations about some global state. Changing the callbacks is thread-safe but not thread-local. More...
int	omnitrace_user_get_callbacks (omnitrace_user_callbacks_t *)
const char *	omnitrace_user_error_string (int)
	Return a descriptor for the provided error code. More...

Function Documentation

◆ omnitrace_user_annotated_progress()

int omnitrace_user_annotated_progress	(	const char *	,
		omnitrace_annotation_t *	,
		unsigned long
	)

mark causal progress with annotations

◆ omnitrace_user_configure()

int omnitrace_user_configure	(	omnitrace_user_configure_mode_t	mode,
		omnitrace_user_callbacks_t	inp,
		omnitrace_user_callbacks_t *	out
	)

Configure the function pointers invoked by the omnitrace user API. The initial callbacks are set via the omnitrace-dl library when it is loaded but the user can user this feature to turn on/off the user API or customize how the the user callbacks occur. For example, the user could maintain one set of callbacks which discard any annotation data or redirect all unannotated user regions to the annotated user regions with annotations about some global state. Changing the callbacks is thread-safe but not thread-local.

Parameters

[in]	mode	Specifies how the new callbacks are merged with the old callbacks
[in]	inp	An omnitrace_user_callbacks instance specifying the callbacks which should be invoked by the user API.
[out]	out	Pointer to omnitrace_user_callbacks which, when non-NULL, will be assigned the former callbacks.

Returns

omnitrace_user_error_t value

◆ omnitrace_user_error_string()

const char * omnitrace_user_error_string

(

int

error_category

)

Return a descriptor for the provided error code.

Parameters

error_category

OMNITRACE_USER_ERROR value

Returns

String descripting the error code

◆ omnitrace_user_get_callbacks()

int omnitrace_user_get_callbacks

(

omnitrace_user_callbacks_t *

)

◆ omnitrace_user_pop_annotated_region()

int omnitrace_user_pop_annotated_region	(	const char *	,
		omnitrace_annotation_t *	,
		unsigned long
	)

◆ omnitrace_user_pop_region()

int omnitrace_user_pop_region

(

const char *

id

)

End a user defined region. In general, user regions should be popped in the inverse order that they were pushed, i.e. first-in, last-out (FILO). The timemory backend was designed to accommodate asynchronous tasking, where FILO may be violated, and will thus compenstate for out-of-order popping, however, the perfetto backend will not; thus, out-of-order popping will result in different results in timemory vs. perfetto.

Parameters

id	The string identifier for the region

Returns

omnitrace_user_error_t value

◆ omnitrace_user_progress()

int omnitrace_user_progress

(

const char *

)

mark causal progress

◆ omnitrace_user_push_annotated_region()

int omnitrace_user_push_annotated_region	(	const char *	,
		omnitrace_annotation_t *	,
		unsigned long
	)

◆ omnitrace_user_push_region()

int omnitrace_user_push_region

(

const char *

id

)

Start a user defined region.

Parameters

id	The string identifier for the region

Returns

omnitrace_user_error_t value

◆ omnitrace_user_start_thread_trace()

int omnitrace_user_start_thread_trace

(

void

)

Enable tracing on this specific thread. Does not apply to subsequently created threads.

Returns

omnitrace_user_error_t value

◆ omnitrace_user_start_trace()

int omnitrace_user_start_trace

(

void

)

Enable tracing on this thread and all subsequently created threads.

Returns

omnitrace_user_error_t value

◆ omnitrace_user_stop_thread_trace()

int omnitrace_user_stop_thread_trace

(

void

)

Disable tracing on this specific thread. Does not apply to subsequently created threads.

Returns

omnitrace_user_error_t value

◆ omnitrace_user_stop_trace()

int omnitrace_user_stop_trace

(

void

)

Disable tracing on this thread and all subsequently created threads.

Returns

omnitrace_user_error_t value