Browse Source

doc: kernel: data_structures: Add documentation for min-heap

Includes explanation of the min-heap’s properties, constraints and
explains about the uses cases of min-heap. It also contains references
to Sample Application and min-heap API

Signed-off-by: Sayooj K Karun <sayooj@aerlync.com>
pull/91334/head
Sayooj K Karun 1 month ago committed by Fabio Baltieri
parent
commit
3416ed2847
  1. 1
      doc/kernel/data_structures/index.rst
  2. 77
      doc/kernel/data_structures/min_heap.rst

1
doc/kernel/data_structures/index.rst

@ -38,3 +38,4 @@ structures are thread safe in specific usage scenarios (see @@ -38,3 +38,4 @@ structures are thread safe in specific usage scenarios (see
ring_buffers.rst
mpsc_lockfree.rst
spsc_lockfree.rst
min_heap.rst

77
doc/kernel/data_structures/min_heap.rst

@ -0,0 +1,77 @@ @@ -0,0 +1,77 @@
.. _min_heap_api:
Min-Heap Data Structure
#######################
.. contents::
:local:
:depth: 2
The Min-Heap implementation provides an efficient data structure for
managing a dynamically changing list of elements while maintaining the ability
to quickly extract the minimum value. It's a tree-based data structure that
satisfies the heap property and supports common operations such as insertion,
removal and popping the minimum element from the Min-Heap
This section explains the motivation behind the implementation, its internal
structure, API usage, and example scenarios for embedded systems and real-time
environments.
Heap Structure
**************
The heap is maintained as a complete binary tree stored in an array.
Each node satisfies the **min-heap** property:
- The value of each node is less than or equal to the values of its children.
This property ensures that the **minimum element is always at the root**
(index 0).
.. code-block:: text
Index: 0 1 2 3 4 5 6
Values: [1, 3, 5, 8, 9, 10, 12]
1
/ \
3 5
/ \ / \
8 9 10 12
For any node at index ``i``, its children are at indices:
- Left child: :math:`2*i + 1`
- Right child: :math:`2*i + 2`
Its parent is at index:
- Parent: :math:`(i - 1) / 2`
Use Cases
*********
MinHeap is well suited for:
- Implementing priority queues
- Sorting data incrementally
- Resource arbitration (e.g., lowest-cost resource selection)
- Scheduling in cooperative multitasking systems
- Managing timeouts and delay queues
- Priority-based sensor or data sampling
In RTOS environments like Zephyr, this heap can be used in kernel-level or
application-level modules where minimal latency to obtain the highest priority
resource is needed.
Samples
*******
:zephyr:code-sample:`min-heap` sample demos the API usage of Min-Heap
implementation in Zephyr RTOS.
API Reference
*************
.. doxygengroup:: min_heap_apis
Loading…
Cancel
Save