X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=bertos%2Fstruct%2Fpool.h;h=a44b14f3518b04d573290b573caaddb94a046209;hb=328675078ae8cd81cfa3524ad9cd082621a18566;hp=b2e14148ab2cea61f95d59c26afeced5b47b8677;hpb=23b7f48a17d33a426782161f721cff4fc6611ddf;p=bertos.git

diff --git a/bertos/struct/pool.h b/bertos/struct/pool.h
index b2e14148..a44b14f3 100644
--- a/bertos/struct/pool.h
+++ b/bertos/struct/pool.h
@@ -31,7 +31,6 @@
  *
  * \brief Pool macros.
  *
- * \version $Id: pool.h 1294 2008-05-20 13:43:57Z asterix $
  * \author Giovanni Bajo <rasky@develer.com>
  */
 
@@ -49,7 +48,7 @@
 	storage name; \
 	INLINE void name##_init(void (*init_func)(type*)) \
 	{ \
-		int i; \
+		size_t i; \
 		LIST_INIT(&name); \
 		for (i=0;i<countof(name##_items);++i) \
 		{ \
@@ -60,6 +59,16 @@
 	INLINE void name##_init(void (*init_func)(type*)) \
 	/**/
 
+/**
+ * \brief Helper macro to declare a Pool data type.
+ *
+ * Data type inserted into the pool must be a \code Node * \endcode
+ * type.
+ *
+ * \param name Variable name of the pool.
+ * \param type Data type held by the pool.
+ * \param num Number of elements in pool.
+ */
 #define DECLARE_POOL(name, type, num) \
 	DECLARE_POOL_WITH_STORAGE(name, type, num, List)
 
@@ -67,8 +76,38 @@
 	DECLARE_POOL_WITH_STORAGE(name, type, num, static List)
 
 #define pool_init(name, init_func)     (*(name##_init))(init_func)
-#define pool_alloc(name)               REMHEAD(name)
+
+/**
+ * \brief Allocate an element from the pool.
+ *
+ * The returned element is of type \code Node * \endcode, it's safe to
+ * cast it to the type contained in the pool.
+ *
+ * \note If the element was recycled with pool_free(), it will not be reset,
+ * so don't assume that the element has specific values.
+ *
+ * \param name Pointer to pool to alloc from.
+ * \return Element of the type present in the pool.
+ */
+#define pool_alloc(name)               list_remHead(name)
+
+/**
+ * \brief Recycle an element into the pool
+ *
+ * \note Element fields are not reset to its original values, keep that in
+ * mind when you alloc nodes.
+ *
+ * \param name Pointer to pool where the node should be recycled.
+ * \param elem Element to be recycled.
+ */
 #define pool_free(name, elem)          ADDHEAD(name, (Node*)elem)
-#define pool_empty(name)               ISLISTEMPTY(name)
+
+/**
+ * \brief Test if the pool is empty
+ *
+ * \param name Pointer to pool.
+ * \return True if the pool is empty, false otherwise.
+ */
+#define pool_empty(name)               LIST_EMPTY(name)
 
 #endif /* STRUCT_POOL_H */