X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=bertos%2Fstruct%2Fpool.h;h=a44b14f3518b04d573290b573caaddb94a046209;hb=4bef9e1478a89338bece87b04c3872e76b64068e;hp=01c18d38a15a28bcdb8706d60e1d1d0c9acbe131;hpb=e5174304054e26cd8f3cd1f9980871c20c07fc46;p=bertos.git

diff --git a/bertos/struct/pool.h b/bertos/struct/pool.h
index 01c18d38..a44b14f3 100644
--- a/bertos/struct/pool.h
+++ b/bertos/struct/pool.h
@@ -31,12 +31,11 @@
  *
  * \brief Pool macros.
  *
- * \version $Id: pool.h 1294 2008-05-20 13:43:57Z asterix $
  * \author Giovanni Bajo <rasky@develer.com>
  */
 
-#ifndef MWARE_POOL_H
-#define MWARE_POOL_H
+#ifndef STRUCT_POOL_H
+#define STRUCT_POOL_H
 
 #include <cfg/macros.h>
 #include <struct/list.h>
@@ -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)
 
-#endif /* MWARE_POOL_H */
+/**
+ * \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 */