From 3416ed2847aa27e22e98262fc66ada2b61d63cfd Mon Sep 17 00:00:00 2001
From: Sayooj K Karun <sayooj@aerlync.com>
Date: Sat, 7 Jun 2025 11:43:33 +0530
Subject: [PATCH] doc: kernel: data_structures: Add documentation for min-heap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 doc/kernel/data_structures/index.rst    |  1 +
 doc/kernel/data_structures/min_heap.rst | 77 +++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 doc/kernel/data_structures/min_heap.rst

diff --git a/doc/kernel/data_structures/index.rst b/doc/kernel/data_structures/index.rst
index e7fac7da201..b67cff1be19 100644
--- a/doc/kernel/data_structures/index.rst
+++ b/doc/kernel/data_structures/index.rst
@@ -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
diff --git a/doc/kernel/data_structures/min_heap.rst b/doc/kernel/data_structures/min_heap.rst
new file mode 100644
index 00000000000..3e1dc189913
--- /dev/null
+++ b/doc/kernel/data_structures/min_heap.rst
@@ -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