No need to rebalance heap for insertion

[lttng-modules.git] / lib / prio_heap / prio_heap.h

diff --git a/lib/prio_heap/prio_heap.h b/lib/prio_heap/prio_heap.h
index 3c0588716837a527ea6dbc3fa9003f41fdaee874..2674db21fb8496d5e5a7ceacd5ad26ce1af756f6 100644 (file)
--- a/lib/prio_heap/prio_heap.h
+++ b/lib/prio_heap/prio_heap.h
@@ -1,29 +1,31 @@
-/*
- * LICENSING: this file is copied from the Linux kernel. We should therefore
- * assume a GPLv2 license for the code that comes from the Linux mainline.
- */
-
-#ifndef _LINUX_PRIO_HEAP_H
-#define _LINUX_PRIO_HEAP_H
+#ifndef _LTTNG_PRIO_HEAP_H
+#define _LTTNG_PRIO_HEAP_H
 
 /*
- * Static-sized priority heap containing pointers. Based on CLR, chapter 7.
+ * prio_heap.h
+ *
+ * Priority heap containing pointers. Based on CLRS, chapter 6.
+ *
+ * Copyright 2011 - Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
  */
 
 #include <linux/gfp.h>
 
-/**
- * struct ptr_heap - simple static-sized priority heap
- * @ptrs - pointer to data area
- * @max - max number of elements that can be stored in @ptrs
- * @size - current number of valid elements in @ptrs (in the range 0..@size-1
- * @gt: comparison operator, which should implement "greater than"
- */
 struct ptr_heap {
+       size_t len, alloc_len;
        void **ptrs;
-       int max;
-       int size;
-       int (*gt)(void *, void *);
+       int (*gt)(void *a, void *b);
+       gfp_t gfpmask;
 };
 
 /**
@@ -35,39 +37,38 @@ struct ptr_heap {
  */
 static inline void *heap_maximum(const struct ptr_heap *heap)
 {
-       return heap->size ? heap->ptrs[0] : NULL;
+       return heap->len ? heap->ptrs[0] : NULL;
 }
 
 /**
- * heap_init - initialize an empty heap with a given memory size
- * @heap: the heap structure to be initialized
- * @size: amount of memory to use in bytes
- * @gfp_mask: mask to pass to kmalloc()
- * @gt: comparison operator, which should implement "greater than"
+ * heap_init - initialize the heap
+ * @heap: the heap to initialize
+ * @alloc_len: number of elements initially allocated
+ * @gfp: allocation flags
+ * @gt: function to compare the elements
+ *
+ * Returns -ENOMEM if out of memory.
  */
-extern int heap_init(struct ptr_heap *heap, size_t size, gfp_t gfp_mask,
-                    int (*gt)(void *, void *));
+extern int heap_init(struct ptr_heap *heap,
+                    size_t alloc_len, gfp_t gfpmask,
+                    int gt(void *a, void *b));
 
 /**
- * heap_free - release a heap's storage
- * @heap: the heap structure whose data should be released
+ * heap_free - free the heap
+ * @heap: the heap to free
  */
-void heap_free(struct ptr_heap *heap);
+extern void heap_free(struct ptr_heap *heap);
 
 /**
- * heap_insert - insert a value into the heap and return any overflowed value
+ * heap_insert - insert an element into the heap
  * @heap: the heap to be operated on
- * @p: the pointer to be inserted
+ * @p: the element to add
+ *
+ * Insert an element into the heap.
  *
- * Attempts to insert the given value into the priority heap. If the
- * heap is full prior to the insertion, then the resulting heap will
- * consist of the smallest @max elements of the original heap and the
- * new element; the greatest element will be removed from the heap and
- * returned. Note that the returned element will be the new element
- * (i.e. no change to the heap) if the new element is greater than all
- * elements currently in the heap.
+ * Returns -ENOMEM if out of memory.
  */
-extern void *heap_insert(struct ptr_heap *heap, void *p);
+extern int heap_insert(struct ptr_heap *heap, void *p);
 
 /**
  * heap_remove - remove the largest element from the heap
@@ -99,8 +100,8 @@ extern void *heap_cherrypick(struct ptr_heap *heap, void *p);
  * the heap is empty.
  *
  * This is the equivalent of calling heap_remove() and then heap_insert(), but
- * it only rebalances the heap once.
+ * it only rebalances the heap once. It never allocates memory.
  */
 extern void *heap_replace_max(struct ptr_heap *heap, void *p);
 
-#endif /* _LINUX_PRIO_HEAP_H */
+#endif /* _LTTNG_PRIO_HEAP_H */