diff options
Diffstat (limited to 'pw_allocator/docs.rst')
| -rw-r--r-- | pw_allocator/docs.rst | 81 |
1 files changed, 63 insertions, 18 deletions
diff --git a/pw_allocator/docs.rst b/pw_allocator/docs.rst index 81dcb06cf..0d5545ccf 100644 --- a/pw_allocator/docs.rst +++ b/pw_allocator/docs.rst @@ -7,19 +7,58 @@ pw_allocator This module provides various building blocks for a dynamic allocator. This is composed of the following parts: -- ``block``: An implementation of a linked list of memory blocks, supporting - splitting and merging of blocks. +- ``block``: An implementation of a doubly-linked list of memory blocks, + supporting splitting and merging of blocks. - ``freelist``: A freelist, suitable for fast lookups of available memory chunks (i.e. ``block`` s). - -Heap Integrity Check -==================== -The ``Block`` class provides two check functions: - -- ``bool Block::IsValid()``: Returns ``true`` is the given block is valid and - ``false`` otherwise. -- ``void Block::CrashIfInvalid()``: Crash the program and output the reason why - the check fails using ``PW_DCHECK``. +- ``allocator``: An interface for memory allocators. Several concrete + implementations are also provided. + +Block +===== +.. doxygenclass:: pw::allocator::Block + :members: + +FreeList +======== +.. doxygenclass:: pw::allocator::FreeList + :members: + +Allocator +========= +.. doxygenclass:: pw::allocator::Allocator + :members: + +Example +------- +As an example, the following implements a simple allocator that tracks memory +using ``Block``. + +.. literalinclude:: public/pw_allocator/simple_allocator.h + :language: cpp + :linenos: + :start-after: [pw_allocator_examples_simple_allocator] + :end-before: [pw_allocator_examples_simple_allocator] + +Other Implemetations +-------------------- +Provided implementations of the ``Allocator`` interface include: + +- ``AllocatorMetricProxy``: Wraps another allocator and records its usage. +- ``FallbackAllocator``: Dispatches first to a primary allocator, and, if that + fails, to a secondary alloator. +- ``LibCAllocator``: Uses ``malloc``, ``realloc``, and ``free``. This should + only be used if the ``libc`` in use provides those functions. +- ``NullAllocator``: Always fails. This may be useful if allocations should be + disallowed under specific circumstances. +- ``SplitFreeListAllocator``: Tracks memory using ``Block``, and splits large + and small allocations between the front and back, respectively, of it memory + region in order to reduce fragmentation. + +UniquePtr +========= +.. doxygenclass:: pw::allocator::UniquePtr + :members: Heap Poisoning ============== @@ -28,7 +67,7 @@ By default, this module disables heap poisoning since it requires extra space. User can enable heap poisoning by enabling the ``pw_allocator_POISON_HEAP`` build arg. -.. code:: sh +.. code-block:: sh $ gn args out # Modify and save the args file to use heap poison. @@ -57,7 +96,7 @@ Usage The heap visualizer can be launched from a shell using the Pigweed environment. -.. code:: sh +.. code-block:: sh $ pw heap-viewer --dump-file <directory of dump file> --heap-low-address <hex address of heap lower address> --heap-high-address <hex address of heap @@ -71,7 +110,7 @@ The required arguments are: represented as ``f <memory address>``. For example, a dump file should look like: - .. code:: sh + .. code-block:: sh m 20 0x20004450 # malloc 20 bytes, the pointer is 0x20004450 m 8 0x2000447c # malloc 8 bytes, the pointer is 0x2000447c @@ -82,13 +121,13 @@ The required arguments are: - ``--heap-low-address`` is the start of the heap. For example: - .. code:: sh + .. code-block:: sh --heap-low-address 0x20004440 - ``--heap-high-address`` is the end of the heap. For example: - .. code:: sh + .. code-block:: sh --heap-high-address 0x20006040 @@ -101,5 +140,11 @@ Options include the following: - ``--pointer-size <integer of pointer size>``: The size of a pointer on the machine where ``malloc/free`` is called. The default value is ``4``. -Note, this module, and its documentation, is currently incomplete and -experimental. +.. _module-pw_allocator-size: + +Size report +=========== +``pw_allocator`` provides some of its own implementations of the ``Allocator`` +interface, whos costs are shown below. + +.. include:: allocator_size_report |