[asterisk-commits] russell: branch russell/heap r175775 - in /team/russell/heap: include/asteris...

[SVN commits to the Asterisk project]

Author: russell
Date: Sat Feb 14 22:13:03 2009
New Revision: 175775

URL: http://svn.digium.com/svn-view/asterisk?view=rev&rev=175775
Log:
API docs

Modified:
    team/russell/heap/include/asterisk/heap.h
    team/russell/heap/main/heap.c

Modified: team/russell/heap/include/asterisk/heap.h
URL: http://svn.digium.com/svn-view/asterisk/team/russell/heap/include/asterisk/heap.h?view=diff&rev=175775&r1=175774&r2=175775
==============================================================================
--- team/russell/heap/include/asterisk/heap.h (original)
+++ team/russell/heap/include/asterisk/heap.h Sat Feb 14 22:13:03 2009
@@ -18,29 +18,120 @@
 
 /*!
  * \file
+ * \brief Max Heap data structure
  * \author Russell Bryant <russell at digium.com>
  */
 
 #ifndef __AST_HEAP_H__
 #define __AST_HEAP_H__
 
+/*!
+ * \brief A max heap.
+ */
 struct ast_heap;
 
+/*!
+ * \brief Function type for comparing nodes in a heap
+ *
+ * \param elm1 the first element
+ * \param elm2 the second element
+ *
+ * \retval -1 if elm1 < elm2
+ * \retval 0 if elm1 == elm2
+ * \retval 1 if elm1 > elm2
+ *
+ * \note This implementation is of a max heap.  However, if a min heap is
+ *       desired, simply swap the return values of this function.
+ */
 typedef int (*ast_heap_cmp_fn)(void *elm1, void *elm2);
 
-struct ast_heap *ast_heap_create(unsigned int init_depth, ast_heap_cmp_fn cmp_fn,
+/*!
+ * \brief Create a max heap
+ *
+ * \param init_height The initial height of the heap to allocate space for.
+ *        To start out, there will be room for (2 ^ init_height) - 1 entries.
+ *        However, the heap will grow as needed.
+ * \param cmp_fn The function that should be used to compare elements in the heap.
+ * \param index_offset This parameter is optional, but must be provided to be able
+ *        to use ast_heap_remove().  This is the number of bytes into the element
+ *        where an "unsigned int" has been made available for the heap's internal
+ *        use.  The heap will use this field to keep track of the element's current
+ *        position in the heap.  The offsetof() macro is useful for providing a
+ *        proper value for this argument.
+ *
+ * \return An instance of a max heap
+ */
+struct ast_heap *ast_heap_create(unsigned int init_height, ast_heap_cmp_fn cmp_fn,
 		size_t index_offset);
 
+/*!
+ * \brief Destroy a max heap
+ *
+ * \param h the heap to destroy
+ *
+ * \return NULL for convenience
+ */
 struct ast_heap *ast_heap_destroy(struct ast_heap *h);
 
+/*!
+ * \brief Push an element on to a heap
+ *
+ * \param h the heap being added to
+ * \param elm the element being put on the heap
+ *
+ * \retval 0 success
+ * \retval non-zero failure
+ */
 int ast_heap_push(struct ast_heap *h, void *elm);
 
+/*!
+ * \brief Pop the max element off of the heap
+ *
+ * \param h the heap
+ *
+ * \return this will return the element on the top of the heap, which has the
+ *         largest value according to the element comparison function that was
+ *         provided when the heap was created.  The element will be removed before
+ *         being returned.
+ */
 void *ast_heap_pop(struct ast_heap *h);
 
+/*!
+ * \brief Remove a specific element from a heap
+ *
+ * \param h the heap to remove from
+ * \param elm the element to remove
+ *
+ * \return elm, if the removal was successful, or NULL if it failed
+ *
+ * \note the index_offset parameter to ast_heap_create() is required to be able
+ *       to use this function.
+ */
 void *ast_heap_remove(struct ast_heap *h, void *elm);
 
+/*!
+ * \brief Peek at the top element on a heap
+ *
+ * \param h the heap
+ *
+ * \return this will return the element on the top of the heap, which has the
+ *         largest value according to the element comparison function that was
+ *         provided when the heap was created.  The element will _not_ be removed
+ *         before being returned by this function.
+ */
 void *ast_heap_peek(struct ast_heap *h);
 
+/*!
+ * \brief Verify that a heap has been properly constructed
+ *
+ * \param h a heap
+ *
+ * \retval 0 success
+ * \retval non-zero failure
+ *
+ * \note This function is mostly for debugging purposes.  It traverses an existing
+ *       heap and verifies that every node is >= its children.
+ */
 int ast_heap_verify(struct ast_heap *h);
 
 #endif /* __AST_HEAP_H__ */

Modified: team/russell/heap/main/heap.c
URL: http://svn.digium.com/svn-view/asterisk/team/russell/heap/main/heap.c?view=diff&rev=175775&r1=175774&r2=175775
==============================================================================
--- team/russell/heap/main/heap.c (original)
+++ team/russell/heap/main/heap.c Sat Feb 14 22:13:03 2009
@@ -18,7 +18,7 @@
 
 /*! \file
  *
- * \brief Heap data structure
+ * \brief Max Heap data structure
  *
  * \author Russell Bryant <russell at digium.com>
  */
@@ -62,6 +62,7 @@
 static inline size_t get_index(struct ast_heap *h, void *elm)
 {
 	size_t *index = elm + h->index_offset;
+
 	return *index;
 }
 
@@ -97,7 +98,7 @@
 	return 0;
 }
 
-struct ast_heap *ast_heap_create(unsigned int init_depth, ast_heap_cmp_fn cmp_fn,
+struct ast_heap *ast_heap_create(unsigned int init_height, ast_heap_cmp_fn cmp_fn,
 		size_t index_offset)
 {
 	struct ast_heap *h;
@@ -107,8 +108,8 @@
 		return NULL;
 	}
 
-	if (!init_depth) {
-		init_depth = 8;
+	if (!init_height) {
+		init_height = 8;
 	}
 
 	if (!(h = ast_calloc(1, sizeof(*h)))) {
@@ -117,7 +118,7 @@
 
 	h->cmp_fn = cmp_fn;
 	h->index_offset = index_offset;
-	h->avail_len = (1 << init_depth) - 1;
+	h->avail_len = (1 << init_height) - 1;
 
 	if (!(h->heap = ast_calloc(1, h->avail_len * sizeof(void *)))) {
 		ast_free(h);