Heaptrace Module¶

Since	Origin / Contributor	Maintainer	Source
2021-09-16	Johny Mattsson	Johny Mattsson	heaptrace.c

The heaptrace module is a debug aid for diagnosing heap allocations and leaks thereof. It provides an interface to the built-in heap tracing support in the IDF, enabling interactive heap tracing from the Lua command line.

To use this module, "standalone" heap tracing must be enabled in Kconfig first. This setting is found (at the time of writing) under "Component config" > "Heap memory debugging" > "Heap tracing". The depth of the call chain to capture can also be configured there. It can be very beneficial to set that to its max, but it comes at significantly increased memory requirements in turn.

A typical sequence of commands for a heap tracing session will be:

heaptrace.init(200) -- your needed buffer size will depend on your use case
collectgarbage() -- start with as clean a slate as possible
heaptrace.start(heaptrace.TRACE_LEAKS) -- start in leak tracing mode
heaptrace.dump() -- dump the current state of allocations
... -- do the thing that is leaking memory
collectgarbage() -- free things that can be freed, to avoid false positives
heaptrace.stop() -- optional, but provides higher quality output next
heaptrace.dump() -- dump the current state of allocations, hopefully showing the leaked entries and where they got allocated from
-- heaptrace.resume() -- optionally resume the tracing, if stopped previously

heaptrace.init¶

Allocates and registers the heap tracing buffer.

Syntax¶

heaptrace.init(bufsz)

Parameters¶

bufsz the size of the heap tracing buffer, expressed as number of heap tracing records. The actual size depends on the call chain depth configured in Kconfig.

Returns¶

nil

heaptrace.start¶

Starts the heap tracing. All allocations and frees will be recorded in the heap tracing buffer, subject to availability within the buffer.

Syntax¶

heaptrace.start(mode)

Parameters¶

mode the heap tracing mode to use. One of:
heaptrace.TRACE_LEAKS
heaptrace.TRACE_ALL

Returns¶

nil

heaptrace.stop¶

Stops the heap tracing session. A stopped session may be resumed later.

Syntax¶

heaptrace.stop()

Parameters¶

None.

Returns¶

nil

heaptrace.resume¶

Resumes a previously stopped heap tracing session.

Syntax¶

heaptrace.resume()

Parameters¶

None.

Returns¶

nil

heaptrace.dump¶

Dumps the heap trace buffer to the console.

Syntax¶

heaptrace.dump()

Parameters¶

None.

Returns¶

nil