1.. _min_heap_api:
2
3Min-Heap Data Structure
4#######################
5
6.. contents::
7  :local:
8  :depth: 2
9
10The Min-Heap implementation provides an efficient data structure for
11managing a dynamically changing list of elements while maintaining the ability
12to quickly extract the minimum value. It's a tree-based data structure that
13satisfies the heap property and supports common operations such as insertion,
14removal and popping the minimum element from the Min-Heap
15
16This section explains the motivation behind the implementation, its internal
17structure, API usage, and example scenarios for embedded systems and real-time
18environments.
19
20Heap Structure
21**************
22
23The heap is maintained as a complete binary tree stored in an array.
24Each node satisfies the **min-heap** property:
25
26   - The value of each node is less than or equal to the values of its children.
27
28This property ensures that the **minimum element is always at the root**
29(index 0).
30
31.. code-block:: text
32
33    Index:      0   1   2   3   4   5   6
34    Values:    [1,  3,  5,  8,  9, 10, 12]
35
36                   1
37                 /   \
38               3       5
39              / \     / \
40             8   9  10  12
41
42For any node at index ``i``, its children are at indices:
43
44- Left child: :math:`2*i + 1`
45
46- Right child: :math:`2*i + 2`
47
48Its parent is at index:
49
50- Parent: :math:`(i - 1) / 2`
51
52Use Cases
53*********
54
55MinHeap is well suited for:
56
57- Implementing priority queues
58- Sorting data incrementally
59- Resource arbitration (e.g., lowest-cost resource selection)
60- Scheduling in cooperative multitasking systems
61- Managing timeouts and delay queues
62- Priority-based sensor or data sampling
63
64In RTOS environments like Zephyr, this heap can be used in kernel-level or
65application-level modules where minimal latency to obtain the highest priority
66resource is needed.
67
68Samples
69*******
70
71 :zephyr:code-sample:`min-heap` sample demos the API usage of Min-Heap
72 implementation in Zephyr RTOS.
73
74API Reference
75*************
76
77.. doxygengroup:: min_heap_apis
78