From: lottaviano Date: Wed, 23 Feb 2011 10:01:47 +0000 (+0000) Subject: doc: Add documentation for the pool memory allocator X-Git-Tag: 2.7.0~246 X-Git-Url: https://codewiz.org/gitweb?a=commitdiff_plain;h=da481df44a8fdd7c5501a03892c935504ff176aa;p=bertos.git doc: Add documentation for the pool memory allocator git-svn-id: https://src.develer.com/svnoss/bertos/trunk@4720 38d2e660-2303-0410-9eaa-f027e97ec537 --- 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 */