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. 64pw_allocator: Add bucket size reports 65 66Separating out the bucket size reports from those of the blocks and 67allocators makes it clearer where contributions to code size are coming 68from. 69 70Change-Id: Ibd719f3d4b88c42aa7833c24963e95253c397e03 71 72.. doxygenclass:: pw::Deallocator 73 :members: 74 75.. _module-pw_allocator-api-capabilities: 76 77Capabilities 78============ 79Types deriving from ``MemoryResource`` can communicate about their optional 80methods and behaviors using ``Capabilities``. This type is intended for 81allocator implementers and not for module consumers. 82 83.. doxygenclass:: pw::allocator::Capabilities 84 :members: 85 86.. _module-pw_allocator-api-unique_ptr: 87 88UniquePtr 89========= 90The ``UniquePtr`` smart pointer type can be created by any type deriving from 91``MemoryResource``. 92 93.. doxygenclass:: pw::UniquePtr 94 :members: 95 96-------------------- 97Module configuration 98-------------------- 99 100.. _module-pw_allocator-config-block_poison_interval: 101 102PW_ALLOCATOR_BLOCK_POISON_INTERVAL 103================================== 104.. doxygendefine:: PW_ALLOCATOR_BLOCK_POISON_INTERVAL 105 106.. _module-pw_allocator-config-hardening: 107 108PW_ALLOCATOR_HARDENING 109====================== 110.. doxygendefine:: PW_ALLOCATOR_HARDENING 111 112.. _module-pw_allocator-config-suppress_deprecated_warnings: 113 114PW_ALLOCATOR_SUPPRESS_DEPRECATED_WARNINGS 115========================================= 116.. doxygendefine:: PW_ALLOCATOR_SUPPRESS_DEPRECATED_WARNINGS 117 118------------------------- 119Allocator implementations 120------------------------- 121This module provides several concrete allocator implementations of the 122:ref:`module-pw_allocator-api-allocator` interface: 123 124.. _module-pw_allocator-api-block_allocator: 125 126BlockAllocator 127============== 128Several allocators use :ref:`module-pw_allocator-api-block` types to manage 129memory, and derive from this abstract base type. 130 131.. doxygenclass:: pw::allocator::BlockAllocator 132 :members: 133 134.. _module-pw_allocator-api-best_fit_allocator: 135 136BestFitAllocator 137---------------- 138.. doxygenclass:: pw::allocator::BestFitAllocator 139 :members: 140 141.. _module-pw_allocator-api-bucket_block_allocator: 142 143BucketAllocator 144--------------- 145.. doxygenclass:: pw::allocator::BucketAllocator 146 :members: 147 148.. _module-pw_allocator-api-dl_allocator: 149 150DlAllocator 151------------- 152.. doxygenclass:: pw::allocator::DlAllocator 153 :members: 154 155.. _module-pw_allocator-api-first_fit_allocator: 156 157FirstFitAllocator 158----------------- 159.. doxygenclass:: pw::allocator::FirstFitAllocator 160 :members: 161 162.. _module-pw_allocator-api-tlsf_allocator: 163 164TlsfAllocator 165------------- 166.. doxygenclass:: pw::allocator::TlsfAllocator 167 :members: 168 169.. _module-pw_allocator-api-worst_fit_allocator: 170 171WorstFitAllocator 172----------------- 173.. doxygenclass:: pw::allocator::WorstFitAllocator 174 :members: 175 176.. _module-pw_allocator-api-buddy_allocator: 177 178BuddyAllocator 179============== 180.. doxygenclass:: pw::allocator::BuddyAllocator 181 :members: 182 183.. _module-pw_allocator-api-bump_allocator: 184 185BumpAllocator 186============= 187.. doxygenclass:: pw::allocator::BumpAllocator 188 :members: 189 190.. _module-pw_allocator-api-chunk_pool: 191 192ChunkPool 193========= 194.. doxygenclass:: pw::allocator::ChunkPool 195 :members: 196 197.. _module-pw_allocator-api-libc_allocator: 198 199LibCAllocator 200============= 201.. doxygenclass:: pw::allocator::LibCAllocator 202 :members: 203 204.. _module-pw_allocator-api-null_allocator: 205 206NullAllocator 207============= 208.. doxygenclass:: pw::allocator::NullAllocator 209 :members: 210 211.. _module-pw_allocator-api-typed_pool: 212 213TypedPool 214========= 215.. doxygenclass:: pw::allocator::TypedPool 216 :members: 217 218--------------------- 219Forwarding Allocators 220--------------------- 221This module provides several "forwarding" allocators, as described in 222:ref:`module-pw_allocator-design-forwarding`. 223 224.. _module-pw_allocator-api-allocator_as_pool: 225 226AllocatorAsPool 227=============== 228.. doxygenclass:: pw::allocator::AllocatorAsPool 229 :members: 230 231.. _module-pw_allocator-api-pmr_allocator: 232 233PmrAllocator 234============ 235.. doxygenclass:: pw::allocator::PmrAllocator 236 :members: 237 238.. _module-pw_allocator-api-fallback_allocator: 239 240FallbackAllocator 241================= 242.. doxygenclass:: pw::allocator::FallbackAllocator 243 :members: 244 245.. _module-pw_allocator-api-synchronized_allocator: 246 247SynchronizedAllocator 248===================== 249.. doxygenclass:: pw::allocator::SynchronizedAllocator 250 :members: 251 252.. _module-pw_allocator-api-tracking_allocator: 253 254TrackingAllocator 255================= 256.. doxygenclass:: pw::allocator::TrackingAllocator 257 :members: 258 259.. _module-pw_allocator-api-block: 260 261----- 262Block 263----- 264A block is an allocatable region of memory, and is the fundamental type managed 265by several of the block allocator implementations. 266 267.. tip:: 268 Avoid converting pointers to allocations into ``Block`` instances, even if 269 you know your memory is coming from a ``BlockAllocator``. Breaking the 270 abstraction in this manner will limit your flexibility to change to a 271 different allocator in the future. 272 273Block mix-ins 274============= 275Blocks are defined using several stateless "mix-in" interface types. These 276provide specific functionality, while deferring the detailed representation of a 277block to a derived type. 278 279.. TODO(b/378549332): Add a diagram of mix-in relationships. 280 281.. _module-pw_allocator-api-basic_block: 282 283BasicBlock 284---------- 285.. doxygenclass:: pw::allocator::BasicBlock 286 :members: 287 288.. _module-pw_allocator-api-contiguous_block: 289 290ContiguousBlock 291--------------- 292.. doxygenclass:: pw::allocator::ContiguousBlock 293 :members: 294 295.. _module-pw_allocator-api-allocatable_block: 296 297AllocatableBlock 298---------------- 299.. doxygenclass:: pw::allocator::AllocatableBlock 300 :members: 301 302.. _module-pw_allocator-api-alignable_block: 303 304AlignableBlock 305-------------- 306.. doxygenclass:: pw::allocator::AlignableBlock 307 :members: 308 309.. _module-pw_allocator-api-block_with_layout: 310 311BlockWithLayout 312--------------- 313.. doxygenclass:: pw::allocator::BlockWithLayout 314 :members: 315 316.. _module-pw_allocator-api-iterable_block: 317 318IterableBlock 319-------------------- 320.. doxygenclass:: pw::allocator::IterableBlock 321 :members: 322 323.. _module-pw_allocator-api-poisonable_block: 324 325PoisonableBlock 326--------------- 327.. doxygenclass:: pw::allocator::PoisonableBlock 328 :members: 329 330BlockResult 331----------- 332This type is not a block mix-in. It is used to communicate whether a method 333succeeded, what block was produced or modified, and what side-effects the call 334produced. 335 336.. doxygenclass:: pw::allocator::BlockResult 337 :members: 338 339Block implementations 340===================== 341The following combine block mix-ins and provide both the methods they require as 342well as a concrete representation of the data those methods need. 343 344.. _module-pw_allocator-api-small_block: 345 346SmallBlock 347---------- 348This implementation includes just enough mix-ins for fixed-alignment 349allocations. 350 351.. doxygenclass:: pw::allocator::SmallBlock 352 :members: 353 354.. _module-pw_allocator-api-small_alignable_block: 355 356SmallAlignableBlock 357------------------- 358This implementation includes just enough mix-ins for variable-alignment 359allocations. 360 361.. doxygenclass:: pw::allocator::SmallAlignableBlock 362 :members: 363 364.. _module-pw_allocator-api-tiny_block: 365 366TinyBlock 367--------- 368This implementation is similar to :ref:`module-pw_allocator-api-small_block`, 369but packs its information into just 4 bytes of overhead per allocation. This 370constrains both its miniumum and maximum allocatable sizes, and incurs small 371code size and performance costs for packing and unpacking header information. 372 373.. doxygenclass:: pw::allocator::TinyBlock 374 :members: 375 376.. _module-pw_allocator-api-detailed_block: 377 378DetailedBlock 379------------- 380This implementation includes all block mix-ins. This makes it very flexible at 381the cost of additional code size. 382 383.. doxygenstruct:: pw::allocator::DetailedBlockParameters 384 :members: 385 386.. doxygenclass:: pw::allocator::DetailedBlockImpl 387 :members: 388 389.. _module-pw_allocator-api-bucket: 390 391------- 392Buckets 393------- 394Several block allocator implementations improve performance by managing buckets, 395which are data structures that track free blocks. Several bucket implementations 396are provided that trade off between performance and per-block space needed when 397free. 398 399.. _module-pw_allocator-api-bucket_base: 400 401BucketBase 402========== 403This type is not a standalone bucket, but a CRTP-style base class that provides 404the common interface for other blocks. 405 406.. doxygenclass:: pw::allocator::internal::BucketBase 407 :members: 408 409FastSortedBucket 410================ 411.. doxygenclass:: pw::allocator::FastSortedBucket 412 :members: 413 414ForwardSortedBucket 415=================== 416.. doxygenclass:: pw::allocator::ForwardSortedBucket 417 :members: 418 419ReverseFastSortedBucket 420======================= 421.. doxygenclass:: pw::allocator::ReverseFastSortedBucket 422 :members: 423 424ReverseSortedBucket 425=================== 426.. doxygenclass:: pw::allocator::ReverseSortedBucket 427 :members: 428 429SequencedBucket 430=============== 431.. doxygenclass:: pw::allocator::SequencedBucket 432 :members: 433 434UnorderedBucket 435=============== 436.. doxygenclass:: pw::allocator::UnorderedBucket 437 :members: 438 439--------------- 440Utility Classes 441--------------- 442In addition to providing allocator implementations themselves, this module 443includes some utility classes. 444 445.. _module-pw_allocator-api-metrics_adapter: 446 447Metrics 448======= 449.. doxygenclass:: pw::allocator::internal::Metrics 450 :members: 451 452This class is templated on a ``MetricsType`` struct. See 453:ref:`module-pw_allocator-design-metrics` for additional details on how the 454struct, this class, and :ref:`module-pw_allocator-api-tracking_allocator` 455interact. 456 457Module consumers can define their own metrics structs using the 458following macros: 459 460.. doxygendefine:: PW_ALLOCATOR_METRICS_DECLARE 461.. doxygendefine:: PW_ALLOCATOR_METRICS_ENABLE 462 463.. _module-pw_allocator-api-fragmentation: 464 465Fragmentation 466============= 467.. doxygenstruct:: pw::allocator::Fragmentation 468 :members: 469 470 471Buffer management 472================= 473.. doxygenclass:: pw::allocator::WithBuffer 474 :members: 475 476.. _module-pw_allocator-api-size_reports: 477 478------------ 479Size reports 480------------ 481This module includes utilities to help generate code size reports for allocator 482implementations. These are used to generate the code size reports for the 483allocators provided by this module, and can also be used to evaluate your own 484custom allocator implementations. 485 486.. doxygenfunction:: pw::allocator::size_report::GetBuffer 487.. doxygenfunction:: pw::allocator::size_report::MeasureAllocator 488 489------------ 490Test support 491------------ 492This module includes test utilities for allocator implementers. These 493facilitate writing unit tests and fuzz tests for both concrete and forwarding 494allocator implementations. They are not intended to be used by module consumers. 495 496.. _module-pw_allocator-api-allocator_for_test: 497 498AllocatorForTest 499================ 500.. doxygenclass:: pw::allocator::test::AllocatorForTest 501 :members: 502 503.. _module-pw_allocator-api-test_harness: 504 505TestHarness 506=========== 507.. doxygenclass:: pw::allocator::test::TestHarness 508 :members: 509 510.. _module-pw_allocator-api-fuzzing_support: 511 512FuzzTest support 513================ 514.. doxygenfunction:: pw::allocator::test::ArbitraryRequest 515.. doxygenfunction:: pw::allocator::test::ArbitraryRequests 516.. doxygenfunction:: pw::allocator::test::MakeRequest 517