cpubench

Marks phases of a program so dis_cpu_usage can report the CPU usage of each phase. See Measuring CPU usage for examples.

Hint

This page describes features that were added in DIS 5.28.0. Linux only.

Include cpubench.h from /opt/DIS/include and link with -L/opt/DIS/lib64 -lcpubench.

A row is one measured phase, identified by a key the caller chooses. A row object is used by one thread at a time and can be started and stopped any number of times.

Types

type cpubench_row_t

Opaque row object.

CPUBENCH_ROW_THREAD

Flag for cpubench_row_create(): measure the calling thread instead of the whole process.

Functions

cpubench_row_t *cpubench_row_create(unsigned int flags)

Creates a row object. flags is 0 for process scope or CPUBENCH_ROW_THREAD.

Returns NULL if flags is invalid or memory can’t be allocated.

void cpubench_row_destroy(cpubench_row_t *row)

Frees a row object. A row that is still open is not reported.

int cpubench_row_start(cpubench_row_t *row, uint64_t key)

Opens a row with the given key.

Returns 0 on success, -1 if the row is already open or the start CPU time can’t be read. A row that failed to start is still opened, and is reported as n/a once stopped.

int cpubench_row_stop(cpubench_row_t *row)

Closes the row and hands its CPU time to dis_cpu_usage, if running.

Returns 0 on success, -1 if the row isn’t open, the times can’t be read, or a CPUBENCH_ROW_THREAD row is stopped on another thread. Failed rows are reported as n/a.

int cpubench_traced(void)

Returns 1 if the program runs under dis_cpu_usage, 0 otherwise.

Notes

• Rows with the same key are added together.

• Rows may be open at the same time, with the same or different keys, as long as each uses its own row object. This also holds across processes, for example a row object copied by fork(). A row object can only be open once.

• Process scope includes threads the SISCI library creates for callbacks.

• Without dis_cpu_usage, start and stop cost two getrusage() calls per row and nothing is reported.