instrument.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	YAC_INSTRUMENT_REGION_TABLE
#define	X(id, name)   YAC_INSTR_##id,

Typedefs
typedef void *(*	yac_instrument_create_cb) (int id, void *user_data)
typedef void(*	yac_instrument_start_cb) (int id, void *region_handle, int depth, void *user_data)
typedef void(*	yac_instrument_stop_cb) (int id, void *region_handle, int depth, void *user_data)
typedef void(*	yac_instrument_destroy_cb) (int id, void *region_handle, void *user_data)

Enumerations
enum	yac_instrument_region_id { YAC_INSTR_REGION_COUNT }

Functions
void	yac_instrument_set_callbacks (yac_instrument_create_cb create_cb, yac_instrument_start_cb start_cb, yac_instrument_stop_cb stop_cb, yac_instrument_destroy_cb destroy_cb, void *user_data)
void	yac_instrument_clear_callbacks (void)
const char *	yac_instrument_region_name (yac_instrument_region_id id)

Macro Definition Documentation

X

#define X	(		id,
			name )   YAC_INSTR_##id,

Definition at line 54 of file instrument.h.

YAC_INSTRUMENT_REGION_TABLE

#define YAC_INSTRUMENT_REGION_TABLE

Definition at line 10 of file instrument.h.

Typedef Documentation

yac_instrument_create_cb

typedef void *(* yac_instrument_create_cb) (int id, void *user_data)

Called once per region ID, the first time it is entered (lazy registration). Return value is opaque to YAC; handed back unchanged on every subsequent start/stop for that ID.

Parameters

[in]	id	The region ID being entered.
[in]	user_data	The user_data pointer passed to yac_instrument_set_callbacks.

Returns

An opaque handle for this region ID, to be passed to the start/stop callbacks.

Remarks

This function will not be called concurrently from multiple threads (e.g. from within an OpenMP parallel region).

Definition at line 72 of file instrument.h.

yac_instrument_destroy_cb

typedef void(* yac_instrument_destroy_cb) (int id, void *region_handle, void *user_data)

Called when a region is destroyed.

Parameters

[in]	id	The region ID being destroyed.
[in]	region_handle	The opaque handle returned by the create callback for this region ID.
[in]	user_data	The user_data pointer passed to yac_instrument_set_callbacks.

Remarks

This function will not be called concurrently from multiple threads (e.g. from within an OpenMP parallel region).

Definition at line 116 of file instrument.h.

yac_instrument_start_cb

typedef void(* yac_instrument_start_cb) (int id, void *region_handle, int depth, void *user_data)

Called when a region is entered.

Parameters

[in]	id	The region ID being entered.
[in]	region_handle	The opaque handle returned by the create callback for this region ID.
[in]	depth	The nesting level of this region.
[in]	user_data	The user_data pointer passed to yac_instrument_set_callbacks.

Remarks

This function will not be called concurrently from multiple threads (e.g. from within an OpenMP parallel region).

Definition at line 85 of file instrument.h.

yac_instrument_stop_cb

typedef void(* yac_instrument_stop_cb) (int id, void *region_handle, int depth, void *user_data)

Called when a region is exited.

Parameters

[in]	id	The region ID being exited.
[in]	region_handle	The opaque handle returned by the create callback for this region ID.
[in]	depth	The nesting level of this region.
[in]	user_data	The user_data pointer passed to yac_instrument_set_callbacks.

Remarks

This function will not be called concurrently from multiple threads (e.g. from within an OpenMP parallel region).

Definition at line 101 of file instrument.h.

Enumeration Type Documentation

yac_instrument_region_id

enum yac_instrument_region_id

Enumerator
YAC_INSTR_REGION_COUNT

Definition at line 53 of file instrument.h.

Function Documentation

yac_instrument_clear_callbacks()

void yac_instrument_clear_callbacks

(

void

)

Clear all registered callbacks. Should be called by the user, if callbacks were set before with yac_instrument_set_callbacks, to avoid dangling pointers when the user-defined callbacks are no longer valid. Will call the destroy callback for all region IDs that were created, if a destroy callback was set. No open regions are allowed when this function is called, otherwise an assertion will be triggered.

Definition at line 149 of file instrument.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_instrument_region_name()

const char * yac_instrument_region_name

(

yac_instrument_region_id

id

)

Human-readable name for a region ID, e.g. for logging by a tool that doesn't use create_cb.

Definition at line 154 of file instrument.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_instrument_set_callbacks()

void yac_instrument_set_callbacks	(	yac_instrument_create_cb	create_cb,
		yac_instrument_start_cb	start_cb,
		yac_instrument_stop_cb	stop_cb,
		yac_instrument_destroy_cb	destroy_cb,
		void *	user_data )

Register callbacks for instrumentation. If at least one of start_cb or stop_cb is provided, instrumentation is enabled. If both are NULL, instrumentation is disabled and all other callbacks/user_data must be NULL as well. Violating this will trigger an assertion.

If instrumentation was enabled before this call, the destroy callback will be called for all region IDs that were created, if a destroy callback was set. Additionally, it will be checked that no regions are currently active/open, because changing the callbacks while regions are active would leave the instrumentation state inconsistent and could lead to memory leaks (e.g. if the destroy callback is changed while regions are still active, the handles owned by the previous registration would never be destroyed).

Remarks

This function will not be called concurrently from multiple threads (e.g. from within an OpenMP parallel region).

Definition at line 97 of file instrument.c.

Here is the call graph for this function:

Here is the caller graph for this function: