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/babeltrace.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 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 extern int bt_heap_init(struct ptr_heap *heap,
  69                      size_t alloc_len,
  70                      int gt(void *a, void *b));
  71
  72 /**
  73  * bt_heap_free - free the heap
  74  * @heap: the heap to free
  75  */
  76 extern void bt_heap_free(struct ptr_heap *heap);
  77
  78 /**
  79  * bt_heap_insert - insert an element into the heap
  80  * @heap: the heap to be operated on
  81  * @p: the element to add
  82  *
  83  * Insert an element into the heap.
  84  *
  85  * Returns -ENOMEM if out of memory.
  86  */
  87 extern int bt_heap_insert(struct ptr_heap *heap, void *p);
  88
  89 /**
  90  * bt_heap_remove - remove the largest element from the heap
  91  * @heap: the heap to be operated on
  92  *
  93  * Returns the largest element in the heap. It removes this element from the
  94  * heap. Returns NULL if the heap is empty.
  95  */
  96 extern void *bt_heap_remove(struct ptr_heap *heap);
  97
  98 /**
  99  * bt_heap_cherrypick - remove a given element from the heap
 100  * @heap: the heap to be operated on
 101  * @p: the element
 102  *
 103  * Remove the given element from the heap. Return the element if present, else
 104  * return NULL. This algorithm has a complexity of O(n), which is higher than
 105  * O(log(n)) provided by the rest of this API.
 106  */
 107 extern void *bt_heap_cherrypick(struct ptr_heap *heap, void *p);
 108
 109 /**
 110  * bt_heap_replace_max - replace the the largest element from the heap
 111  * @heap: the heap to be operated on
 112  * @p: the pointer to be inserted as topmost element replacement
 113  *
 114  * Returns the largest element in the heap. It removes this element from the
 115  * heap. The heap is rebalanced only once after the insertion. Returns NULL if
 116  * the heap is empty.
 117  *
 118  * This is the equivalent of calling bt_heap_remove() and then bt_heap_insert(), but
 119  * it only rebalances the heap once. It never allocates memory.
 120  */
 121 extern void *bt_heap_replace_max(struct ptr_heap *heap, void *p);
 122
 123 /**
 124  * bt_heap_copy - copy a heap
 125  * @dst: the destination heap (must be allocated)
 126  * @src: the source heap
 127  *
 128  * Returns -ENOMEM if out of memory.
 129  */
 130 extern int bt_heap_copy(struct ptr_heap *dst, struct ptr_heap *src);
 131
 132 #endif /* _BABELTRACE_PRIO_HEAP_H */