Profiler

The profiler is used to get information about program performance and efficiency.

typedef struct profiler_snapshot profiler_snapshot_t

typedef struct profiler_snapshot_entry profiler_snapshot_entry_t

typedef struct profiler_name_store profiler_name_store_t

typedef struct profiler_time_entry profiler_time_entry_t

#include <util/profiler.h>

Profiler Structures

struct profiler_time_entry

uint64_t profiler_time_entry.time_delta

uint64_t profiler_time_entry.count

Profiler Control Functions

void profiler_start(void): Starts the profiler.

void profiler_stop(void): Stops the profiler.

void profiler_print(profiler_snapshot_t *snap)

Creates a profiler snapshot and saves it within snap.

Parameters

snap – A profiler snapshot object

void profiler_print_time_between_calls(profiler_snapshot_t *snap)

Creates a profiler snapshot of time between calls and saves it within snap.

Parameters

snap – A profiler snapshot object

void profiler_free(void): Frees the profiler.

Profiling Functions

void profile_register_root(const char *name, uint64_t expected_time_between_calls)

Registers a root profile node.

Parameters

name – Name of the root profile node
expected_time_between_calls – The expected time between calls of the profile root node, or 0 if none.

void profile_start(const char *name)

Starts a profile node. This profile node will be a child of the last node that was started.

Parameters

name – Name of the profile node

void profile_end(const char *name)

Parameters

name – Name of the profile node

void profile_reenable_thread(void): Because profiler_start() can be called in a different thread than the current thread, this is used to specify a point where it’s safe to re-enable profiling in the calling thread. Call this when you have looped root profile nodes and need to specify a safe point where the root profile node isn’t active and the profiler can start up in the current thread again.

Profiler Name Storage Functions

profiler_name_store_t *profiler_name_store_create(void)

Creates a profiler name storage object.

Returns: Profiler name store object

void profiler_name_store_free(profiler_name_store_t *store)

Frees a profiler name storage object.

Parameters

store – Profiler name storage object

const char *profile_store_name(profiler_name_store_t *store, const char *format, ...)

Creates a formatted string and stores it within a profiler name storage object.

Parameters

store – Profiler name storage object
format – Formatted string

Returns

The string created from format specifications

Profiler Data Access Functions

profiler_snapshot_t *profile_snapshot_create(void)

Creates a profile snapshot. Profiler snapshots are used to obtain data about how the active profiles performed.

Returns: A profiler snapshot object

void profile_snapshot_free(profiler_snapshot_t *snap)

Frees a profiler snapshot object.

Parameters

snap – A profiler snapshot

bool profiler_snapshot_dump_csv(const profiler_snapshot_t *snap, const char *filename)

Creates a CSV file of the profiler snapshot.

Parameters

snap – A profiler snapshot
filename – The path to the CSV file to save

Returns

true if successfully written, false otherwise

bool profiler_snapshot_dump_csv_gz(const profiler_snapshot_t *snap, const char *filename)

Creates a gzipped CSV file of the profiler snapshot.

Parameters

snap – A profiler snapshot
filename – The path to the gzipped CSV file to save

Returns

true if successfully written, false otherwise

size_t profiler_snapshot_num_roots(profiler_snapshot_t *snap)

Parameters

snap – A profiler snapshot

Returns

Number of root profiler nodes in the snapshot

typedef bool (*profiler_entry_enum_func)(void *context, profiler_snapshot_entry_t *entry)

Profiler snapshot entry numeration callback

Param context: Private data passed to this callback
Param entry: Profiler snapshot entry
Return: true to continue enumeration, false otherwise

void profiler_snapshot_enumerate_roots(profiler_snapshot_t *snap, profiler_entry_enum_func func, void *context)

Enumerates root profile nodes.

Parameters

snap – A profiler snapshot
func – Enumeration callback
context – Private data to pass to the callback

typedef bool (*profiler_name_filter_func)(void *data, const char *name, bool *remove)

Callback used to determine what profile nodes are removed/filtered.

Param data: Private data passed to this callback
Param name: Profile node name to be filtered
Param remove: Used to determined whether the node should be removed or not
Return: true to continue enumeration, false otherwise

void profiler_snapshot_filter_roots(profiler_snapshot_t *snap, profiler_name_filter_func func, void *data)

Removes/filters profile roots based upon their names.

Parameters

snap – A profiler snapshot
func – Enumeration callback to filter with
data – Private data to pass to the callback

size_t profiler_snapshot_num_children(profiler_snapshot_entry_t *entry)

Parameters

entry – A profiler snapshot entry

Returns

Number of children for the entry

void profiler_snapshot_enumerate_children(profiler_snapshot_entry_t *entry, profiler_entry_enum_func func, void *context)

Enumerates child entries of a profiler snapshot entry.

Parameters

entry – A profiler snapshot entry
func – Enumeration callback
context – Private data passed to the callback

const char *profiler_snapshot_entry_name(profiler_snapshot_entry_t *entry)

Parameters

entry – A profiler snapshot entry

Returns

The name of the profiler snapshot entry

profiler_time_entries_t *profiler_snapshot_entry_times(profiler_snapshot_entry_t *entry)

Gets the time entries for a snapshot entry.

Parameters

entry – A profiler snapshot entry

Returns

An array of profiler time entries

uint64_t profiler_snapshot_entry_min_time(profiler_snapshot_entry_t *entry)

Gets the minimum time for a profiler snapshot entry.

Parameters

entry – A profiler snapshot entry

Returns

The minimum time value for the snapshot entry

uint64_t profiler_snapshot_entry_max_time(profiler_snapshot_entry_t *entry)

Gets the maximum time for a profiler snapshot entry.

Parameters

entry – A profiler snapshot entry

Returns

The maximum time value for the snapshot entry

uint64_t profiler_snapshot_entry_overall_count(profiler_snapshot_entry_t *entry)

Gets the overall count for a profiler snapshot entry.

Parameters

entry – A profiler snapshot entry

Returns

The overall count value for the snapshot entry

profiler_time_entries_t *profiler_snapshot_entry_times_between_calls(profiler_snapshot_entry_t *entry)

Gets an array of time between calls for a profiler snapshot entry.

Parameters

entry – A profiler snapshot entry

Returns

An array of profiler time entries

uint64_t profiler_snapshot_entry_expected_time_between_calls(profiler_snapshot_entry_t *entry)

Gets the expected time between calls for a profiler snapshot entry.

Parameters

entry – A profiler snapshot entry

Returns

The expected time between calls for the snapshot entry, or 0 if not set

uint64_t profiler_snapshot_entry_min_time_between_calls(profiler_snapshot_entry_t *entry)

Gets the minimum time seen between calls for a profiler snapshot entry.

Parameters

entry – A profiler snapshot entry

Returns

The minimum time seen between calls for the snapshot entry

uint64_t profiler_snapshot_entry_max_time_between_calls(profiler_snapshot_entry_t *entry)

Gets the maximum time seen between calls for a profiler snapshot entry.

Parameters

entry – A profiler snapshot entry

Returns

The maximum time seen between calls for the snapshot entry

uint64_t profiler_snapshot_entry_overall_between_calls_count(profiler_snapshot_entry_t *entry)

Gets the overall time between calls for a profiler snapshot entry.

Parameters

entry – A profiler snapshot entry

Returns

The overall time between calls for the snapshot entry