.. _heap_v2:

Heap Memory Pool
################

The :dfn:`heap memory pool` is a pre-defined memory pool object that allows
threads to dynamically allocate memory from a common memory region
in a :cpp:func:`malloc()`-like manner.

.. contents::
    :local:
    :depth: 2

Concepts
********

Only a single heap memory pool can be defined. Unlike other memory pools,
the heap memory pool cannot be directly referenced using its memory address.

The size of the heap memory pool is configurable. The following sizes
are supported: 256 bytes, 1024 bytes, 4096 bytes, and 16384 bytes.

A thread can dynamically allocate a chunk of heap memory by calling
:cpp:func:`k_malloc()`. The address of the allocated chunk is guaranteed
to be aligned on a multiple of 4 bytes. If a suitable chunk of heap memory
cannot be found :c:macro:`NULL` is returned.

When the thread is finished with a chunk of heap memory it can release
the chunk back to the heap memory pool by calling :cpp:func:`k_free()`.

Internal Operation
==================

The heap memory pool defines a single maximum size block that contains
the entire heap; that is, a single block of 256, 1024, 4096, or 16384 bytes.
The heap memory pool also defines a minimum block size of 64 bytes.
Consequently, the maximum number of blocks of each size that the heap
memory pool can support is shown in the following table.

+-------+---------+----------+-----------+-----------+------------+
| heap  | 64 byte | 256 byte | 1024 byte | 4096 byte | 16384 byte |
| size  | blocks  | blocks   | blocks    | blocks    | blocks     |
+=======+=========+==========+===========+===========+============+
| 256   | 4       | 1        | 0         | 0         | 0          |
+-------+---------+----------+-----------+-----------+------------+
| 1024  | 16      | 4        | 1         | 0         | 0          |
+-------+---------+----------+-----------+-----------+------------+
| 4096  | 64      | 16       | 4         | 1         | 0          |
+-------+---------+----------+-----------+-----------+------------+
| 16384 | 256     | 64       | 16        | 4         | 1          |
+-------+---------+----------+-----------+-----------+------------+

.. note::
    The number of blocks of a given size that can be allocated
    simultaneously is typically smaller than the value shown in the table.
    For example, each allocation of a 256 byte block from a 1024 byte
    heap reduces the number of 64 byte blocks available for allocation
    by 4. Fragmentation of the memory pool's buffer can also further
    reduce the availability of blocks.

The kernel uses the first 16 bytes of any memory block allocated
from the heap memory pool to save the block descriptor information
it needs to later free the block. Consequently, an application's request
for an N byte chunk of heap memory requires a block that is at least
(N+16) bytes long.

Implementation
**************

Defining the Heap Memory Pool
=============================

The size of the heap memory pool is specified using the
:option:`CONFIG_HEAP_MEM_POOL_SIZE` configuration option.

By default, the heap memory pool size is zero bytes. This value instructs
the kernel not to define the heap memory pool object.

Allocating Memory
=================

A chunk of heap memory is allocated by calling :cpp:func:`k_malloc()`.

The following code allocates a 200 byte chunk of heap memory, then fills it
with zeros. A warning is issued if a suitable chunk is not obtained.

Note that the application will actually allocate a 256 byte memory block,
since that is the closest matching size supported by the heap memory pool.

.. code-block:: c

    char *mem_ptr;

    mem_ptr = k_malloc(200);
    if (mem_ptr != NULL)) {
        memset(mem_ptr, 0, 200);
	...
    } else {
        printf("Memory not allocated");
    }

Releasing Memory
================

A chunk of heap memory is released by calling :cpp:func:`k_free()`.

The following code allocates a 75 byte chunk of memory, then releases it
once it is no longer needed. (A 256 byte memory block from the heap memory
pool is actually used to satisfy the request.)

.. code-block:: c

    char *mem_ptr;

    mem_ptr = k_malloc(75);
    ... /* use memory block */
    k_free(mem_ptr);

Suggested Uses
**************

Use the heap memory pool to dynamically allocate memory in a
:cpp:func:`malloc()`-like manner.

Configuration Options
*********************

Related configuration options:

* :option:`CONFIG_HEAP_MEM_POOL_SIZE`

APIs
****

The following heap memory pool APIs are provided by :file:`kernel.h`:

* :cpp:func:`k_malloc()`
* :cpp:func:`k_free()`