Memory Profiler

[中文]

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

Overview

memory_profiler samples heap usage, tracks peaks, and supports threshold alerts for runtime memory monitoring.

Features

  • Current heap, historical peak, and statistics

  • Periodic profiling and manual snapshots

  • Threshold callbacks when limits are exceeded

  • Optional integration with TaskScheduler for periodic sampling

API Reference

Header File

Classes

class MemoryProfiler

Heap memory profiler for internal RAM and PSRAM usage.

This class provides a C++ interface to monitor ESP32 heap memory usage, including internal SRAM and external PSRAM. It integrates naturally with TaskScheduler for periodic profiling.

Public Types

enum class ThresholdType

Metric used when registering threshold callbacks.

Values:

enumerator TotalFree

Total free memory in bytes.

enumerator InternalFree

Internal SRAM free memory in bytes.

enumerator ExternalFree

External PSRAM free memory in bytes.

enumerator TotalFreePercent

Total free memory as a percentage.

enumerator InternalFreePercent

Internal SRAM free memory as a percentage.

enumerator ExternalFreePercent

External PSRAM free memory as a percentage.

enumerator TotalLargestFreeBlock

Largest free block across all heaps, in bytes.

enumerator InternalLargestFreeBlock

Largest internal SRAM free block, in bytes.

enumerator ExternalLargestFreeBlock

Largest external PSRAM free block, in bytes.

enumerator MinTotalFree

Minimum total free memory in bytes.

enumerator MinInternalFree

Minimum internal SRAM free memory in bytes.

enumerator MinExternalFree

Minimum external PSRAM free memory in bytes.

enumerator MinTotalFreePercent

Minimum total free memory as a percentage.

enumerator MinInternalFreePercent

Minimum internal SRAM free memory as a percentage.

enumerator MinExternalFreePercent

Minimum external PSRAM free memory as a percentage.

enumerator MinTotalLargestFreeBlock

Minimum largest free block across all heaps, in bytes.

enumerator MinInternalLargestFreeBlock

Minimum largest internal SRAM free block, in bytes.

enumerator MinExternalLargestFreeBlock

Minimum largest external PSRAM free block, in bytes.

using ProfilingSignal = boost::signals2::signal<void(const ProfileSnapshot&)>

Signal type emitted for each profiling snapshot.

using ProfilingSignalSlot = ProfilingSignal::slot_type

Slot type accepted by connect_profiling_signal().

using ThresholdSignal = boost::signals2::signal<void(const ProfileSnapshot&)>

Signal type emitted when a threshold condition is met.

using ThresholdSignalSlot = ThresholdSignal::slot_type

Slot type accepted by connect_threshold_signal().

using SignalConnection = boost::signals2::scoped_connection

Signal connection type.

Note

This is an RAII smart handle for managing the lifetime of callbacks. When this object is destroyed, the corresponding callback is automatically disconnected. It is recommended to use std::move() to transfer ownership for manual management of the connection lifetime.

Public Functions

MemoryProfiler() = default

Construct an idle memory profiler.

MemoryProfiler(const MemoryProfiler&) = delete

Copy construction is not supported.

MemoryProfiler &operator=(const MemoryProfiler&) = delete

Copy assignment is not supported.

MemoryProfiler(MemoryProfiler&&) = delete

Move construction is not supported.

MemoryProfiler &operator=(MemoryProfiler&&) = delete

Move assignment is not supported.

bool configure_profiling(const ProfilingConfig &config)

Update the profiling configuration.

Parameters

config – New profiler configuration.

Returns

true after the configuration is stored.

inline ProfilingConfig get_profiling_config() const

Get the current profiling configuration.

Returns

Active ProfilingConfig.

bool start_profiling(std::shared_ptr<TaskScheduler> scheduler, uint32_t period_ms = 0)

Start periodic profiling with a task scheduler.

Parameters

  • scheduler – Scheduler used to execute periodic sampling.

  • period_ms – Sampling period in milliseconds. Pass 0 to use config.sample_interval_ms.

Returns

true on success, or false if startup fails.

void stop_profiling()

Stop periodic profiling.

void reset_profiling()

Reset captured snapshots and registered callbacks without changing configuration.

inline bool is_profiling() const

Check whether periodic profiling is active.

Returns

true when a profiling task is active, or false otherwise.

inline std::shared_ptr<ProfileSnapshot> get_profiling_latest_snapshot() const

Get the latest captured snapshot.

Returns

Shared pointer to the latest snapshot, or nullptr if no snapshot is available.

SignalConnection connect_profiling_signal(ProfilingSignalSlot slot)

Subscribe to every profiling snapshot.

Parameters

slot – Callback invoked whenever a new snapshot is produced.

Returns

RAII connection handle for the registered callback.

SignalConnection connect_threshold_signal(ThresholdType type, uint32_t threshold_value, ThresholdSignalSlot slot)

Subscribe to threshold events for a specific metric.

Parameters

  • type – Metric to monitor.

  • threshold_value – Threshold value interpreted according to type.

  • slot – Callback invoked when the threshold is met by a snapshot.

Returns

RAII connection handle for the registered callback.

Public Static Functions

static inline MemoryProfiler &get_instance()

Get the process-wide singleton instance.

Returns

Reference to the singleton profiler.

static std::shared_ptr<ProfileSnapshot> take_snapshot(ProfileSnapshot *last_snapshot = nullptr)

Capture the current memory state.

Parameters

last_snapshot – Previous snapshot used to update running statistics, or nullptr for the first sample.

Returns

Shared pointer to the new snapshot, or nullptr if allocation fails.

static void print_snapshot(const ProfileSnapshot &snapshot)

Print a formatted snapshot summary to the log.

Parameters

snapshot – Snapshot to print.

struct HeapInfo

Snapshot of a single heap region.

Public Members

size_t total_size = 0

Total heap size in bytes.

size_t free_size = 0

Free heap size in bytes.

size_t largest_free_block = 0

Size of the largest free block in bytes.

size_t free_percent = 0

Free memory ratio expressed as a percentage.

size_t used_percent = 0

Used memory ratio expressed as a percentage.

struct MemoryInfo

Aggregated memory information for all monitored heap regions.

Public Members

HeapInfo internal

Internal SRAM heap information (MALLOC_CAP_INTERNAL).

HeapInfo external

External PSRAM heap information (MALLOC_CAP_SPIRAM).

size_t total_size = 0

Total heap size in bytes across all monitored heaps.

size_t total_free = 0

Total free memory in bytes across all monitored heaps.

size_t total_free_percent = 0

Total free memory ratio expressed as a percentage.

size_t total_largest_free_block = 0

Largest free block in bytes across all monitored heaps.

struct ProfileSnapshot

Memory profile snapshot captured at one point in time.

Public Members

std::chrono::system_clock::time_point timestamp

Snapshot capture time.

MemoryInfo memory

Instantaneous memory information.

Statistics stats

Running statistics after this snapshot.

struct ProfilingConfig

Configuration for periodic memory profiling.

Public Members

uint32_t sample_interval_ms = 5000

Sampling interval in milliseconds.

bool enable_auto_logging = true

Whether to log each generated snapshot automatically.

struct Statistics

Running minimum statistics accumulated across snapshots.

Public Members

size_t sample_count = 0

Number of snapshots processed.

size_t min_total_free = 0

Minimum total free memory observed, in bytes.

size_t min_internal_free = 0

Minimum internal free memory observed, in bytes.

size_t min_external_free = 0

Minimum external free memory observed, in bytes.

size_t min_total_free_percent = 0

Minimum total free percentage observed.

size_t min_internal_free_percent = 0

Minimum internal free percentage observed.

size_t min_external_free_percent = 0

Minimum external free percentage observed.

size_t min_total_largest_free_block = 0

Minimum total largest free block observed, in bytes.

size_t min_internal_largest_free_block = 0

Minimum internal largest free block observed, in bytes.

size_t min_external_largest_free_block = 0

Minimum external largest free block observed, in bytes.