latest/source/lib/omnitrace-user/omnitrace/user.h File Reference

latest/source/lib/omnitrace-user/omnitrace/user.h File Reference#

omnitrace: latest/source/lib/omnitrace-user/omnitrace/user.h File Reference
user.h File Reference

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]modeSpecifies how the new callbacks are merged with the old callbacks
[in]inpAn omnitrace_user_callbacks instance specifying the callbacks which should be invoked by the user API.
[out]outPointer 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_categoryOMNITRACE_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
idThe 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
idThe 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