1.. _module-pw_allocator: 2 3============ 4pw_allocator 5============ 6.. pigweed-module:: 7 :name: pw_allocator 8 9- **Flexible**: Simple interface makes it easy to inject specific behaviors. 10- **Safe**: Can detect memory corruption, e.g overflows and use-after-free. 11- **Measurable**: Pick what allocations you want to track and measure. 12 13.. literalinclude:: examples/basic.cc 14 :language: cpp 15 :linenos: 16 :start-after: [pw_allocator-examples-basic-allocate] 17 :end-before: [pw_allocator-examples-basic-allocate] 18 19.. code-block:: cpp 20 21 // Any of these allocators can be passed to the routine above. 22 WithBuffer<LastFitBlockAllocator<uint32_t>, 0x1000> block_allocator; 23 LibCAllocator libc_allocator; 24 TrackingAllocator tracker(libc_allocator); 25 SynchronizedAllocator synced(*block_allocator); 26 27 28Dynamically allocate without giving up control! Pigweed's allocators let you 29easily combine allocator features for your needs, without extra code size or 30performance penalties for those you don't. Complex projects in particular can 31benefit from dynamic allocation through simplified code, improved memory usage, 32increased shared memory, and reduced large reservations. 33 34**Want to allocate objects from specific memory like SRAM or PSRAM?** 35 36Use `dependency injection`_! Write your code to take 37:ref:`module-pw_allocator-api-allocator` parameters, and you can quickly and 38easily change where memory comes from or what additional features are provided 39simply by changing what allocator is passed: 40 41.. literalinclude:: examples/linker_sections.cc 42 :language: cpp 43 :linenos: 44 :start-after: [pw_allocator-examples-linker_sections-injection] 45 :end-before: [pw_allocator-examples-linker_sections-injection] 46 47Now you can easily allocate objects in the example above using SRAM, PSRAM, or 48both: 49 50.. literalinclude:: examples/linker_sections.cc 51 :language: cpp 52 :linenos: 53 :start-after: [pw_allocator-examples-linker_sections-placement] 54 :end-before: [pw_allocator-examples-linker_sections-placement] 55 56**Worried about forgetting to deallocate?** 57 58Use a smart pointer! 59 60.. literalinclude:: examples/basic.cc 61 :language: cpp 62 :linenos: 63 :start-after: [pw_allocator-examples-basic-make_unique] 64 :end-before: [pw_allocator-examples-basic-make_unique] 65 66**Want to know how much memory has been allocated?** 67 68Pick the metrics you're interested in and track them with a 69:ref:`module-pw_allocator-api-tracking_allocator`: 70 71.. literalinclude:: examples/metrics.cc 72 :language: cpp 73 :linenos: 74 :start-after: [pw_allocator-examples-metrics-custom_metrics1] 75 :end-before: [pw_allocator-examples-metrics-custom_metrics1] 76 77.. literalinclude:: examples/metrics.cc 78 :language: cpp 79 :linenos: 80 :start-after: [pw_allocator-examples-metrics-custom_metrics2] 81 :end-before: [pw_allocator-examples-metrics-custom_metrics2] 82 83**Need to share the allocator with another thread or an interrupt handler?** 84 85Use a :ref:`module-pw_allocator-api-synchronized_allocator` with the lock of 86your choice: 87 88.. literalinclude:: examples/spin_lock.cc 89 :language: cpp 90 :linenos: 91 :start-after: [pw_allocator-examples-spin_lock] 92 :end-before: [pw_allocator-examples-spin_lock] 93 94.. tip:: Check out the :ref:`module-pw_allocator-guides` for even more code 95 samples! 96 97-------------------- 98Is it right for you? 99-------------------- 100.. rst-class:: key-text 101 102Does your project need to use memory... 103 104- Without knowing exactly how much ahead of time? 105- From different backing storage, e.g. SRAM vs. PSRAM? 106- Across different tasks using a shared pool? 107- In multiple places, and you need to know how much each place is using? 108 109If you answered "yes" to any of these questions, ``pw_allocator`` may be able to 110help! This module is designed to faciliate dynamic allocation for embedded 111projects that are sufficiently complex to make static allocation infeasible. 112 113Smaller projects may be able to enumerate their objects and preallocate any 114storage they may need on device when running, and may be subject to extremely 115tight memory constraints. In these cases, ``pw_allocator`` may add more costs in 116terms of code size, overhead, and performance than it provides benefits in terms 117of code simplicity and memory sharing. 118 119At the other extreme, larger projects may be built on platforms with rich 120operating system capabilities. On these platforms, the system and language 121runtime may already provide dynamic allocation and memory may be less 122constrained. In these cases, ``pw_allocator`` may not provide the same 123capabilities as the platform. 124 125Between these two is a range of complex projects on RTOSes and other platforms. 126These projects may benefit from using the 127:ref:`module-pw_allocator-api-allocator` interface and its implementations to 128manage memory. 129 130.. toctree:: 131 :hidden: 132 :maxdepth: 1 133 134 guide 135 api 136 design 137 code_size 138 139.. grid:: 2 140 141 .. grid-item-card:: :octicon:`rocket` Guides 142 :link: module-pw_allocator-guides 143 :link-type: ref 144 :class-item: sales-pitch-cta-primary 145 146 Integrate pw_allocator into your project and learn common use cases 147 148 .. grid-item-card:: :octicon:`code-square` API reference 149 :link: module-pw_allocator-api 150 :link-type: ref 151 :class-item: sales-pitch-cta-secondary 152 153 Detailed description of the pw_allocator's API 154 155.. grid:: 2 156 157 .. grid-item-card:: :octicon:`code-square` Design & roadmap 158 :link: module-pw_allocator-design 159 :link-type: ref 160 :class-item: sales-pitch-cta-secondary 161 162 Learn why pw_allocator is designed the way it is, and upcoming plans 163 164 .. grid-item-card:: :octicon:`code-square` Code size analysis 165 :link: module-pw_allocator-size-reports 166 :link-type: ref 167 :class-item: sales-pitch-cta-secondary 168 169 Understand pw_allocator's code footprint and savings potential 170 171.. _dependency injection: https://en.wikipedia.org/wiki/Dependency_injection 172