Custom allocator / heap profiler

[matth-x]

Add custom allocation hook functions and a built-in heap profiler.

The new Memory module provides methods for overriding the default C++ allocation and a central malloc / free selector. If enabled via build switches, the allocations will be handled by the Memory module, instead of going to the host system allocator directly. There exist two possible uses:

• Decoration of the host system allocator, e.g. to track and measure allocations
• Replacing the host system allocator by a custom allocator

If the Memory module is not enabled via build switches, then this has no effect on the allocations.

Usage

The following features can be enabled:

• MO_OVERRIDE_ALLOCATION=1: enable routing allocations through the Memory module. The firmware can now set its custom allocator using mo_mem_set_malloc_free(...)
• MO_ENABLE_HEAP_PROFILER=1: track allocations and enable the function MO_MEM_PRINT_STATS() to print heap stats. This feature depends on setting MO_OVERRIDE_ALLOCATION=1.

Changes

The API in MicroOcpp.h / MicroOcpp_c.h didn't change. But if the firmware integration gets beyond the API, then the following changes are relevant:

• std::string has been replaced by MicroOcpp::String which is a typedef of either the same std::string if the Memory module is disabled, or std::basic_string<char, std::char_traits<char>, MicroOcpp::Allocator<char>> if enabled. To construct a String, use makeString(const char *memoryTag) and give it a memory tag which will show up in the heap statistics
• std::vector has been replaced by MicroOcpp::Vector, a typedef of std::vector or std::vector<T, MicroOcpp::Allocator<T>>. Use makeVector(const char *memoryTag)
• And last, DynamicJsonDocument is MicroOcpp::JsonDoc now which becomes DynamicJsonDocument again if the Memory module is off and BasicJsonDocument<ArduinoJsonAllocator> if on

Limitations

This method of redirecting all allocations depends on explicitly changing the allocation everywhere in the code base. It is likely that some allocations have been overlooked and in future changes, it could be forgotten about in some places.

For std::function, it's not really common to replace the internal allocator and therefore it's not well supported by STL implementations. For now, the MO-internal uses of std::function remain unchanged, making them a blind spot of the heap profiler. In future, they should be replaced by classic C-style callback functions for example.

If MO requires system resources (like snprintf) which allocate memory internally, that isn't taken into account. The Memory module can only track explicit allocations inside the MO library.

Example

The example output of running all unit tests looks like this:

 *** Heap usage statistics ***
Context - 0 B (max. 744 B)
EmptyJsonDoc - 0 B (max. 0 B)
Filesystem - 0 B (max. 88 B)
FilesystemIndex - 0 B (max. 1282 B)
Model - 0 B (max. 206 B)
OperationRegistry - 0 B (max. 4992 B)
Request - 0 B (max. 4914 B)
RequestQueue - 0 B (max. 14209 B)
Timestamp - 0 B (max. 32 B)
UnitTests - 0 B (max. 4096 B)
v16.Authorization.AuthorizationData - 0 B (max. 21 B)
v16.Authorization.AuthorizationList - 0 B (max. 584 B)
v16.Authorization.AuthorizationService - 0 B (max. 1472 B)
v16.Boot.BootService - 0 B (max. 949 B)
v16.Configuration.AllowOfflineTxForUnknownId - 0 B (max. 72 B)
v16.Configuration.AuthorizeRemoteTxRequests - 0 B (max. 72 B)

[118 more lines]

v16.Transactions.Transaction - 0 B (max. 736 B)
v16.Transactions.TransactionDeserialize - 0 B (max. 1024 B)
v16.Transactions.TransactionStore - 0 B (max. 1856 B)
Blocks: 0
Tags: 137
Current usage: 0 B
Maximum usage: 31544 B

The heap usage at exiting the unit tests is 0 bytes (MO has been deinitalized) and total maximum over all tests was 31544 bytes.