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>
This commit is contained in:
parent
fc6f9e23ce
commit
3416ed2847
2 changed files with 78 additions and 0 deletions
|
@ -38,3 +38,4 @@ structures are thread safe in specific usage scenarios (see
|
||||||
ring_buffers.rst
|
ring_buffers.rst
|
||||||
mpsc_lockfree.rst
|
mpsc_lockfree.rst
|
||||||
spsc_lockfree.rst
|
spsc_lockfree.rst
|
||||||
|
min_heap.rst
|
||||||
|
|
77
doc/kernel/data_structures/min_heap.rst
Normal file
77
doc/kernel/data_structures/min_heap.rst
Normal file
|
@ -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…
Add table
Add a link
Reference in a new issue