xref: /aosp_15_r20/external/pigweed/pw_allocator/api.rst (revision 61c4878ac05f98d0ceed94b57d316916de578985)

.. _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
   :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::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::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_allocator:

FirstFitAllocator
-----------------
.. doxygenclass:: pw::allocator::FirstFitAllocator
   :members:

.. _module-pw_allocator-api-best_fit_allocator:

BestFitAllocator
----------------
.. doxygenclass:: pw::allocator::BestFitAllocator
   :members:

.. _module-pw_allocator-api-worst_fit_allocator:

WorstFitAllocator
-----------------
.. doxygenclass:: pw::allocator::WorstFitAllocator
   :members:

.. _module-pw_allocator-api-bucket_block_allocator:

BucketAllocator
===============
.. doxygenclass:: pw::allocator::BucketAllocator
   :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:

---------------------
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-pmr_allocator:

PmrAllocator
============
.. doxygenclass:: pw::allocator::PmrAllocator
   :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 interfaces
================
A block is an allocatable region of memory, and is the fundamental type managed
by several of the concrete allocator implementations. Blocks are defined
using several stateless "mix-in" interface types. These provide specific
functionality, while deferring the detailed representation of a block to a
derived type.

.. 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.

.. TODO(b/378549332): Add a diagram of mix-in relationships.

BasicBlock
----------
.. doxygenclass:: pw::allocator::BasicBlock
   :members:

ContiguousBlock
---------------
.. doxygenclass:: pw::allocator::ContiguousBlock
   :members:

AllocatableBlock
----------------
.. doxygenclass:: pw::allocator::AllocatableBlock
   :members:

AlignableBlock
--------------
.. doxygenclass:: pw::allocator::AlignableBlock
   :members:

BlockWithLayout
---------------
.. doxygenclass:: pw::allocator::BlockWithLayout
   :members:

ForwardIterableBlock
--------------------
.. doxygenclass:: pw::allocator::ForwardIterableBlock
   :members:

ReverseIterableBlock
--------------------
.. doxygenclass:: pw::allocator::ReverseIterableBlock
   :members:

PoisonableBlock
---------------
.. doxygenclass:: pw::allocator::PoisonableBlock
   :members:

BlockResult
-----------
This type is not a block mix-in. It is used to communicate whether a method
succeeded, what block was produced or modified, and what side-effects the call
produced.

.. doxygenclass:: pw::allocator::BlockResult
   :members:

DetailedBlock
-------------
This type is not a block mix-in. It is an example of a block implementation that
uses the mix-ins above.

.. doxygenstruct:: pw::allocator::DetailedBlockParameters
   :members:

.. doxygenclass:: pw::allocator::DetailedBlockImpl
   :members:

.. _module-pw_allocator-api-bucket:

Bucket
======
Several block allocator implementations improve performance by managing buckets,
which are data structures that track free blocks. Several bucket implementations
are provided that trade off between performance and per-block space needed when
free.

FastSortedBucket
----------------
.. doxygenclass:: pw::allocator::FastSortedBucket
   :members:

ForwardSortedBucket
-------------------
.. doxygenclass:: pw::allocator::ForwardSortedBucket
   :members:

ReverseFastSortedBucket
-----------------------
.. doxygenclass:: pw::allocator::ReverseFastSortedBucket
   :members:

ReverseSortedBucket
-------------------
.. doxygenclass:: pw::allocator::ReverseSortedBucket
   :members:

SequencedBucket
---------------
.. doxygenclass:: pw::allocator::SequencedBucket
   :members:

UnorderedBucket
---------------
.. doxygenclass:: pw::allocator::UnorderedBucket
   :members:

.. _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.

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-fragmentation:

Fragmentation
=============
.. doxygenstruct:: pw::allocator::Fragmentation
   :members:

.. _module-pw_allocator-api-size_reporter:

SizeReporter
============
This module 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:

------------
Test support
------------
This module 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-synchronized_allocator_for_test:

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

.. _module-pw_allocator-api-test_harness:

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

.. _module-pw_allocator-api-fuzzing_support:

FuzzTest support
================
.. doxygenfunction:: pw::allocator::test::ArbitraryRequest
.. doxygenfunction:: pw::allocator::test::ArbitraryRequests
.. doxygenfunction:: pw::allocator::test::MakeRequest