include/linux/min_heap.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 #ifndef _LINUX_MIN_HEAP_H
   3 #define _LINUX_MIN_HEAP_H
   4
   5 #include <linux/bug.h>
   6 #include <linux/string.h>
   7 #include <linux/types.h>
   8
   9 /**
  10  * Data structure to hold a min-heap.
  11  * @nr: Number of elements currently in the heap.
  12  * @size: Maximum number of elements that can be held in current storage.
  13  * @data: Pointer to the start of array holding the heap elements.
  14  * @preallocated: Start of the static preallocated array holding the heap elements.
  15  */
  16 #define MIN_HEAP_PREALLOCATED(_type, _name, _nr)        \
  17 struct _name {  \
  18         int nr; \
  19         int size;       \
  20         _type *data;    \
  21         _type preallocated[_nr];        \
  22 }
  23
  24 #define DEFINE_MIN_HEAP(_type, _name) MIN_HEAP_PREALLOCATED(_type, _name, 0)
  25
  26 typedef DEFINE_MIN_HEAP(char, min_heap_char) min_heap_char;
  27
  28 #define __minheap_cast(_heap)           (typeof((_heap)->data[0]) *)
  29 #define __minheap_obj_size(_heap)       sizeof((_heap)->data[0])
  30
  31 /**
  32  * struct min_heap_callbacks - Data/functions to customise the min_heap.
  33  * @less: Partial order function for this heap.
  34  * @swp: Swap elements function.
  35  */
  36 struct min_heap_callbacks {
  37         bool (*less)(const void *lhs, const void *rhs, void *args);
  38         void (*swp)(void *lhs, void *rhs, void *args);
  39 };
  40
  41 /* Initialize a min-heap. */
  42 static __always_inline
  43 void __min_heap_init(min_heap_char *heap, void *data, int size)
  44 {
  45         heap->nr = 0;
  46         heap->size = size;
  47         if (data)
  48                 heap->data = data;
  49         else
  50                 heap->data = heap->preallocated;
  51 }
  52
  53 #define min_heap_init(_heap, _data, _size)      \
  54         __min_heap_init((min_heap_char *)_heap, _data, _size)
  55
  56 /* Get the minimum element from the heap. */
  57 static __always_inline
  58 void *__min_heap_peek(struct min_heap_char *heap)
  59 {
  60         return heap->nr ? heap->data : NULL;
  61 }
  62
  63 #define min_heap_peek(_heap)    \
  64         (__minheap_cast(_heap) __min_heap_peek((min_heap_char *)_heap))
  65
  66 /* Check if the heap is full. */
  67 static __always_inline
  68 bool __min_heap_full(min_heap_char *heap)
  69 {
  70         return heap->nr == heap->size;
  71 }
  72
  73 #define min_heap_full(_heap)    \
  74         __min_heap_full((min_heap_char *)_heap)
  75
  76 /* Sift the element at pos down the heap. */
  77 static __always_inline
  78 void __min_heap_sift_down(min_heap_char *heap, int pos, size_t elem_size,
  79                 const struct min_heap_callbacks *func, void *args)
  80 {
  81         void *left, *right;
  82         void *data = heap->data;
  83         void *root = data + pos * elem_size;
  84         int i = pos, j;
  85
  86         /* Find the sift-down path all the way to the leaves. */
  87         for (;;) {
  88                 if (i * 2 + 2 >= heap->nr)
  89                         break;
  90                 left = data + (i * 2 + 1) * elem_size;
  91                 right = data + (i * 2 + 2) * elem_size;
  92                 i = func->less(left, right, args) ? i * 2 + 1 : i * 2 + 2;
  93         }
  94
  95         /* Special case for the last leaf with no sibling. */
  96         if (i * 2 + 2 == heap->nr)
  97                 i = i * 2 + 1;
  98
  99         /* Backtrack to the correct location. */
 100         while (i != pos && func->less(root, data + i * elem_size, args))
 101                 i = (i - 1) / 2;
 102
 103         /* Shift the element into its correct place. */
 104         j = i;
 105         while (i != pos) {
 106                 i = (i - 1) / 2;
 107                 func->swp(data + i * elem_size, data + j * elem_size, args);
 108         }
 109 }
 110
 111 #define min_heap_sift_down(_heap, _pos, _func, _args)   \
 112         __min_heap_sift_down((min_heap_char *)_heap, _pos, __minheap_obj_size(_heap), _func, _args)
 113
 114 /* Sift up ith element from the heap, O(log2(nr)). */
 115 static __always_inline
 116 void __min_heap_sift_up(min_heap_char *heap, size_t elem_size, size_t idx,
 117                 const struct min_heap_callbacks *func, void *args)
 118 {
 119         void *data = heap->data;
 120         size_t parent;
 121
 122         while (idx) {
 123                 parent = (idx - 1) / 2;
 124                 if (func->less(data + parent * elem_size, data + idx * elem_size, args))
 125                         break;
 126                 func->swp(data + parent * elem_size, data + idx * elem_size, args);
 127                 idx = parent;
 128         }
 129 }
 130
 131 #define min_heap_sift_up(_heap, _idx, _func, _args)     \
 132         __min_heap_sift_up((min_heap_char *)_heap, __minheap_obj_size(_heap), _idx, _func, _args)
 133
 134 /* Floyd's approach to heapification that is O(nr). */
 135 static __always_inline
 136 void __min_heapify_all(min_heap_char *heap, size_t elem_size,
 137                 const struct min_heap_callbacks *func, void *args)
 138 {
 139         int i;
 140
 141         for (i = heap->nr / 2 - 1; i >= 0; i--)
 142                 __min_heap_sift_down(heap, i, elem_size, func, args);
 143 }
 144
 145 #define min_heapify_all(_heap, _func, _args)    \
 146         __min_heapify_all((min_heap_char *)_heap, __minheap_obj_size(_heap), _func, _args)
 147
 148 /* Remove minimum element from the heap, O(log2(nr)). */
 149 static __always_inline
 150 bool __min_heap_pop(min_heap_char *heap, size_t elem_size,
 151                 const struct min_heap_callbacks *func, void *args)
 152 {
 153         void *data = heap->data;
 154
 155         if (WARN_ONCE(heap->nr <= 0, "Popping an empty heap"))
 156                 return false;
 157
 158         /* Place last element at the root (position 0) and then sift down. */
 159         heap->nr--;
 160         memcpy(data, data + (heap->nr * elem_size), elem_size);
 161         __min_heap_sift_down(heap, 0, elem_size, func, args);
 162
 163         return true;
 164 }
 165
 166 #define min_heap_pop(_heap, _func, _args)       \
 167         __min_heap_pop((min_heap_char *)_heap, __minheap_obj_size(_heap), _func, _args)
 168
 169 /*
 170  * Remove the minimum element and then push the given element. The
 171  * implementation performs 1 sift (O(log2(nr))) and is therefore more
 172  * efficient than a pop followed by a push that does 2.
 173  */
 174 static __always_inline
 175 void __min_heap_pop_push(min_heap_char *heap,
 176                 const void *element, size_t elem_size,
 177                 const struct min_heap_callbacks *func,
 178                 void *args)
 179 {
 180         memcpy(heap->data, element, elem_size);
 181         __min_heap_sift_down(heap, 0, elem_size, func, args);
 182 }
 183
 184 #define min_heap_pop_push(_heap, _element, _func, _args)        \
 185         __min_heap_pop_push((min_heap_char *)_heap, _element, __minheap_obj_size(_heap), _func, _args)
 186
 187 /* Push an element on to the heap, O(log2(nr)). */
 188 static __always_inline
 189 bool __min_heap_push(min_heap_char *heap, const void *element, size_t elem_size,
 190                 const struct min_heap_callbacks *func, void *args)
 191 {
 192         void *data = heap->data;
 193         int pos;
 194
 195         if (WARN_ONCE(heap->nr >= heap->size, "Pushing on a full heap"))
 196                 return false;
 197
 198         /* Place at the end of data. */
 199         pos = heap->nr;
 200         memcpy(data + (pos * elem_size), element, elem_size);
 201         heap->nr++;
 202
 203         /* Sift child at pos up. */
 204         __min_heap_sift_up(heap, elem_size, pos, func, args);
 205
 206         return true;
 207 }
 208
 209 #define min_heap_push(_heap, _element, _func, _args)    \
 210         __min_heap_push((min_heap_char *)_heap, _element, __minheap_obj_size(_heap), _func, _args)
 211
 212 /* Remove ith element from the heap, O(log2(nr)). */
 213 static __always_inline
 214 bool __min_heap_del(min_heap_char *heap, size_t elem_size, size_t idx,
 215                 const struct min_heap_callbacks *func, void *args)
 216 {
 217         void *data = heap->data;
 218
 219         if (WARN_ONCE(heap->nr <= 0, "Popping an empty heap"))
 220                 return false;
 221
 222         /* Place last element at the root (position 0) and then sift down. */
 223         heap->nr--;
 224         if (idx == heap->nr)
 225                 return true;
 226         func->swp(data + (idx * elem_size), data + (heap->nr * elem_size), args);
 227         __min_heap_sift_up(heap, elem_size, idx, func, args);
 228         __min_heap_sift_down(heap, idx, elem_size, func, args);
 229
 230         return true;
 231 }
 232
 233 #define min_heap_del(_heap, _idx, _func, _args) \
 234         __min_heap_del((min_heap_char *)_heap, __minheap_obj_size(_heap), _idx, _func, _args)
 235
 236 #endif /* _LINUX_MIN_HEAP_H */