1.. _module-pw_allocator-api: 2 3============= 4API reference 5============= 6.. pigweed-module-subpage:: 7 :name: pw_allocator 8 9This module provides the following: 10 11- Generic allocator interfaces that can be injected into routines that need 12 dynamic memory. These include :ref:`module-pw_allocator-api-allocator`, as 13 well as the :ref:`module-pw_allocator-api-layout` type that is passed to it 14 and the :ref:`module-pw_allocator-api-unique_ptr` returned from it. 15- Concrete allocator implementations used to provide memory dynamically. 16- "Forwarding" allocators, as described by 17 :ref:`module-pw_allocator-design-forwarding`. 18- Additional allocator utility classes. These are typically used by allocator 19 implementers. 20- Test utilities for testing allocator implementations. These are typically used 21 by allocator implementers. 22 23--------------- 24Core interfaces 25--------------- 26This module defines several types as part of a generic interface for memory 27users. 28 29.. _module-pw_allocator-api-layout: 30 31Layout 32====== 33A request for memory includes a requested size and alignment as a ``Layout``: 34 35.. doxygenclass:: pw::allocator::Layout 36 :members: 37 38.. _module-pw_allocator-api-allocator: 39 40Allocator 41========= 42``Allocator`` is the most commonly used interface. It can be used to request 43memory of different layouts: 44 45.. doxygenclass:: pw::Allocator 46 :members: 47 48.. _module-pw_allocator-api-pool: 49 50Pool 51==== 52``Pool`` differs from ``Allocator`` in that it can be used to request memory of 53a single, fixed layout: 54 55.. doxygenclass:: pw::allocator::Pool 56 :members: 57 58.. _module-pw_allocator-api-deallocator: 59 60Deallocator 61=========== 62Both ``Allocator`` and ``Pool`` derive from and extend ``Deallocator``. This 63type is intended for allocator implementers and not for module consumers. 64 65.. doxygenclass:: pw::Deallocator 66 :members: 67 68.. _module-pw_allocator-api-capabilities: 69 70Capabilities 71============ 72Types deriving from ``MemoryResource`` can communicate about their optional 73methods and behaviors using ``Capabilities``. This type is intended for 74allocator implementers and not for module consumers. 75 76.. doxygenclass:: pw::allocator::Capabilities 77 :members: 78 79.. _module-pw_allocator-api-unique_ptr: 80 81UniquePtr 82========= 83The ``UniquePtr`` smart pointer type can be created by any type deriving from 84``MemoryResource``. 85 86.. doxygenclass:: pw::UniquePtr 87 :members: 88 89------------------------- 90Allocator implementations 91------------------------- 92This module provides several concrete allocator implementations of the 93:ref:`module-pw_allocator-api-allocator` interface: 94 95.. _module-pw_allocator-api-block_allocator: 96 97BlockAllocator 98============== 99.. doxygenclass:: pw::allocator::BlockAllocator 100 :members: 101 102.. _module-pw_allocator-api-first_fit_block_allocator: 103 104FirstFitBlockAllocator 105---------------------- 106.. doxygenclass:: pw::allocator::FirstFitBlockAllocator 107 :members: 108 109.. _module-pw_allocator-api-last_fit_block_allocator: 110 111LastFitBlockAllocator 112--------------------- 113.. doxygenclass:: pw::allocator::LastFitBlockAllocator 114 :members: 115 116.. _module-pw_allocator-api-best_fit_block_allocator: 117 118BestFitBlockAllocator 119--------------------- 120.. doxygenclass:: pw::allocator::BestFitBlockAllocator 121 :members: 122 123.. _module-pw_allocator-api-worst_fit_block_allocator: 124 125WorstFitBlockAllocator 126---------------------- 127.. doxygenclass:: pw::allocator::WorstFitBlockAllocator 128 :members: 129 130.. _module-pw_allocator-api-dual_first_fit_block_allocator: 131 132DualFirstFitBlockAllocator 133-------------------------- 134.. doxygenclass:: pw::allocator::DualFirstFitBlockAllocator 135 :members: 136 137.. _module-pw_allocator-api-bucket_block_allocator: 138 139BucketBlockAllocator 140==================== 141.. doxygenclass:: pw::allocator::BucketBlockAllocator 142 :members: 143 144.. _module-pw_allocator-api-buddy_allocator: 145 146BuddyAllocator 147============== 148.. doxygenclass:: pw::allocator::BuddyAllocator 149 :members: 150 151.. _module-pw_allocator-api-bump_allocator: 152 153BumpAllocator 154============= 155.. doxygenclass:: pw::allocator::BumpAllocator 156 :members: 157 158.. _module-pw_allocator-api-chunk_pool: 159 160ChunkPool 161========= 162.. doxygenclass:: pw::allocator::ChunkPool 163 :members: 164 165.. _module-pw_allocator-api-libc_allocator: 166 167LibCAllocator 168============= 169.. doxygenclass:: pw::allocator::LibCAllocator 170 :members: 171 172.. _module-pw_allocator-api-null_allocator: 173 174NullAllocator 175============= 176.. doxygenclass:: pw::allocator::NullAllocator 177 :members: 178 179.. _module-pw_allocator-api-typed_pool: 180 181TypedPool 182========= 183.. doxygenclass:: pw::allocator::TypedPool 184 :members: 185 186.. TODO: b/328076428 - Update FreeListHeap or remove 187 188--------------------- 189Forwarding Allocators 190--------------------- 191This module provides several "forwarding" allocators, as described in 192:ref:`module-pw_allocator-design-forwarding`. 193 194.. _module-pw_allocator-api-allocator_as_pool: 195 196AllocatorAsPool 197=============== 198.. doxygenclass:: pw::allocator::AllocatorAsPool 199 :members: 200 201.. _module-pw_allocator-api-as_pmr_allocator: 202 203AsPmrAllocator 204============== 205.. doxygenclass:: pw::allocator::AsPmrAllocator 206 :members: 207 208.. _module-pw_allocator-api-fallback_allocator: 209 210FallbackAllocator 211================= 212.. doxygenclass:: pw::allocator::FallbackAllocator 213 :members: 214 215.. _module-pw_allocator-api-synchronized_allocator: 216 217SynchronizedAllocator 218===================== 219.. doxygenclass:: pw::allocator::SynchronizedAllocator 220 :members: 221 222.. _module-pw_allocator-api-tracking_allocator: 223 224TrackingAllocator 225================= 226.. doxygenclass:: pw::allocator::TrackingAllocator 227 :members: 228 229--------------- 230Utility Classes 231--------------- 232In addition to providing allocator implementations themselves, this module 233includes some utility classes. 234 235.. _module-pw_allocator-api-block: 236 237Block 238===== 239.. doxygenclass:: pw::allocator::Block 240 :members: 241 242.. tip:: 243 Avoid converting pointers to allocations into ``Block`` instances, even if 244 you know your memory is coming from a ``BlockAllocator``. Breaking the 245 abstraction in this manner will limit your flexibility to change to a 246 different allocator in the future. 247 248.. _module-pw_allocator-api-bucket: 249 250Bucket 251====== 252.. doxygenclass:: pw::allocator::internal::Bucket 253 :members: 254 255.. _module-pw_allocator-api-metrics_adapter: 256 257Metrics 258======= 259.. doxygenclass:: pw::allocator::internal::Metrics 260 :members: 261 262This class is templated on a ``MetricsType`` struct. See 263:ref:`module-pw_allocator-design-metrics` for additional details on how the 264struct, this class, and :ref:`module-pw_allocator-api-tracking_allocator` 265interact. 266 267Module consumers can define their own metrics structs using the 268following macros: 269 270.. doxygendefine:: PW_ALLOCATOR_METRICS_DECLARE 271.. doxygendefine:: PW_ALLOCATOR_METRICS_ENABLE 272 273.. _module-pw_allocator-api-fragmentation: 274 275Fragmentation 276============= 277.. doxygenstruct:: pw::allocator::Fragmentation 278 :members: 279 280.. _module-pw_allocator-api-size_reporter: 281 282SizeReporter 283============ 284This module includes a utility class for generating size reports. It is 285intended for allocator implementers and not for module consumers. 286 287.. doxygenclass:: pw::allocator::SizeReporter 288 :members: 289 290Buffer management 291================= 292.. doxygenclass:: pw::allocator::WithBuffer 293 :members: 294 295------------ 296Test support 297------------ 298This module includes test utilities for allocator implementers. These 299facilitate writing unit tests and fuzz tests for both concrete and forwarding 300allocator implementations. They are not intended to be used by module consumers. 301 302.. _module-pw_allocator-api-allocator_for_test: 303 304AllocatorForTest 305================ 306.. doxygenclass:: pw::allocator::test::AllocatorForTest 307 :members: 308 309.. _module-pw_allocator-api-test_harness: 310 311TestHarness 312=========== 313.. doxygenclass:: pw::allocator::test::TestHarness 314 :members: 315 316.. _module-pw_allocator-api-fuzzing_support: 317 318FuzzTest support 319================ 320.. doxygenfunction:: pw::allocator::test::ArbitraryRequest 321.. doxygenfunction:: pw::allocator::test::ArbitraryRequests 322.. doxygenfunction:: pw::allocator::test::MakeRequest 323