Time Profiler

[中文]

Public header: #include "brookesia/lib_utils/time_profiler.hpp"

Overview

time_profiler provides hierarchical timing for scopes and events to locate bottlenecks and hot paths.

Features

  • Scope and event timing models

  • Hierarchical reports with customizable output

  • Per-thread sampling

  • Convenience macros for instrumentation

Warning

On ESP32-P4 with CONFIG_SPIRAM_XIP_FROM_PSRAM=y, time_profiler may crash the system.

API Reference

Header File

Classes

class TimeProfiler

Hierarchical time profiler for scoped code regions and named events.

This class provides hierarchical time profiling capabilities with support for nested scopes, cross-thread events, and detailed statistics reporting.

Public Functions

void set_format_options(const FormatOptions &options)

Set formatting options used by report().

Parameters

options – [in] Format options to apply.

void enter_scope(const std::string &name)

Enter a named profiling scope.

Should be paired with leave_scope(). Prefer using BROOKESIA_TIME_PROFILER_SCOPE macro for automatic scope management.

Parameters

name – [in] Scope name to record.

void leave_scope()

Leave the current profiling scope.

Records the elapsed time since the matching enter_scope() call.

void start_event(const std::string &name)

Start timing a named event.

Used for timing events that may span across function boundaries or threads. Must be paired with end_event() with the same name.

Parameters

name – [in] Event name to start.

void end_event(const std::string &name)

End timing a named event.

Records the elapsed time since the corresponding start_event() call.

Parameters

name – [in] Event name to stop.

Statistics get_statistics() const

Build a structured snapshot of the collected profiling data.

Returns a structured representation of all profiling data.

Returns

Statistics structure containing all profiling information.

void report()

Generate and log a formatted profiling report.

Prints a hierarchical report of all recorded timings to the log. This method internally calls get_statistics() and formats the output.

void clear()

Clear all recorded profiling data.

Resets all timing statistics and clears the profiling tree.

Public Static Functions

static inline TimeProfiler &get_instance()

Get the singleton instance of TimeProfiler.

Returns

Reference to the singleton TimeProfiler instance

struct FormatOptions

Formatting options used by report().

Public Types

enum class SortBy

Sort order for sibling profiling nodes.

Values:

enumerator TotalDesc

Sort by total time descending.

enumerator NameAsc

Sort by name ascending.

enumerator None

No sorting.

enum class TimeUnit

Time unit used for formatted output and exported statistics.

Values:

enumerator Microseconds

Display in microseconds.

enumerator Milliseconds

Display in milliseconds.

enumerator Seconds

Display in seconds.

Public Members

int name_width = 32

Width of name column.

int calls_width = 6

Width of calls column.

int num_width = 10

Width of numeric columns.

int percent_width = 7

Width of percentage column.

int precision = 2

Decimal precision for numbers.

bool use_unicode = false

Use ASCII characters to ensure alignment.

bool show_percentages = true

Show percentage columns.

bool use_color = false

Use ANSI color codes in output.

SortBy sort_by = SortBy::TotalDesc

Sort order for output.

TimeUnit time_unit = TimeUnit::Milliseconds

Time unit for display.

struct Node

Internal tree node representing one profiled scope.

Public Members

std::string name

Name of this profiling scope.

double total = 0.0

Total time spent in this scope.

size_t count = 0

Number of times this scope was entered.

double min = std::numeric_limits<double>::infinity()

Minimum time recorded.

double max = 0.0

Maximum time recorded.

std::map<std::string, std::unique_ptr<Node>> children

Child scopes.

Node *parent = nullptr

Parent scope.

struct NodeStatistics

Aggregated statistics for a single profiling node.

Public Members

std::string name

Name of the profiling scope.

size_t count = 0

Number of times this scope was entered.

double total = 0.0

Total time spent in this scope.

double self_time = 0.0

Time spent in this scope excluding children.

double avg = 0.0

Average time per call.

double min = 0.0

Minimum time recorded.

double max = 0.0

Maximum time recorded.

double pct_parent = 0.0

Percentage of parent’s total time.

double pct_total = 0.0

Percentage of overall total time.

std::vector<NodeStatistics> children

Child node statistics.

struct Statistics

Structured report returned by get_statistics().

Public Members

std::string unit_name

Time unit name (e.g., “ms”, “us”, “s”)

double overall_total = 0.0

Overall total time.

std::vector<NodeStatistics> root_children

Root level node statistics.

class TimeProfilerScope

RAII wrapper that profiles the lifetime of a C++ scope.

Automatically calls enter_scope() on construction and leave_scope() on destruction. Use the BROOKESIA_TIME_PROFILER_SCOPE macro for convenient usage.

Public Functions

explicit TimeProfilerScope(const std::string &name)

Enter a named profiling scope on construction.

Parameters

name – [in] Scope name to record.

~TimeProfilerScope()

Leave the profiling scope on destruction.

Macros

_BROOKESIA_TIME_PROFILER_CONCAT(a, b)
BROOKESIA_TIME_PROFILER_CONCAT(a, b)
BROOKESIA_TIME_PROFILER_SCOPE(name)
BROOKESIA_TIME_PROFILER_START_EVENT(name)
BROOKESIA_TIME_PROFILER_END_EVENT(name)
BROOKESIA_TIME_PROFILER_REPORT()
BROOKESIA_TIME_PROFILER_CLEAR()