Malloc Count

This Component is a modified version of the original code at https://github.com/bingmann/malloc_count. It is intended to provide basic heap monitoring for the Sming Host Emulator. See Host Heap support.

It is also supported on all architectures to provide more detailed heap allocation diagnostics.

Note

Not supported for host builds on MacOS.

For a sample application see :samples:`Basic_Ssl`.

For Host builds, malloc_count is normally enabled. Use ENABLE_MALLOC_COUNT to control linkage.

To enable for use in a project, add malloc_count to COMPONENT_DEPENDS in component.mk.

Basic usage

Measure allocation

To establish RAM headroom for an application, use MallocCount::getCurrent() and MallocCount::getPeak().

Measure heap activity

Total accumulated heap allocation is returned by MallocCount::getTotal(). Call MallocCount::resetTotal() to clear.

Total number of allocations is returned by MallocCount::getAllocCount().

Restrict available RAM

To test application low-memory behaviour use MallocCount::setAllocLimit(). Calling malloc, new, etc. will return nullptr if total allocation would exceed this value.

Note

Host ONLY

Calling system_get_free_heap_size() will reflect the configured limit.

Logging

Enable debug console output with MallocCount::enableLogging(). By default, single allocations of 256 bytes or more are logged.

Call MallocCount::setLogThreshold() to change this value.

Internal operation

When enabled, standard (architecture-dependent) memory allocation routines are intercepted. Note that for each allocation an additional 16 bytes is consumed for internal use.

Part of this contains a fixed sentinel value which indicates that the memory block was actually allocated by malloc_count.

When malloc_count frees a memory block, it checks this sentinel value and, with logging enabled, outputs a !!! memory corruption? message.

This may indicate memory corruption, which the developer should investigate further: see ENABLE_SANITIZERS.

Another explanation for this is that code somehow bypassed the malloc_count allocator. This indicates an issue with malloc_count itself and an issue should be raised.

API Documentation

namespace MallocCount

Typedefs

using Callback = std::function<void(size_t current)>

Callback function type.

Param current:

Current allocated bytes

Functions

size_t getCurrent(void)

Get the currently allocated amount of memory.

size_t getPeak(void)

Get the peak memory allocation.

void resetPeak(void)

Reset the peak memory allocation to current.

size_t getTotal(void)

Get the total cumulative memory allocation.

void resetTotal(void)

Reset the total cumulative memory allocation to zero.

size_t getAllocCount(void)

Get the total number of allocations.

void setAllocLimit(size_t maxBytes)

Set an allocation limit.

Parameters:

maxBytes – Specify 0 for no limit

size_t getAllocLimit()

Get the configured allocation limit.

Return values:

size_t – Maximum allocation in bytes, 0 for no limit

void setCallback(Callback callback)

Set a callback function that is invoked on each change of the current allocation.

Note

The callback function must not use malloc()/realloc()/free() or it will go into an endless recursive loop!

void enableLogging(bool enable)

Enable/disable logging.

void setLogThreshold(size_t threshold)

Set minimum allocation size for log output (when enabled)

References

Used by

Environment Variables

SoC support

  • esp32

  • esp32c2

  • esp32c3

  • esp32s2

  • esp32s3

  • esp8266

  • host

  • rp2040

  • rp2350