instrument.c File Reference

#include "instrument.h"
#include "instrument_internal.h"
#include "yac_assert.h"
#include "utils_common.h"

Include dependency graph for instrument.c:

Go to the source code of this file.

Data Structures
struct	yac_region_state
	State of a single instrumented region ID. More...
struct	yac_region_open_frame
	Frame of an open instrumented region. More...

Macros
#define	X(id, str)   {.name = str, .type = (int)YAC_INSTR_##id},
#define	CHECK_REGION_ID(id)
#define	INSTR_IS_ACTIVE()   (yac_free_frame != NULL)
#define	INSTR_DEPTH()   (int)(yac_free_frame - yac_region_open)
#define	INSTR_HAS_OPEN()   (yac_free_frame != yac_region_open)
#define	INSTR_INNERMOST_OPEN()   (yac_free_frame - 1)

Functions
static char const *	yac_region_name (yac_instrument_region_id id)
static void	yac_instrument_open_frame_reset (yac_region_open_frame *frame)
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)
const char *	yac_instrument_region_name_f2c (int id)
void	yac_instrument_start_impl (yac_instrument_region_id id, char const *file, int line)
	Start an instrumented region. Do not call directly — use the YAC_INSTRUMENT_START macro below, which supplies the source location.
void	yac_instrument_stop_impl (yac_instrument_region_id id, char const *file, int line)
	Stop an instrumented region. Do not call directly — use the YAC_INSTRUMENT_STOP macro below, which supplies the source location.

Variables
static struct yac_name_type_pair const	yac_region_name_type_pair []
static yac_region_state	yac_region [YAC_INSTR_REGION_COUNT]
static yac_region_open_frame	yac_region_open [YAC_INSTR_REGION_COUNT]
static yac_instrument_create_cb	yac_create_cb = NULL
static yac_instrument_start_cb	yac_start_cb = NULL
static yac_instrument_stop_cb	yac_stop_cb = NULL
static yac_instrument_destroy_cb	yac_destroy_cb = NULL
static void *	yac_user_data = NULL
static yac_region_open_frame *	yac_free_frame = NULL

Macro Definition Documentation

CHECK_REGION_ID

#define CHECK_REGION_ID

(

id

)

Value:

  YAC_ASSERT_F( \
    (int)(id) >= 0 && (int)(id) < YAC_INSTR_REGION_COUNT, \
    "invalid instrumentation region id %d", (int)(id))

Definition at line 23 of file instrument.c.

INSTR_DEPTH

#define INSTR_DEPTH

(

)

(int)(yac_free_frame - yac_region_open)

Definition at line 87 of file instrument.c.

INSTR_HAS_OPEN

#define INSTR_HAS_OPEN

(

)

(yac_free_frame != yac_region_open)

Definition at line 88 of file instrument.c.

INSTR_INNERMOST_OPEN

#define INSTR_INNERMOST_OPEN

(

)

(yac_free_frame - 1)

Definition at line 89 of file instrument.c.

INSTR_IS_ACTIVE

#define INSTR_IS_ACTIVE

(

)

(yac_free_frame != NULL)

Helper macros for checking the instrumentation state.

Definition at line 86 of file instrument.c.

X

#define X	(		id,
			str )   {.name = str, .type = (int)YAC_INSTR_##id},

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_open_frame_reset()

static void yac_instrument_open_frame_reset ( yac_region_open_frame * frame )

static

Definition at line 91 of file instrument.c.

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_region_name_f2c()

const char * yac_instrument_region_name_f2c

(

int

id

)

Definition at line 162 of file instrument.c.

Here is the call 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:

yac_instrument_start_impl()

void yac_instrument_start_impl	(	yac_instrument_region_id	id,
		char const *	file,
		int	line )

Start an instrumented region. Do not call directly — use the YAC_INSTRUMENT_START macro below, which supplies the source location.

Parameters

id	The ID of the instrumented region to start.
file	Source file of the call (for diagnostics).
line	Source line of the call (for diagnostics).

Remarks

This function is not thread-safe and should not be called concurrently from multiple threads (e.g. from within an OpenMP parallel region).

Nesting of the same region ID is not allowed. If a region is started while already active — which also happens if a prior YAC_INSTRUMENT_STOP for it was skipped, e.g. by an early return — an assertion is triggered, reporting where the still-open region was started.

Definition at line 171 of file instrument.c.

Here is the call graph for this function:

yac_instrument_stop_impl()

void yac_instrument_stop_impl	(	yac_instrument_region_id	id,
		char const *	file,
		int	line )

Stop an instrumented region. Do not call directly — use the YAC_INSTRUMENT_STOP macro below, which supplies the source location.

Parameters

id	The ID of the instrumented region to stop.
file	Source file of the call (for diagnostics).
line	Source line of the call (for diagnostics).

Remarks

This function is not thread-safe and should not be called concurrently from multiple threads (e.g. from within an OpenMP parallel region).

If the region is not the innermost currently-open one — which also happens if a YAC_INSTRUMENT_STOP for a more recently started region was skipped, e.g. by an early return — an assertion is triggered.

Definition at line 214 of file instrument.c.

Here is the call graph for this function:

yac_region_name()

static char const * yac_region_name ( yac_instrument_region_id id )

static

Definition at line 28 of file instrument.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

yac_create_cb

yac_instrument_create_cb yac_create_cb = NULL

static

Definition at line 69 of file instrument.c.

yac_destroy_cb

yac_instrument_destroy_cb yac_destroy_cb = NULL

static

Definition at line 72 of file instrument.c.

yac_free_frame

yac_region_open_frame* yac_free_frame = NULL

static

Points at the next free slot in yac_region_open, i.e. one past the innermost open region. NULL means instrumentation is disabled (no callbacks registered); otherwise the current nesting depth is (yac_free_frame - yac_region_open), and yac_free_frame == yac_region_open means active with no region currently open.

Definition at line 81 of file instrument.c.

yac_region

yac_region_state yac_region[YAC_INSTR_REGION_COUNT]

static

Definition at line 65 of file instrument.c.

yac_region_name_type_pair

struct yac_name_type_pair const yac_region_name_type_pair[]

static

Initial value:

= {
#define X(id, str)                                            
  YAC_INSTRUMENT_REGION_TABLE
 
  {.name = "total number of instrumented regions",
   .type = (int)YAC_INSTR_REGION_COUNT}
}

Definition at line 15 of file instrument.c.

yac_region_open

yac_region_open_frame yac_region_open[YAC_INSTR_REGION_COUNT]

static

Definition at line 66 of file instrument.c.

yac_start_cb

yac_instrument_start_cb yac_start_cb = NULL

static

Definition at line 70 of file instrument.c.

yac_stop_cb

yac_instrument_stop_cb yac_stop_cb = NULL

static

Definition at line 71 of file instrument.c.

yac_user_data

void* yac_user_data = NULL

static

Definition at line 73 of file instrument.c.