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

[SVN commits to the Asterisk project]

Author: russell
Date: Sun Feb 15 21:48:32 2009
New Revision: 176018

URL: http://svn.digium.com/svn-view/asterisk?view=rev&rev=176018
Log:
Add a lock for convenience for potential future usage

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=176018&r1=176017&r2=176018
==============================================================================
--- team/russell/heap/include/asterisk/heap.h (original)
+++ team/russell/heap/include/asterisk/heap.h Sun Feb 15 21:48:32 2009
@@ -31,7 +31,9 @@
  * \note Thread-safety is left to the user of the API.  The heap API provides
  *       no locking of its own.  If the heap will be accessed by multiple threads,
  *       then a lock must be used to ensure that only a single operation is
- *       done on the heap at a time.
+ *       done on the heap at a time.  For the sake of convenience, a lock is
+ *       provided for the user of the API to use if another lock is not already
+ *       available to protect the heap.
  */
 struct ast_heap;
 
@@ -125,6 +127,10 @@
  *
  * \return an element at the specified index on the heap.  This element will _not_
  *         be removed before being returned.
+ *
+ * \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.
  */
 void *ast_heap_peek(struct ast_heap *h, unsigned int index);
 
@@ -136,6 +142,28 @@
  * \return the number of elements currently in the heap
  */
 size_t ast_heap_size(struct ast_heap *h);
+
+/*!
+ * \brief Lock a heap
+ *
+ * \arg h the heap
+ *
+ * A lock is provided for convenience.  It can be assumed that none of the
+ * ast_heap API calls are thread safe.  This lock does not have to be used
+ * if another one is already available to protect the heap.
+ *
+ * \return see the documentation for pthread_mutex_lock()
+ */
+int ast_heap_lock(struct ast_heap *h);
+
+/*!
+ * \brief Unlock a heap
+ *
+ * \arg h the heap
+ *
+ * \return see the documentation for pthread_mutex_unlock()
+ */
+int ast_heap_unlock(struct ast_heap *h);
 
 /*!
  * \brief Verify that a heap has been properly constructed

Modified: team/russell/heap/main/heap.c
URL: http://svn.digium.com/svn-view/asterisk/team/russell/heap/main/heap.c?view=diff&rev=176018&r1=176017&r2=176018
==============================================================================
--- team/russell/heap/main/heap.c (original)
+++ team/russell/heap/main/heap.c Sun Feb 15 21:48:32 2009
@@ -32,6 +32,7 @@
 #include "asterisk/cli.h"
 
 struct ast_heap {
+	ast_mutex_t lock;
 	ast_heap_cmp_fn cmp_fn;
 	ssize_t index_offset;
 	size_t cur_len;
@@ -133,6 +134,8 @@
 		return NULL;
 	}
 
+	ast_mutex_init(&h->lock);
+
 	return h;
 }
 
@@ -140,6 +143,8 @@
 {
 	ast_free(h->heap);
 	h->heap = NULL;
+
+	ast_mutex_destroy(&h->lock);
 
 	ast_free(h);
 
@@ -262,3 +267,13 @@
 	return h->cur_len;
 }
 
+int ast_heap_lock(struct ast_heap *h)
+{
+	return ast_mutex_lock(&h->lock);
+}
+
+int ast_heap_unlock(struct ast_heap *h)
+{
+	return ast_mutex_unlock(&h->lock);
+}
+