From: Russell Bryant <russell@russellbryant.com>
Date: Wed, 18 Feb 2009 06:14:47 +0000 (+0000)
Subject: Add example code for a heap traversal.
X-Git-Tag: 1.6.2.0-beta1~185
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=b5410fad009ab1850742c847431d73e758307c00;p=thirdparty%2Fasterisk.git

Add example code for a heap traversal.


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@176904 65c4cc65-6c06-0410-ace0-fbb531ad65f3
---

diff --git a/include/asterisk/heap.h b/include/asterisk/heap.h
index 6f6e52b2dc..8148fa5ba2 100644
--- a/include/asterisk/heap.h
+++ b/include/asterisk/heap.h
@@ -155,6 +155,28 @@ void *ast_heap_remove(struct ast_heap *h, void *elm);
  * \note If this function is being used in combination with ast_heap_size() for
  *       purposes of traversing the heap, the heap must be locked for the entire
  *       duration of the traversal.
+ *
+ * Example code for a traversal:
+ * \code
+ *
+ * struct ast_heap *h;
+ *
+ * ...
+ *
+ * size_t size, i;
+ * void *cur_obj;
+ *
+ * ast_heap_rdlock(h);
+ *
+ * size = ast_heap_size(h);
+ *
+ * for (i = 1; i <= size && (cur_obj = ast_heap_peek(h, i)); i++) {
+ *     ... Do stuff with cur_obj ...
+ * }
+ *
+ * ast_heap_unlock(h);
+ *
+ * \endcode
  */
 void *ast_heap_peek(struct ast_heap *h, unsigned int index);