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_allocator: 103 104FirstFitAllocator 105----------------- 106.. doxygenclass:: pw::allocator::FirstFitAllocator 107 :members: 108 109.. _module-pw_allocator-api-best_fit_allocator: 110 111BestFitAllocator 112---------------- 113.. doxygenclass:: pw::allocator::BestFitAllocator 114 :members: 115 116.. _module-pw_allocator-api-worst_fit_allocator: 117 118WorstFitAllocator 119----------------- 120.. doxygenclass:: pw::allocator::WorstFitAllocator 121 :members: 122 123.. _module-pw_allocator-api-bucket_block_allocator: 124 125BucketAllocator 126=============== 127.. doxygenclass:: pw::allocator::BucketAllocator 128 :members: 129 130.. _module-pw_allocator-api-buddy_allocator: 131 132BuddyAllocator 133============== 134.. doxygenclass:: pw::allocator::BuddyAllocator 135 :members: 136 137.. _module-pw_allocator-api-bump_allocator: 138 139BumpAllocator 140============= 141.. doxygenclass:: pw::allocator::BumpAllocator 142 :members: 143 144.. _module-pw_allocator-api-chunk_pool: 145 146ChunkPool 147========= 148.. doxygenclass:: pw::allocator::ChunkPool 149 :members: 150 151.. _module-pw_allocator-api-libc_allocator: 152 153LibCAllocator 154============= 155.. doxygenclass:: pw::allocator::LibCAllocator 156 :members: 157 158.. _module-pw_allocator-api-null_allocator: 159 160NullAllocator 161============= 162.. doxygenclass:: pw::allocator::NullAllocator 163 :members: 164 165.. _module-pw_allocator-api-typed_pool: 166 167TypedPool 168========= 169.. doxygenclass:: pw::allocator::TypedPool 170 :members: 171 172--------------------- 173Forwarding Allocators 174--------------------- 175This module provides several "forwarding" allocators, as described in 176:ref:`module-pw_allocator-design-forwarding`. 177 178.. _module-pw_allocator-api-allocator_as_pool: 179 180AllocatorAsPool 181=============== 182.. doxygenclass:: pw::allocator::AllocatorAsPool 183 :members: 184 185.. _module-pw_allocator-api-pmr_allocator: 186 187PmrAllocator 188============ 189.. doxygenclass:: pw::allocator::PmrAllocator 190 :members: 191 192.. _module-pw_allocator-api-fallback_allocator: 193 194FallbackAllocator 195================= 196.. doxygenclass:: pw::allocator::FallbackAllocator 197 :members: 198 199.. _module-pw_allocator-api-synchronized_allocator: 200 201SynchronizedAllocator 202===================== 203.. doxygenclass:: pw::allocator::SynchronizedAllocator 204 :members: 205 206.. _module-pw_allocator-api-tracking_allocator: 207 208TrackingAllocator 209================= 210.. doxygenclass:: pw::allocator::TrackingAllocator 211 :members: 212 213--------------- 214Utility Classes 215--------------- 216In addition to providing allocator implementations themselves, this module 217includes some utility classes. 218 219.. _module-pw_allocator-api-block: 220 221Block interfaces 222================ 223A block is an allocatable region of memory, and is the fundamental type managed 224by several of the concrete allocator implementations. Blocks are defined 225using several stateless "mix-in" interface types. These provide specific 226functionality, while deferring the detailed representation of a block to a 227derived type. 228 229.. tip:: 230 Avoid converting pointers to allocations into ``Block`` instances, even if 231 you know your memory is coming from a ``BlockAllocator``. Breaking the 232 abstraction in this manner will limit your flexibility to change to a 233 different allocator in the future. 234 235.. TODO(b/378549332): Add a diagram of mix-in relationships. 236 237BasicBlock 238---------- 239.. doxygenclass:: pw::allocator::BasicBlock 240 :members: 241 242ContiguousBlock 243--------------- 244.. doxygenclass:: pw::allocator::ContiguousBlock 245 :members: 246 247AllocatableBlock 248---------------- 249.. doxygenclass:: pw::allocator::AllocatableBlock 250 :members: 251 252AlignableBlock 253-------------- 254.. doxygenclass:: pw::allocator::AlignableBlock 255 :members: 256 257BlockWithLayout 258--------------- 259.. doxygenclass:: pw::allocator::BlockWithLayout 260 :members: 261 262ForwardIterableBlock 263-------------------- 264.. doxygenclass:: pw::allocator::ForwardIterableBlock 265 :members: 266 267ReverseIterableBlock 268-------------------- 269.. doxygenclass:: pw::allocator::ReverseIterableBlock 270 :members: 271 272PoisonableBlock 273--------------- 274.. doxygenclass:: pw::allocator::PoisonableBlock 275 :members: 276 277BlockResult 278----------- 279This type is not a block mix-in. It is used to communicate whether a method 280succeeded, what block was produced or modified, and what side-effects the call 281produced. 282 283.. doxygenclass:: pw::allocator::BlockResult 284 :members: 285 286DetailedBlock 287------------- 288This type is not a block mix-in. It is an example of a block implementation that 289uses the mix-ins above. 290 291.. doxygenstruct:: pw::allocator::DetailedBlockParameters 292 :members: 293 294.. doxygenclass:: pw::allocator::DetailedBlockImpl 295 :members: 296 297.. _module-pw_allocator-api-bucket: 298 299Bucket 300====== 301Several block allocator implementations improve performance by managing buckets, 302which are data structures that track free blocks. Several bucket implementations 303are provided that trade off between performance and per-block space needed when 304free. 305 306FastSortedBucket 307---------------- 308.. doxygenclass:: pw::allocator::FastSortedBucket 309 :members: 310 311ForwardSortedBucket 312------------------- 313.. doxygenclass:: pw::allocator::ForwardSortedBucket 314 :members: 315 316ReverseFastSortedBucket 317----------------------- 318.. doxygenclass:: pw::allocator::ReverseFastSortedBucket 319 :members: 320 321ReverseSortedBucket 322------------------- 323.. doxygenclass:: pw::allocator::ReverseSortedBucket 324 :members: 325 326SequencedBucket 327--------------- 328.. doxygenclass:: pw::allocator::SequencedBucket 329 :members: 330 331UnorderedBucket 332--------------- 333.. doxygenclass:: pw::allocator::UnorderedBucket 334 :members: 335 336.. _module-pw_allocator-api-metrics_adapter: 337 338Metrics 339======= 340.. doxygenclass:: pw::allocator::internal::Metrics 341 :members: 342 343This class is templated on a ``MetricsType`` struct. See 344:ref:`module-pw_allocator-design-metrics` for additional details on how the 345struct, this class, and :ref:`module-pw_allocator-api-tracking_allocator` 346interact. 347 348Module consumers can define their own metrics structs using the 349following macros: 350 351.. doxygendefine:: PW_ALLOCATOR_METRICS_DECLARE 352.. doxygendefine:: PW_ALLOCATOR_METRICS_ENABLE 353 354.. _module-pw_allocator-api-fragmentation: 355 356Fragmentation 357============= 358.. doxygenstruct:: pw::allocator::Fragmentation 359 :members: 360 361.. _module-pw_allocator-api-size_reporter: 362 363SizeReporter 364============ 365This module includes a utility class for generating size reports. It is 366intended for allocator implementers and not for module consumers. 367 368.. doxygenclass:: pw::allocator::SizeReporter 369 :members: 370 371Buffer management 372================= 373.. doxygenclass:: pw::allocator::WithBuffer 374 :members: 375 376------------ 377Test support 378------------ 379This module includes test utilities for allocator implementers. These 380facilitate writing unit tests and fuzz tests for both concrete and forwarding 381allocator implementations. They are not intended to be used by module consumers. 382 383.. _module-pw_allocator-api-allocator_for_test: 384 385AllocatorForTest 386================ 387.. doxygenclass:: pw::allocator::test::AllocatorForTest 388 :members: 389 390.. _module-pw_allocator-api-synchronized_allocator_for_test: 391 392SynchronizedAllocatorForTest 393============================ 394.. doxygenclass:: pw::allocator::test::SynchronizedAllocatorForTest 395 :members: 396 397.. _module-pw_allocator-api-test_harness: 398 399TestHarness 400=========== 401.. doxygenclass:: pw::allocator::test::TestHarness 402 :members: 403 404.. _module-pw_allocator-api-fuzzing_support: 405 406FuzzTest support 407================ 408.. doxygenfunction:: pw::allocator::test::ArbitraryRequest 409.. doxygenfunction:: pw::allocator::test::ArbitraryRequests 410.. doxygenfunction:: pw::allocator::test::MakeRequest 411