时间分析器

[English]

公共头文件： #include "brookesia/lib_utils/time_profiler.hpp"

概述

time_profiler 提供层级化的时间分析能力，可记录作用域与事件耗时， 帮助定位性能瓶颈与热点路径。

特性

  • 支持作用域与事件两类计时模型

  • 生成层级化统计报告，支持自定义输出格式

  • 支持线程内的独立采样与统计

  • 提供便捷宏快速接入分析点

警告

当 ESP32-P4 开启 CONFIG_SPIRAM_XIP_FROM_PSRAM=y 时， time_profiler 功能可能导致系统崩溃。

API 参考

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

参数

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.

参数

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.

参数

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.

参数

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.

返回

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.

返回

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.

参数

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