pw_allocator/api.rst

.. _module-pw_allocator-api:

=============
API reference
=============
.. pigweed-module-subpage::
   :name: pw_allocator

This module provides the following:

- Generic allocator interfaces that can be injected into routines that need
  dynamic memory. These include :ref:`module-pw_allocator-api-allocator`, as
  well as the :ref:`module-pw_allocator-api-layout` type that is passed to it
  and the :ref:`module-pw_allocator-api-unique_ptr` returned from it.
- Concrete allocator implementations used to provide memory dynamically.
- "Forwarding" allocators, as described by
  :ref:`module-pw_allocator-design-forwarding`.
- Additional allocator utility classes. These are typically used by allocator
  implementers.
- Test utilities for testing allocator implementations. These are typically used
  by allocator implementers.

---------------
Core interfaces
---------------
This module defines several types as part of a generic interface for memory
users.

.. _module-pw_allocator-api-layout:

Layout
======
A request for memory includes a requested size and alignment as a ``Layout``:

.. doxygenclass:: pw::allocator::Layout
   :members:

.. _module-pw_allocator-api-allocator:

Allocator
=========
``Allocator`` is the most commonly used interface. It can be used to request
memory of different layouts:

.. doxygenclass:: pw::allocator::Allocator
   :members:

.. _module-pw_allocator-api-pool:

Pool
====
``Pool`` differs from ``Allocator`` in that it can be used to request memory of
a single, fixed layout:

.. doxygenclass:: pw::allocator::Pool
   :members:

.. _module-pw_allocator-api-deallocator:

Deallocator
===========
Both ``Allocator`` and ``Pool`` derive from and extend ``Deallocator``. This
type is intended for allocator implementers and not for module consumers.

.. doxygenclass:: pw::allocator::Deallocator
   :members:

.. _module-pw_allocator-api-capabilities:

Capabilities
============
Types deriving from ``MemoryResource`` can communicate about their optional
methods and behaviors using ``Capabilities``. This type is intended for
allocator implementers and not for module consumers.

.. doxygenclass:: pw::allocator::Capabilities
   :members:

.. _module-pw_allocator-api-unique_ptr:

UniquePtr
=========
The ``UniquePtr`` smart pointer type can be created by any type deriving from
``MemoryResource``.

.. doxygenclass:: pw::allocator::UniquePtr
   :members:

-------------------------
Allocator implementations
-------------------------
This module provides several concrete allocator implementations of the
:ref:`module-pw_allocator-api-allocator` interface:

.. _module-pw_allocator-api-block_allocator:

BlockAllocator
==============
.. doxygenclass:: pw::allocator::BlockAllocator
   :members:

.. _module-pw_allocator-api-first_fit_block_allocator:

FirstFitBlockAllocator
----------------------
.. doxygenclass:: pw::allocator::FirstFitBlockAllocator
   :members:

.. _module-pw_allocator-api-last_fit_block_allocator:

LastFitBlockAllocator
---------------------
.. doxygenclass:: pw::allocator::LastFitBlockAllocator
   :members:

.. _module-pw_allocator-api-best_fit_block_allocator:

BestFitBlockAllocator
---------------------
.. doxygenclass:: pw::allocator::BestFitBlockAllocator
   :members:

.. _module-pw_allocator-api-worst_fit_block_allocator:

WorstFitBlockAllocator
----------------------
.. doxygenclass:: pw::allocator::WorstFitBlockAllocator
   :members:

.. _module-pw_allocator-api-dual_first_fit_block_allocator:

DualFirstFitBlockAllocator
--------------------------
.. doxygenclass:: pw::allocator::DualFirstFitBlockAllocator
   :members:

.. _module-pw_allocator-api-buddy_allocator:

BuddyAllocator
==============
.. doxygenclass:: pw::allocator::BuddyAllocator
   :members:

.. _module-pw_allocator-api-bump_allocator:

BumpAllocator
=============
.. doxygenclass:: pw::allocator::BumpAllocator
   :members:

.. _module-pw_allocator-api-chunk_pool:

ChunkPool
=========
.. doxygenclass:: pw::allocator::ChunkPool
   :members:

.. _module-pw_allocator-api-libc_allocator:

LibCAllocator
=============
.. doxygenclass:: pw::allocator::LibCAllocator
   :members:

.. _module-pw_allocator-api-null_allocator:

NullAllocator
=============
.. doxygenclass:: pw::allocator::NullAllocator
   :members:

.. _module-pw_allocator-api-typed_pool:

TypedPool
=========
.. doxygenclass:: pw::allocator::TypedPool
   :members:

.. TODO: b/328076428 - Update FreeListHeap or remove

---------------------
Forwarding Allocators
---------------------
This module provides several "forwarding" allocators, as described in
:ref:`module-pw_allocator-design-forwarding`.

.. _module-pw_allocator-api-allocator_as_pool:

AllocatorAsPool
===============
.. doxygenclass:: pw::allocator::AllocatorAsPool
   :members:

.. _module-pw_allocator-api-fallback_allocator:

FallbackAllocator
=================
.. doxygenclass:: pw::allocator::FallbackAllocator
   :members:

.. _module-pw_allocator-api-synchronized_allocator:

SynchronizedAllocator
=====================
.. doxygenclass:: pw::allocator::SynchronizedAllocator
   :members:

.. _module-pw_allocator-api-tracking_allocator:

TrackingAllocator
=================
.. doxygenclass:: pw::allocator::TrackingAllocator
   :members:

---------------
Utility Classes
---------------
In addition to providing allocator implementations themselves, this module
includes some utility classes.

.. _module-pw_allocator-api-block:

Block
=====
.. doxygenclass:: pw::allocator::Block
   :members:

.. tip::
   Avoid converting pointers to allocations into ``Block`` instances, even if
   you know your memory is coming from a ``BlockAllocator``. Breaking the
   abstraction in this manner will limit your flexibility to change to a
   different allocator in the future.

.. _module-pw_allocator-api-metrics_adapter:

Metrics
=======
.. doxygenclass:: pw::allocator::internal::Metrics
   :members:

This class is templated on a ``MetricsType`` struct. See
:ref:`module-pw_allocator-design-metrics` for additional details on how the
struct, this class, and :ref:`module-pw_allocator-api-tracking_allocator`
interact.

This modules also includes two concrete metrics types that can be used as the
template parameter of this class:

- ``AllMetrics``, which enables all metrics.
- ``NoMetrics``, which disables all metrics.

Additionally, module consumers can define their own metrics structs using the
following macros:

.. doxygendefine:: PW_ALLOCATOR_METRICS_DECLARE
.. doxygendefine:: PW_ALLOCATOR_METRICS_ENABLE

.. _module-pw_allocator-api-size_reporter:

SizeReporter
============
This modules includes a utility class for generating size reports. It is
intended for allocator implementers and not for module consumers.

.. doxygenclass:: pw::allocator::SizeReporter
   :members:

Buffer management
=================
.. doxygenclass:: pw::allocator::WithBuffer
   :members:

The following utility functions are available to allocator implementers. They
are not intended to be used by module consumers.

.. doxygenfunction:: pw::allocator::GetAlignedSubspan
.. doxygenfunction:: pw::allocator::IsWithin

------------
Test support
------------
This modules includes test utilities for allocator implementers. These
facilitate writing unit tests and fuzz tests for both concrete and forwarding
allocator implementations. They are not intended to be used by module consumers.

.. _module-pw_allocator-api-allocator_for_test:

AllocatorForTest
================
.. doxygenclass:: pw::allocator::test::AllocatorForTest
   :members:

.. _module-pw_allocator-api-allocator_test_harness:

AllocatorTestHarness
====================
.. doxygenclass:: pw::allocator::test::AllocatorTestHarness
   :members:

.. _module-pw_allocator-api-fuzzing_support:

FuzzTest support
================
.. doxygenfunction:: pw::allocator::test::ArbitraryAllocatorRequest
.. doxygenfunction:: pw::allocator::test::ArbitraryAllocatorRequests
.. doxygenfunction:: pw::allocator::test::MakeAllocatorRequest