Heap Listener APIs

Data Structures
struct	heap_listener

Macros
#define	HEAP_ID_FROM_POINTER(heap_pointer)   ((uintptr_t)heap_pointer)
	Construct heap identifier from heap pointer.
#define	HEAP_ID_LIBC   ((uintptr_t)0)
	Libc heap identifier.
#define	HEAP_LISTENER_ALLOC_DEFINE(name, _heap_id, _alloc_cb)
	Define heap event listener node for allocation event.
#define	HEAP_LISTENER_FREE_DEFINE(name, _heap_id, _free_cb)
	Define heap event listener node for free event.
#define	HEAP_LISTENER_RESIZE_DEFINE(name, _heap_id, _resize_cb)
	Define heap event listener node for resize event.

Typedefs
typedef void(*	heap_listener_resize_cb_t) (uintptr_t heap_id, void *old_heap_end, void *new_heap_end)
	Callback used when heap is resized.
typedef void(*	heap_listener_alloc_cb_t) (uintptr_t heap_id, void *mem, size_t bytes)
	Callback used when there is heap allocation.
typedef void(*	heap_listener_free_cb_t) (uintptr_t heap_id, void *mem, size_t bytes)
	Callback used when memory is freed from heap.

Enumerations
enum	heap_event_types {   HEAP_EVT_UNKNOWN = 0 , HEAP_RESIZE , HEAP_ALLOC , HEAP_FREE ,   HEAP_REALLOC , HEAP_MAX_EVENTS }

Functions
void	heap_listener_register (struct heap_listener *listener)
	Register heap event listener.
void	heap_listener_unregister (struct heap_listener *listener)
	Unregister heap event listener.
void	heap_listener_notify_alloc (uintptr_t heap_id, void *mem, size_t bytes)
	Notify listeners of heap allocation event.
void	heap_listener_notify_free (uintptr_t heap_id, void *mem, size_t bytes)
	Notify listeners of heap free event.
void	heap_listener_notify_resize (uintptr_t heap_id, void *old_heap_end, void *new_heap_end)
	Notify listeners of heap resize event.

Detailed Description

Macro Definition Documentation

HEAP_ID_FROM_POINTER

#define HEAP_ID_FROM_POINTER

(

heap_pointer

)

((uintptr_t)heap_pointer)

#include <zephyr/sys/heap_listener.h>

Construct heap identifier from heap pointer.

Construct a heap identifier from a pointer to the heap object, such as sys_heap.

Parameters

heap_pointer

Pointer to the heap object

HEAP_ID_LIBC

#define HEAP_ID_LIBC   ((uintptr_t)0)

#include <zephyr/sys/heap_listener.h>

Libc heap identifier.

Identifier of the global libc heap.

HEAP_LISTENER_ALLOC_DEFINE

#define HEAP_LISTENER_ALLOC_DEFINE	(		name,
			_heap_id,
			_alloc_cb
	)

#include <zephyr/sys/heap_listener.h>

Value:

        struct heap_listener name = { \
                .heap_id = _heap_id, \
                .event = HEAP_ALLOC, \
                { \
                        .alloc_cb = _alloc_cb \
                }, \
        }

Define heap event listener node for allocation event.

Sample usage:

void on_heap_alloc(uintptr_t heap_id, void *mem, size_t bytes)
{
  LOG_INF("Memory allocated at %p, size %ld", mem, bytes);
}
 
HEAP_LISTENER_ALLOC_DEFINE(my_listener, HEAP_ID_LIBC, on_heap_alloc);

Parameters

name	Name of the heap event listener object
_heap_id	Identifier of the heap to be listened
_alloc_cb	Function to be called for allocation event

HEAP_LISTENER_FREE_DEFINE

#define HEAP_LISTENER_FREE_DEFINE	(		name,
			_heap_id,
			_free_cb
	)

#include <zephyr/sys/heap_listener.h>

Value:

        struct heap_listener name = { \
                .heap_id = _heap_id, \
                .event = HEAP_FREE, \
                { \
                        .free_cb = _free_cb \
                }, \
        }

Define heap event listener node for free event.

Sample usage:

void on_heap_free(uintptr_t heap_id, void *mem, size_t bytes)
{
  LOG_INF("Memory freed at %p, size %ld", mem, bytes);
}
 
HEAP_LISTENER_FREE_DEFINE(my_listener, HEAP_ID_LIBC, on_heap_free);

Parameters

name	Name of the heap event listener object
_heap_id	Identifier of the heap to be listened
_free_cb	Function to be called for free event

HEAP_LISTENER_RESIZE_DEFINE

#define HEAP_LISTENER_RESIZE_DEFINE	(		name,
			_heap_id,
			_resize_cb
	)

#include <zephyr/sys/heap_listener.h>

Value:

        struct heap_listener name = { \
                .heap_id = _heap_id, \
                .event = HEAP_RESIZE, \
                { \
                        .resize_cb = _resize_cb \
                }, \
        }

Define heap event listener node for resize event.

Sample usage:

void on_heap_resized(uintptr_t heap_id, void *old_heap_end, void *new_heap_end)
{
  LOG_INF("Libc heap end moved from %p to %p", old_heap_end, new_heap_end);
}
 
HEAP_LISTENER_RESIZE_DEFINE(my_listener, HEAP_ID_LIBC, on_heap_resized);

Parameters

name	Name of the heap event listener object
_heap_id	Identifier of the heap to be listened
_resize_cb	Function to be called when the listened heap is resized

Typedef Documentation

heap_listener_alloc_cb_t

heap_listener_alloc_cb_t

#include <zephyr/sys/heap_listener.h>

Callback used when there is heap allocation.

Note

Heaps managed by libraries outside of code in Zephyr main code repository may not emit this event.

The number of bytes allocated may not match exactly to the request to the allocation function. Internal mechanism of the heap may allocate more than requested.

Parameters

heap_id	Heap identifier
mem	Pointer to the allocated memory
bytes	Size of allocated memory

heap_listener_free_cb_t

heap_listener_free_cb_t

#include <zephyr/sys/heap_listener.h>

Callback used when memory is freed from heap.

Note

Heaps managed by libraries outside of code in Zephyr main code repository may not emit this event.

The number of bytes freed may not match exactly to the request to the allocation function. Internal mechanism of the heap dictates how memory is allocated or freed.

Parameters

heap_id	Heap identifier
mem	Pointer to the freed memory
bytes	Size of freed memory

heap_listener_resize_cb_t

heap_listener_resize_cb_t

#include <zephyr/sys/heap_listener.h>

Callback used when heap is resized.

Note

Minimal C library does not emit this event.

Parameters

heap_id	Identifier of heap being resized
old_heap_end	Pointer to end of heap before resize
new_heap_end	Pointer to end of heap after resize

Enumeration Type Documentation

heap_event_types

enum heap_event_types

#include <zephyr/sys/heap_listener.h>

Enumerator
HEAP_EVT_UNKNOWN
HEAP_RESIZE
HEAP_ALLOC
HEAP_FREE
HEAP_REALLOC
HEAP_MAX_EVENTS

Function Documentation

heap_listener_notify_alloc()

void heap_listener_notify_alloc	(	uintptr_t	heap_id,
		void *	mem,
		size_t	bytes
	)

#include <zephyr/sys/heap_listener.h>

Notify listeners of heap allocation event.

Notify registered heap event listeners with matching heap identifier that an allocation has been done on heap

Parameters

heap_id	Heap identifier
mem	Pointer to the allocated memory
bytes	Size of allocated memory

heap_listener_notify_free()

void heap_listener_notify_free	(	uintptr_t	heap_id,
		void *	mem,
		size_t	bytes
	)

#include <zephyr/sys/heap_listener.h>

Notify listeners of heap free event.

Notify registered heap event listeners with matching heap identifier that memory is freed on heap

Parameters

heap_id	Heap identifier
mem	Pointer to the freed memory
bytes	Size of freed memory

heap_listener_notify_resize()

void heap_listener_notify_resize	(	uintptr_t	heap_id,
		void *	old_heap_end,
		void *	new_heap_end
	)

#include <zephyr/sys/heap_listener.h>

Notify listeners of heap resize event.

Notify registered heap event listeners with matching heap identifier that the heap has been resized.

Parameters

heap_id	Heap identifier
old_heap_end	Address of the heap end before the change
new_heap_end	Address of the heap end after the change

heap_listener_register()

void heap_listener_register

(

struct heap_listener *

listener

)

#include <zephyr/sys/heap_listener.h>

Register heap event listener.

Add the listener to the global list of heap listeners that can be notified by different heap implementations upon certain events related to the heap usage.

Parameters

listener

Pointer to the heap_listener object

heap_listener_unregister()

void heap_listener_unregister

(

struct heap_listener *

listener

)

#include <zephyr/sys/heap_listener.h>

Unregister heap event listener.

Remove the listener from the global list of heap listeners that can be notified by different heap implementations upon certain events related to the heap usage.

Parameters

listener

Pointer to the heap_listener object