bertos/struct/pool.h

   1 /**
   2  * \file
   3  * <!--
   4  * This file is part of BeRTOS.
   5  *
   6  * Bertos is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  19  *
  20  * As a special exception, you may use this file as part of a free software
  21  * library without restriction.  Specifically, if other files instantiate
  22  * templates or use macros or inline functions from this file, or you compile
  23  * this file and link it with other files to produce an executable, this
  24  * file does not by itself cause the resulting executable to be covered by
  25  * the GNU General Public License.  This exception does not however
  26  * invalidate any other reasons why the executable file might be covered by
  27  * the GNU General Public License.
  28  *
  29  * Copyright 2004, 2008, 2011 Develer S.r.l. (http://www.develer.com/)
  30  * -->
  31  *
  32  * \defgroup pool Pool memory allocator
  33  * \ingroup struct
  34  * \{
  35  *
  36  * \brief Pool macros.
  37  *
  38  * The pool module provides the boilerplate code to create a set of objects
  39  * of the same type.
  40  * It provides an interface similar to the heap module, with pool_alloc() and
  41  * pool_free() functions that allocate and free an element respectively.
  42  * In contrast with the heap module, you can specify exactly the number of
  43  * items that you want to be in the pool.
  44  *
  45  * Items in the pool must be a derived class of <tt>Node *</tt>, which also
  46  * means that they can be used as-is with list containers, eg. MsgPort.
  47  *
  48  * Example code:
  49  * \code
  50  * typedef struct MyType
  51  * {
  52  *     Node *n;
  53  *     uint16_t *buf;
  54  *     // other members here...
  55  * } MyType;
  56  *
  57  * DECLARE_POOL(mypool, MyType, POOL_SIZE);
  58  *
  59  * static void elem_init(MyType *e)
  60  * {
  61  *     e->buf = NULL;
  62  *     // other initializations here
  63  * }
  64  *
  65  * int main(void)
  66  * {
  67  *     pool_init(&mypool, elem_init);
  68  *
  69  *     MyType *foo = pool_alloc(&mypool);
  70  *     // do stuff with foo
  71  *     pool_free(&mypool, foo);
  72  * }
  73  * \endcode
  74  *
  75  * \author Giovanni Bajo <rasky@develer.com>
  76  * \author Luca Ottaviano <lottaviano@develer.com>
  77  */
  78
  79 #ifndef STRUCT_POOL_H
  80 #define STRUCT_POOL_H
  81
  82 #include <cfg/macros.h>
  83 #include <struct/list.h>
  84
  85 /**
  86  * \brief Extern pool declaration
  87  */
  88 #define EXTERN_POOL(name) \
  89         extern List name
  90
  91 #define DECLARE_POOL_WITH_STORAGE(name, type, num, storage) \
  92         static type name##_items[num]; \
  93         storage name; \
  94         INLINE void name##_init(void (*init_func)(type*)) \
  95         { \
  96                 size_t i; \
  97                 LIST_INIT(&name); \
  98                 for (i=0;i<countof(name##_items);++i) \
  99                 { \
 100                         if (init_func) init_func(&name##_items[i]); \
 101                         ADDTAIL(&name, (Node*)&name##_items[i]); \
 102                 } \
 103         } \
 104         INLINE void name##_init(void (*init_func)(type*)) \
 105         /**/
 106
 107 /**
 108  * \brief Helper macro to declare a Pool data type.
 109  *
 110  * Data type inserted into the pool must be a <tt>Node *</tt>
 111  * type.
 112  *
 113  * \param name Variable name of the pool.
 114  * \param type Data type held by the pool.
 115  * \param num Number of elements in pool.
 116  */
 117 #define DECLARE_POOL(name, type, num) \
 118         DECLARE_POOL_WITH_STORAGE(name, type, num, List)
 119
 120 /**
 121  * \brief Static Pool declaration
 122  *
 123  * \sa DECLARE_POOL
 124  */
 125 #define DECLARE_POOL_STATIC(name, type, num) \
 126         DECLARE_POOL_WITH_STORAGE(name, type, num, static List)
 127
 128 /**
 129  * Initialize the pool \a name, calling \a init_func on each element.
 130  *
 131  * The init function must have the following prototype:
 132  * \code
 133  * void init_func(type *)
 134  * \endcode
 135  * where \a type is the type of objects held in the pool.
 136  *
 137  * \param name Pool to initialize
 138  * \param init_func Init function to be called on each element
 139  */
 140 #define pool_init(name, init_func)     (*(name##_init))(init_func)
 141
 142 /**
 143  * \brief Allocate an element from the pool.
 144  *
 145  * The returned element is of type <tt>Node *</tt>, it's safe to
 146  * cast it to the type contained in the pool.
 147  *
 148  * \note If the element was recycled with pool_free(), it will not be reset,
 149  * so don't assume that the element has specific values.
 150  *
 151  * \param name Pointer to pool to alloc from.
 152  * \return Element of the type present in the pool.
 153  */
 154 #define pool_alloc(name)               list_remHead(name)
 155
 156 /**
 157  * \brief Recycle an element into the pool
 158  *
 159  * \note Element fields are not reset to its original values, keep that in
 160  * mind when you alloc nodes.
 161  *
 162  * \param name Pointer to pool where the node should be recycled.
 163  * \param elem Element to be recycled.
 164  */
 165 #define pool_free(name, elem)          ADDHEAD(name, (Node*)elem)
 166
 167 /**
 168  * \brief Test if the pool is empty
 169  *
 170  * \param name Pointer to pool.
 171  * \return True if the pool is empty, false otherwise.
 172  */
 173 #define pool_empty(name)               LIST_EMPTY(name)
 174
 175  /** \} */ /* defgroup pool */
 176
 177 #endif /* STRUCT_POOL_H */