pw_malloc#

Replacement interface for standard libc dynamic memory operations

Stable C C++

This module defines an interface for replacing the standard libc dynamic memory operations.

This facade doesn’t implement any heap structure or dynamic memory methods. It only requires that backends implements pw::malloc::GetSystemAllocator and optionally pw::malloc::InitSystemAllocator. These functions are called before static initialization, and are responsible for initializing global data structures required by the malloc implementation.

The intent of this module is to provide an interface for user-provided dynamic memory operations that is compatible with different implementations.

Setup#

This module requires the following setup:

  1. Choose a pw_malloc backend, or write one yourself.

  2. Select a backend in your build system. If using GN build, Specify the pw_malloc_BACKEND GN build arg to point to the library that provides a pw_malloc backend. If using the Bazel build, add the constraint value for the backend library that provides a pw_malloc backend.

  3. Add a dependency on the pw_malloc facade in your targets executable build template, e.g.:

template("platform_executable") {
   target("executable", target_name) {
      deps = []
      config = []
      forward_variables_from(invoker, "*")
      if (pw_malloc_BACKEND != "") {
         deps += [ dir_pw_malloc ]
      }
   }
}

Compile-time configuration#

This module has configuration options that globally affect the behavior of pw_malloc via compile-time configuration of this module.

PW_MALLOC_LOCK_TYPE#

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#

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

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

PW_MALLOC_BLOCK_OFFSET_TYPE#

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_MIN_BUCKET_SIZE#

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#

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

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

Defaults to 5.

PW_MALLOC_DUAL_FIRST_FIT_THRESHOLD#

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

See also pw::allocator::DualFirstFitBlockAllocator.

Defaults to 2KiB.

See the module documentation for more details.

Heap initialization#

You can provide a region of memory to use as heap as either a byte span or a pair of addresses to pw::malloc::InitSystemAllocator.

Usage#

Once the heap is initialized, you may simply use malloc and free as you would normally, as well as standard library functions like strdup and built-in routines like new that use those functions.

If you configured a PW_MALLOC_METRICS_TYPE, you can retrieve metrics using pw::malloc::GetSystemMetrics().

On this page