X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=bertos%2Fstruct%2Fpool.h;h=9bf4535b54822d2a49353f00f9f512a167c0d86b;hb=d603ad8d35758a54f6cb08a7f8c16f6327ea86e0;hp=a44b14f3518b04d573290b573caaddb94a046209;hpb=a96606a141e20e7d2b855c485abab79fc258d198;p=bertos.git
diff --git a/bertos/struct/pool.h b/bertos/struct/pool.h
index a44b14f3..9bf4535b 100644
--- a/bertos/struct/pool.h
+++ b/bertos/struct/pool.h
@@ -26,12 +26,54 @@
* invalidate any other reasons why the executable file might be covered by
* the GNU General Public License.
*
- * Copyright 2004, 2008 Develer S.r.l. (http://www.develer.com/)
+ * Copyright 2004, 2008, 2011 Develer S.r.l. (http://www.develer.com/)
* -->
*
+ * \defgroup pool Pool memory allocator
+ * \ingroup struct
+ * \{
+ *
* \brief Pool macros.
*
+ * The pool module provides the boilerplate code to create a set of objects
+ * of the same type.
+ * It provides an interface similar to the heap module, with pool_alloc() and
+ * pool_free() functions that allocate and free an element respectively.
+ * In contrast with the heap module, you can specify exactly the number of
+ * items that you want to be in the pool.
+ *
+ * Items in the pool must be a derived class of Node *, which also
+ * means that they can be used as-is with list containers, eg. MsgPort.
+ *
+ * Example code:
+ * \code
+ * typedef struct MyType
+ * {
+ * Node *n;
+ * uint16_t *buf;
+ * // other members here...
+ * } MyType;
+ *
+ * DECLARE_POOL(mypool, MyType, POOL_SIZE);
+ *
+ * static void elem_init(MyType *e)
+ * {
+ * e->buf = NULL;
+ * // other initializations here
+ * }
+ *
+ * int main(void)
+ * {
+ * pool_init(&mypool, elem_init);
+ *
+ * MyType *foo = pool_alloc(&mypool);
+ * // do stuff with foo
+ * pool_free(&mypool, foo);
+ * }
+ * \endcode
+ *
* \author Giovanni Bajo
+ * \author Luca Ottaviano
*/
#ifndef STRUCT_POOL_H
@@ -40,6 +82,9 @@
#include
#include
+/**
+ * \brief Extern pool declaration
+ */
#define EXTERN_POOL(name) \
extern List name
@@ -62,7 +107,7 @@
/**
* \brief Helper macro to declare a Pool data type.
*
- * Data type inserted into the pool must be a \code Node * \endcode
+ * Data type inserted into the pool must be a Node *
* type.
*
* \param name Variable name of the pool.
@@ -72,15 +117,32 @@
#define DECLARE_POOL(name, type, num) \
DECLARE_POOL_WITH_STORAGE(name, type, num, List)
+/**
+ * \brief Static Pool declaration
+ *
+ * \sa DECLARE_POOL
+ */
#define DECLARE_POOL_STATIC(name, type, num) \
DECLARE_POOL_WITH_STORAGE(name, type, num, static List)
+/**
+ * Initialize the pool \a name, calling \a init_func on each element.
+ *
+ * The init function must have the following prototype:
+ * \code
+ * void init_func(type *)
+ * \endcode
+ * where \a type is the type of objects held in the pool.
+ *
+ * \param name Pool to initialize
+ * \param init_func Init function to be called on each element
+ */
#define pool_init(name, init_func) (*(name##_init))(init_func)
/**
* \brief Allocate an element from the pool.
*
- * The returned element is of type \code Node * \endcode, it's safe to
+ * The returned element is of type Node *, 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,
@@ -110,4 +172,6 @@
*/
#define pool_empty(name) LIST_EMPTY(name)
+ /** \} */ /* defgroup pool */
+
#endif /* STRUCT_POOL_H */