Add binary heap implementation and test

threadless/heap.h

@@ -0,0 +1,112 @@
+/* threadless.io
+ * Copyright (c) 2016 Justin R. Cutler
+ * Licensed under the MIT License. See LICENSE file in the project root for
+ * full license information.
+ */
+/** @file
+ * heap interface definition
+ * @author Justin R. Cutler <justin.r.cutler@gmail.com>
+ */
+#ifndef THREADLESS_HEAP_H
+#define THREADLESS_HEAP_H
+
+/* size_t, NULL */
+#include <stddef.h>
+
+/* allocation_t, allocator_t, allocation_init */
+#include <threadless/allocation.h>
+
+/** Heap descriptor type */
+typedef struct heap heap_t;
+
+/** Heap node type */
+typedef struct {
+    /** Back-pointer to containing heap */
+    heap_t *heap;
+    /** Current index within @p heap */
+    size_t index;
+} heap_node_t;
+
+/** Heap node comparison function type
+ * @param[in] a first node
+ * @param[in] b second node
+ * @retval >0 @p a is "better" than @p b
+ * @retval 0  @p a is equivalent to @p b
+ * @retval <0 @p a is "worse" than @p b
+ */
+typedef int (heap_compare_function_t)(const heap_node_t *a,
+    const heap_node_t *b);
+
+/** Heap descriptor structure */
+struct heap {
+    /** Heap node pointer storage */
+    allocation_t allocation;
+    /** Number of nodes in heap */
+    size_t count;
+    /** Heap node comparison function */
+    heap_compare_function_t *compare;
+};
+
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
+/** Initialize a heap descriptor
+ * @param[out] heap      heap to initialize
+ * @param      allocator allocator instance
+ * @param      compare   comparison function
+ * @post @p heap represents an empty heap with given @p compare function
+ */
+static inline void heap_init(heap_t *heap, allocator_t *allocator,
+    heap_compare_function_t *compare)
+{
+    allocation_init(&heap->allocation, allocator);
+    heap->count = 0;
+    heap->compare = compare;
+}
+
+/** Peek at the "best" node in @p heap
+ * @param[in] heap heap
+ * @retval NULL     @p heap is empty
+ * @retval non-NULL pointer to "best" node in @p heap
+ */
+static inline heap_node_t *heap_peek(const heap_t *heap)
+{
+    heap_node_t **storage = heap->count ? heap->allocation.memory : NULL;
+    return storage ? *storage : NULL;
+}
+
+/** Push a @p node into @p heap
+ * @param[in,out] heap heap
+ * @param[in,out] node node
+ * @retval 0  success
+ * @retval -1 error
+ */
+int heap_push(heap_t *heap, heap_node_t *node);
+
+/** Remove an arbitrary @p node from its heap
+ * @param[in,out] node node
+ * @pre @p node must be in a heap
+ * @post @p node is no longer in a heap
+ */
+void heap_remove(heap_node_t *node);
+
+/** Remove and return the "best" node in @p heap
+ * @param[in,out] heap heap
+ * @retval NULL     @p heap was empty
+ * @retval non-NULL pointer to removed "best" node from @p heap
+ */
+heap_node_t *heap_pop(heap_t *heap);
+
+/** Finalize a heap
+ * @param[in,out] heap heap
+ * @post All nodes have been removed from @p heap and all backing memory has
+ *       been released
+ */
+void heap_fini(heap_t *heap);
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+#endif /* THREADLESS_HEAP_H */