pw_malloc

Oveview

Replacement interface for standard libc dynamic memory operations. Main docs: https://pigweed.dev/pw_malloc.

Macros
#define	PW_MALLOC_LOCK_TYPE   ::pw::allocator::NoSync
#define	PW_MALLOC_METRICS_TYPE   ::pw::allocator::NoMetrics
#define	PW_MALLOC_BLOCK_OFFSET_TYPE   uintptr_t
#define	PW_MALLOC_MIN_BUCKET_SIZE   32
#define	PW_MALLOC_NUM_BUCKETS   5
#define	PW_MALLOC_DUAL_FIRST_FIT_THRESHOLD   2048

Functions
void	pw::malloc::InitSystemAllocator (ByteSpan heap)
void	pw::malloc::InitSystemAllocator (void *heap_low_addr, void *heap_high_addr)
template<typename AllocatorType >
void	pw::malloc::InitSystemAllocator (ByteSpan heap)
Allocator *	pw::malloc::GetSystemAllocator ()
const PW_MALLOC_METRICS_TYPE &	pw::malloc::UpdateSystemMetrics ()

Macro Definition Documentation

PW_MALLOC_BLOCK_OFFSET_TYPE

#define PW_MALLOC_BLOCK_OFFSET_TYPE   uintptr_t

Sets the unsigned integer type used by pw::allocator::BlockAllocators to index blocks.

Larger types allow addressing more memory, but increase allocation overhead from block metadata.

Defaults to platform's uintptr_t type.

PW_MALLOC_DUAL_FIRST_FIT_THRESHOLD

#define PW_MALLOC_DUAL_FIRST_FIT_THRESHOLD   2048

Sets the threshold beyond which a pw::allocator::DualFirstFitBlockAllocator considers allocations large.

See also pw::allocator::DualFirstFitBlockAllocator.

Defaults to 2KiB.

PW_MALLOC_LOCK_TYPE

#define PW_MALLOC_LOCK_TYPE   ::pw::allocator::NoSync

Sets the type of synchronization primitive to use to mediate concurrent allocations by the system allocator.

Defaults to pw::allocator::NoSync, which does no locking.

PW_MALLOC_METRICS_TYPE

#define PW_MALLOC_METRICS_TYPE   ::pw::allocator::NoMetrics

Sets the type of allocator metrics collected by the system allocator.

Defaults to pw::allocator::NoMetrics, which does no tracking.

PW_MALLOC_MIN_BUCKET_SIZE

#define PW_MALLOC_MIN_BUCKET_SIZE   32

Sets the size of the smallest `pw::allocator::Bucket used by an allocator.

See also pw::allocator::BucketBlockAllocator and pw::allocator::BuddyAllocator.

Must be a power of two. Defaults to 32.

PW_MALLOC_NUM_BUCKETS

#define PW_MALLOC_NUM_BUCKETS   5

Sets the number of `pw::allocator::Bucket used by an allocator.

See also pw::allocator::BucketBlockAllocator and pw::allocator::BuddyAllocator.

Defaults to 5.

Function Documentation

GetSystemAllocator()

Allocator * pw::malloc::GetSystemAllocator

(

)

Returns the system allocator.

This function must be implemented to return a pointer to an allocator with a global lifetime. The returned allocator must be initialized and ready to use. The facade will call this function at most once.

Backends may either implement this function directly with a concrete allocator type, or delegate its implementation to consumers to allow them to provide their own allocator types. Backends that implement it directly should use pw_malloc_Init to provide the region from which to allocate memory.

Precondition

This function must be implemented by the pw_malloc backend.

InitSystemAllocator() [1/3]

void pw::malloc::InitSystemAllocator

(

ByteSpan

heap

)

Sets the memory to be used by the system allocator.

A backend can implement this method to provide the allocator returned by GetSystemAllocator with a region of memory for it to use.

Precondition

This function must be implemented by the pw_malloc backend, but may be trivially empty if the backend provides its own storage.

Parameters

heap	The region of memory to use as a heap.

InitSystemAllocator() [2/3]

template<typename AllocatorType >

void pw::malloc::InitSystemAllocator

(

ByteSpan

heap

)

Sets the memory to be used by the system allocator.

This method is a generic version of InitSystemAllocator that works with allocator types that have an Init(ByteSpan) method. It can be used to implement InitSystemAllocator for specific pw_malloc backends.

This method enforces the requirement that it is only called once.

InitSystemAllocator() [3/3]

void pw::malloc::InitSystemAllocator	(	void *	heap_low_addr,
		void *	heap_high_addr
	)

Sets the memory to be used by the system allocator.

This method provides an alternate interface that may be more convenient to call with symbols defined in linker scripts.

Parameters

heap_low_addr	The inclusive start of the region of memory to use as a heap. This MUST be less than heap_high_addr.
heap	The exclusive end of the region of memory to use as a heap. This MUST be less than heap_high_addr.

UpdateSystemMetrics()

const PW_MALLOC_METRICS_TYPE & pw::malloc::UpdateSystemMetrics

(

)

Returns the metrics for the system allocator using the configured type.

In order to be thread-safe, the system metrics are only updated when either this method is called. Thus, callers should call this method each time they wish to examine the system allocator metrics.

For example:

DoSomethingWithMetrics(UpdateSystemMetrics());
 
PerformSomeAllocationsAndFrees();
DoSomethingWithMetrics(UpdateSystemMetrics());