docs-6.3.1/source/lib/rocprof-sys-user/rocprofiler-systems/user.h File Reference

• docs-6.3.1
• source
• lib
• rocprof-sys-user
• rocprofiler-systems

Functions

user.h File Reference

#include "rocprofiler-systems/categories.h"
#include "rocprofiler-systems/types.h"

Go to the source code of this file.

Functions
int	rocprofsys_user_start_trace (void)
	Enable tracing on this thread and all subsequently created threads. More...
int	rocprofsys_user_stop_trace (void)
	Disable tracing on this thread and all subsequently created threads. More...
int	rocprofsys_user_start_thread_trace (void)
	Enable tracing on this specific thread. Does not apply to subsequently created threads. More...
int	rocprofsys_user_stop_thread_trace (void)
	Disable tracing on this specific thread. Does not apply to subsequently created threads. More...
int	rocprofsys_user_push_region (const char *)
	Start a user defined region. More...
int	rocprofsys_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	rocprofsys_user_push_annotated_region (const char *, rocprofsys_annotation_t *, unsigned long)
int	rocprofsys_user_pop_annotated_region (const char *, rocprofsys_annotation_t *, unsigned long)
int	rocprofsys_user_progress (const char *)
	mark causal progress More...
int	rocprofsys_user_annotated_progress (const char *, rocprofsys_annotation_t *, unsigned long)
	mark causal progress with annotations More...
int	rocprofsys_user_configure (rocprofsys_user_configure_mode_t mode, rocprofsys_user_callbacks_t inp, rocprofsys_user_callbacks_t *out)
	Configure the function pointers invoked by the rocprof-sys user API. The initial callbacks are set via the rocprof-sys-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	rocprofsys_user_get_callbacks (rocprofsys_user_callbacks_t *)
const char *	rocprofsys_user_error_string (int)
	Return a descriptor for the provided error code. More...

Function Documentation

◆ rocprofsys_user_annotated_progress()

int rocprofsys_user_annotated_progress	(	const char *	,
		rocprofsys_annotation_t *	,
		unsigned long
	)

mark causal progress with annotations

◆ rocprofsys_user_configure()

int rocprofsys_user_configure	(	rocprofsys_user_configure_mode_t	mode,
		rocprofsys_user_callbacks_t	inp,
		rocprofsys_user_callbacks_t *	out
	)

Configure the function pointers invoked by the rocprof-sys user API. The initial callbacks are set via the rocprof-sys-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 rocprofsys_user_callbacks instance specifying the callbacks which should be invoked by the user API.
[out]	out	Pointer to rocprofsys_user_callbacks which, when non-NULL, will be assigned the former callbacks.

Returns

rocprofsys_user_error_t value

◆ rocprofsys_user_error_string()

const char * rocprofsys_user_error_string

(

int

error_category

)

Return a descriptor for the provided error code.

Parameters

error_category

ROCPROFSYS_USER_ERROR value

Returns

String descripting the error code

◆ rocprofsys_user_get_callbacks()

int rocprofsys_user_get_callbacks

(

rocprofsys_user_callbacks_t *

)

◆ rocprofsys_user_pop_annotated_region()

int rocprofsys_user_pop_annotated_region	(	const char *	,
		rocprofsys_annotation_t *	,
		unsigned long
	)

◆ rocprofsys_user_pop_region()

int rocprofsys_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

rocprofsys_user_error_t value

◆ rocprofsys_user_progress()

int rocprofsys_user_progress

(

const char *

)

mark causal progress

◆ rocprofsys_user_push_annotated_region()

int rocprofsys_user_push_annotated_region	(	const char *	,
		rocprofsys_annotation_t *	,
		unsigned long
	)

◆ rocprofsys_user_push_region()

int rocprofsys_user_push_region

(

const char *

id

)

Start a user defined region.

Parameters

id	The string identifier for the region

Returns

rocprofsys_user_error_t value

◆ rocprofsys_user_start_thread_trace()

int rocprofsys_user_start_thread_trace

(

void

)

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

Returns

rocprofsys_user_error_t value

◆ rocprofsys_user_start_trace()

int rocprofsys_user_start_trace

(

void

)

Enable tracing on this thread and all subsequently created threads.

Returns

rocprofsys_user_error_t value

◆ rocprofsys_user_stop_thread_trace()

int rocprofsys_user_stop_thread_trace

(

void

)

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

Returns

rocprofsys_user_error_t value

◆ rocprofsys_user_stop_trace()

int rocprofsys_user_stop_trace

(

void

)

Disable tracing on this thread and all subsequently created threads.

Returns

rocprofsys_user_error_t value