src/lib/prio-heap/prio-heap.h

   1 #ifndef _BABELTRACE_PRIO_HEAP_H
   2 #define _BABELTRACE_PRIO_HEAP_H
   3
   4 /*
   5  * Static-sized priority heap containing pointers. Based on CLRS,
   6  * chapter 6.
   7  *
   8  * Copyright 2011 - Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   9  *
  10  * Permission is hereby granted, free of charge, to any person obtaining a copy
  11  * of this software and associated documentation files (the "Software"), to deal
  12  * in the Software without restriction, including without limitation the rights
  13  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  14  * copies of the Software, and to permit persons to whom the Software is
  15  * furnished to do so, subject to the following conditions:
  16  *
  17  * The above copyright notice and this permission notice shall be included in
  18  * all copies or substantial portions of the Software.
  19  *
  20  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  21  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  23  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  24  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  25  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  26  * SOFTWARE.
  27  */
  28
  29 #include <unistd.h>
  30 #include "common/macros.h"
  31
  32 struct ptr_heap {
  33         size_t len, alloc_len;
  34         void **ptrs;
  35         int (*gt)(void *a, void *b);
  36 };
  37
  38 #ifdef DEBUG_HEAP
  39 void check_heap(const struct ptr_heap *heap);
  40 #else
  41 static inline
  42 void check_heap(const struct ptr_heap *heap)
  43 {
  44 }
  45 #endif
  46
  47 /**
  48  * bt_heap_maximum - return the largest element in the heap
  49  * @heap: the heap to be operated on
  50  *
  51  * Returns the largest element in the heap, without performing any modification
  52  * to the heap structure. Returns NULL if the heap is empty.
  53  */
  54 static inline void *bt_heap_maximum(const struct ptr_heap *heap)
  55 {
  56         check_heap(heap);
  57         return G_LIKELY(heap->len) ? heap->ptrs[0] : NULL;
  58 }
  59
  60 /**
  61  * bt_heap_init - initialize the heap
  62  * @heap: the heap to initialize
  63  * @alloc_len: number of elements initially allocated
  64  * @gt: function to compare the elements
  65  *
  66  * Returns -ENOMEM if out of memory.
  67  */
  68 BT_HIDDEN
  69 extern int bt_heap_init(struct ptr_heap *heap,
  70                      size_t alloc_len,
  71                      int gt(void *a, void *b));
  72
  73 /**
  74  * bt_heap_free - free the heap
  75  * @heap: the heap to free
  76  */
  77 BT_HIDDEN
  78 extern void bt_heap_free(struct ptr_heap *heap);
  79
  80 /**
  81  * bt_heap_insert - insert an element into the heap
  82  * @heap: the heap to be operated on
  83  * @p: the element to add
  84  *
  85  * Insert an element into the heap.
  86  *
  87  * Returns -ENOMEM if out of memory.
  88  */
  89 BT_HIDDEN
  90 extern int bt_heap_insert(struct ptr_heap *heap, void *p);
  91
  92 /**
  93  * bt_heap_remove - remove the largest element from the heap
  94  * @heap: the heap to be operated on
  95  *
  96  * Returns the largest element in the heap. It removes this element from the
  97  * heap. Returns NULL if the heap is empty.
  98  */
  99 BT_HIDDEN
 100 extern void *bt_heap_remove(struct ptr_heap *heap);
 101
 102 /**
 103  * bt_heap_cherrypick - remove a given element from the heap
 104  * @heap: the heap to be operated on
 105  * @p: the element
 106  *
 107  * Remove the given element from the heap. Return the element if present, else
 108  * return NULL. This algorithm has a complexity of O(n), which is higher than
 109  * O(log(n)) provided by the rest of this API.
 110  */
 111 BT_HIDDEN
 112 extern void *bt_heap_cherrypick(struct ptr_heap *heap, void *p);
 113
 114 /**
 115  * bt_heap_replace_max - replace the the largest element from the heap
 116  * @heap: the heap to be operated on
 117  * @p: the pointer to be inserted as topmost element replacement
 118  *
 119  * Returns the largest element in the heap. It removes this element from the
 120  * heap. The heap is rebalanced only once after the insertion. Returns NULL if
 121  * the heap is empty.
 122  *
 123  * This is the equivalent of calling bt_heap_remove() and then bt_heap_insert(), but
 124  * it only rebalances the heap once. It never allocates memory.
 125  */
 126 BT_HIDDEN
 127 extern void *bt_heap_replace_max(struct ptr_heap *heap, void *p);
 128
 129 /**
 130  * bt_heap_copy - copy a heap
 131  * @dst: the destination heap (must be allocated)
 132  * @src: the source heap
 133  *
 134  * Returns -ENOMEM if out of memory.
 135  */
 136 BT_HIDDEN
 137 extern int bt_heap_copy(struct ptr_heap *dst, struct ptr_heap *src);
 138
 139 #endif /* _BABELTRACE_PRIO_HEAP_H */