1.. _module-pw_malloc: 2 3========= 4pw_malloc 5========= 6This module defines an interface for replacing the standard libc dynamic memory 7operations. 8 9This facade doesn't implement any heap structure or dynamic memory methods. It 10only requires that backends implements ``pw::malloc::GetSystemAllocator`` and 11optionally ``pw::malloc::InitSystemAllocator``. These functions are called 12before static initialization, and are responsible for initializing global data 13structures required by the ``malloc`` implementation. 14 15The intent of this module is to provide an interface for user-provided dynamic 16memory operations that is compatible with different implementations. 17 18----- 19Setup 20----- 21This module requires the following setup: 22 231. Choose a ``pw_malloc`` backend, or write one yourself. 242. Select a backend in your build system. If using GN build, Specify the 25 ``pw_malloc_BACKEND`` GN build arg to point to the library that provides a 26 ``pw_malloc`` backend. If using the Bazel build, add the constraint value for 27 the backend library that provides a ``pw_malloc`` backend. 283. Add a dependency on the ``pw_malloc`` facade in your targets ``executable`` 29 build template, e.g.: 30 31.. code-block:: 32 33 template("platform_executable") { 34 target("executable", target_name) { 35 deps = [] 36 config = [] 37 forward_variables_from(invoker, "*") 38 if (pw_malloc_BACKEND != "") { 39 deps += [ dir_pw_malloc ] 40 } 41 } 42 } 43 44Compile-time configuration 45========================== 46This module has configuration options that globally affect the behavior of 47``pw_malloc`` via compile-time configuration of this module. 48 49.. doxygendefine:: PW_MALLOC_LOCK_TYPE 50.. doxygendefine:: PW_MALLOC_METRICS_TYPE 51.. doxygendefine:: PW_MALLOC_BLOCK_OFFSET_TYPE 52.. doxygendefine:: PW_MALLOC_BLOCK_POISON_INTERVAL 53.. doxygendefine:: PW_MALLOC_BLOCK_ALIGNMENT 54.. doxygendefine:: PW_MALLOC_MIN_BUCKET_SIZE 55.. doxygendefine:: PW_MALLOC_NUM_BUCKETS 56.. doxygendefine:: PW_MALLOC_DUAL_FIRST_FIT_THRESHOLD 57 58See the 59:ref:`module documentation <module-structure-compile-time-configuration>` for 60more details. 61 62Heap initialization 63=================== 64You can provide a region of memory to use as heap as either a byte span or a 65pair of addresses to ``pw::malloc::InitSystemAllocator``. 66 67----- 68Usage 69----- 70Once the heap is initialized, you may simply use ``malloc`` and ``free`` as you 71would normally, as well as standard library functions like ``strdup`` and 72built-in routines like ``new`` that use those functions. 73 74If you configured a ``PW_MALLOC_METRICS_TYPE``, you can retrieve metrics using 75``pw::malloc::GetSystemMetrics()``. 76 77.. toctree:: 78 :maxdepth: 1 79 :hidden: 80 81 Backends <backends> 82