1
0

blockpool.h 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237
  1. /**
  2. \ingroup lub
  3. \defgroup lub_blockpool blockpool
  4. @{
  5. \brief This interface provides a facility to manage the allocation and
  6. deallocation of fixed sized blocks of memory.
  7. This type of memory manager is very fast and doesn't suffer from
  8. any memory fragmentation problems.
  9. This allocator uses block in the order in which they are freed,
  10. this is significant for some applications where you don't want to
  11. re-use a particular freed block too soon. e.g. hardware timing
  12. limits on re-use.
  13. The client is responsible for providing the memory to be managed.
  14. \author Graeme McKerrell
  15. \date Created On : Fri Jan 23 12:50:18 2004
  16. \version TESTED
  17. */
  18. /*---------------------------------------------------------------
  19. * HISTORY
  20. * 7-Dec-2004 Graeme McKerrell
  21. * Updated to use the "lub" prefix
  22. * 6-Feb-2004 Graeme McKerrell
  23. * removed init_fn type definition and parameter, the client had
  24. * more flexiblity in defining their own initialisation operation with
  25. * arguments rather than use a "one-size-fits-all" approach.
  26. * Modified blockpool structure to support FIFO block allocation.
  27. * 23-Jan-2004 Graeme McKerrell
  28. * Initial version
  29. *---------------------------------------------------------------
  30. * Copyright (C) 2004 3Com Corporation. All Rights Reserved.
  31. *--------------------------------------------------------------- */
  32. #ifndef _lub_blockpool_h
  33. #define _lub_blockpool_h
  34. #include <stddef.h>
  35. /****************************************************************
  36. * TYPE DEFINITIONS
  37. **************************************************************** */
  38. typedef struct _lub_blockpool_block lub_blockpool_block_t;
  39. /**
  40. * This type represents a "blockpool" instance.
  41. */
  42. typedef struct _lub_blockpool lub_blockpool_t;
  43. struct _lub_blockpool
  44. {
  45. /* CLIENTS MUSTN'T TOUCH THESE DETAILS */
  46. lub_blockpool_block_t *m_head;
  47. lub_blockpool_block_t *m_tail;
  48. size_t m_block_size;
  49. size_t m_num_blocks;
  50. unsigned m_alloc_blocks;
  51. unsigned m_alloc_total_blocks;
  52. unsigned m_alloc_hightide_blocks;
  53. unsigned m_alloc_failures;
  54. };
  55. /**
  56. * This type defines the statistics available for each blockpool.
  57. */
  58. typedef struct _lub_blockpool_stats lub_blockpool_stats_t;
  59. struct _lub_blockpool_stats
  60. {
  61. /*----------------------------------------------------- */
  62. /**
  63. * NUmber of bytes in each block.
  64. */
  65. size_t block_size;
  66. /**
  67. * Total number of blocks in this pool.
  68. */
  69. size_t num_blocks;
  70. /*----------------------------------------------------- */
  71. /**
  72. * Number of dynamically allocated blocks currently
  73. * held by clients of a blockpool.
  74. */
  75. size_t alloc_blocks;
  76. /**
  77. * Number of dynamically allocated bytes currently
  78. * held by clients of a blockpool.
  79. */
  80. size_t alloc_bytes;
  81. /**
  82. * Number of free blocks.
  83. */
  84. size_t free_blocks;
  85. /**
  86. * Number of bytes available in a blockpool.
  87. */
  88. size_t free_bytes;
  89. /*----------------------------------------------------- */
  90. /**
  91. * Cumulative number of dynamically allocated blocks
  92. * given to clients of a blockpool.
  93. */
  94. size_t alloc_total_blocks;
  95. /**
  96. * Cumulative number of dynamically allocated bytes
  97. * given to clients of a blockpool.
  98. */
  99. size_t alloc_total_bytes;
  100. /*----------------------------------------------------- */
  101. /**
  102. * Number of dynamically allocated blocks
  103. * given to clients when the memory usage was at it's highest.
  104. */
  105. size_t alloc_hightide_blocks;
  106. /**
  107. * Number of dynamically allocated bytes
  108. * given to clients of a blockpool when the memory usage was at it's
  109. * highest
  110. */
  111. size_t alloc_hightide_bytes;
  112. /**
  113. * Number of free blocks when the memory usage was at it's
  114. * highest
  115. */
  116. size_t free_hightide_blocks;
  117. /**
  118. * Number of free bytes when the memory usage was at it's highest.
  119. */
  120. size_t free_hightide_bytes;
  121. /*----------------------------------------------------- */
  122. /**
  123. * Number of time an allocation has failed from this block
  124. */
  125. size_t alloc_failures;
  126. /*----------------------------------------------------- */
  127. };
  128. /****************************************************************
  129. * BLOCKPOOL OPERATIONS
  130. **************************************************************** */
  131. /**
  132. * This operation initialises an instance of a blockpool.
  133. *
  134. *
  135. * \pre 'blocksize' must be an multiple of 'sizeof(void *)'.
  136. * (If the client declares a structure for the block this should be handled
  137. * automatically by the compiler)
  138. *
  139. * \post If the size constraint is not met an assert will fire.
  140. * \post Following initialisation the allocation of memory can be performed.
  141. */
  142. extern void
  143. lub_blockpool_init(
  144. /**
  145. * the "blockpool" instance to initialise.
  146. */
  147. lub_blockpool_t *blockpool,
  148. /**
  149. * the memory to be managed.
  150. */
  151. void *memory,
  152. /**
  153. * The size in bytes of each block.
  154. */
  155. size_t blocksize,
  156. /** The number of blocks to be managed. NB the client is
  157. * responsible for ensuring that (blocksize x blockcount)
  158. * bytes of memory are available for use.
  159. */
  160. unsigned blockcount
  161. );
  162. /**
  163. * This operation allocates a "block" of memory from a "blockpool"
  164. *
  165. *
  166. * \pre
  167. * The blockpool must have been initialised.
  168. *
  169. * \return
  170. * A pointer to a "block" of memory, or NULL if there is none left for
  171. * allocation.
  172. *
  173. * \post
  174. * The behaviour is undefined if the "blockpool" is uninitialised.
  175. */
  176. extern void *
  177. lub_blockpool_alloc(
  178. /**
  179. * the "blockpool" instance to invoke this operation upon
  180. */
  181. lub_blockpool_t *blockpool
  182. );
  183. /**
  184. * This operation de-allocates a "block" of memory back into a "blockpool"
  185. *
  186. * \pre
  187. * The specified block must have been previously allocated using
  188. * lub_blockpool_alloc()
  189. *
  190. * \post
  191. * The de-allocated block become available for subsequent
  192. * lub_blockpool_alloc() requests.
  193. */
  194. extern void
  195. lub_blockpool_free(
  196. /**
  197. * the "blockpool" instance to invoke this operation upon
  198. */
  199. lub_blockpool_t *blockpool,
  200. /**
  201. * the "block" to release back to the pool
  202. */
  203. void *block
  204. );
  205. /**
  206. * This operation fills out a statistics structure with the details for the
  207. * specified blockpool.
  208. *
  209. * \pre
  210. * - none
  211. *
  212. * \post
  213. * - the results filled out are a snapshot of the statistics as the time
  214. * of the call.
  215. */
  216. void
  217. lub_blockpool__get_stats(
  218. /**
  219. * The instance on which to operate
  220. */
  221. lub_blockpool_t *instance,
  222. /**
  223. * A client provided structure to fill out with the blockpool details
  224. */
  225. lub_blockpool_stats_t *stats
  226. );
  227. #endif /* _lub_blockpool_h */
  228. /** @} blockpool */