1
0

blockpool.h 6.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226
  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. /* CLIENTS MUSTN'T TOUCH THESE DETAILS */
  45. lub_blockpool_block_t *m_head;
  46. lub_blockpool_block_t *m_tail;
  47. size_t m_block_size;
  48. size_t m_num_blocks;
  49. unsigned m_alloc_blocks;
  50. unsigned m_alloc_total_blocks;
  51. unsigned m_alloc_hightide_blocks;
  52. unsigned m_alloc_failures;
  53. };
  54. /**
  55. * This type defines the statistics available for each blockpool.
  56. */
  57. typedef struct _lub_blockpool_stats lub_blockpool_stats_t;
  58. struct _lub_blockpool_stats {
  59. /*----------------------------------------------------- */
  60. /**
  61. * NUmber of bytes in each block.
  62. */
  63. size_t block_size;
  64. /**
  65. * Total number of blocks in this pool.
  66. */
  67. size_t num_blocks;
  68. /*----------------------------------------------------- */
  69. /**
  70. * Number of dynamically allocated blocks currently
  71. * held by clients of a blockpool.
  72. */
  73. size_t alloc_blocks;
  74. /**
  75. * Number of dynamically allocated bytes currently
  76. * held by clients of a blockpool.
  77. */
  78. size_t alloc_bytes;
  79. /**
  80. * Number of free blocks.
  81. */
  82. size_t free_blocks;
  83. /**
  84. * Number of bytes available in a blockpool.
  85. */
  86. size_t free_bytes;
  87. /*----------------------------------------------------- */
  88. /**
  89. * Cumulative number of dynamically allocated blocks
  90. * given to clients of a blockpool.
  91. */
  92. size_t alloc_total_blocks;
  93. /**
  94. * Cumulative number of dynamically allocated bytes
  95. * given to clients of a blockpool.
  96. */
  97. size_t alloc_total_bytes;
  98. /*----------------------------------------------------- */
  99. /**
  100. * Number of dynamically allocated blocks
  101. * given to clients when the memory usage was at it's highest.
  102. */
  103. size_t alloc_hightide_blocks;
  104. /**
  105. * Number of dynamically allocated bytes
  106. * given to clients of a blockpool when the memory usage was at it's
  107. * highest
  108. */
  109. size_t alloc_hightide_bytes;
  110. /**
  111. * Number of free blocks when the memory usage was at it's
  112. * highest
  113. */
  114. size_t free_hightide_blocks;
  115. /**
  116. * Number of free bytes when the memory usage was at it's highest.
  117. */
  118. size_t free_hightide_bytes;
  119. /*----------------------------------------------------- */
  120. /**
  121. * Number of time an allocation has failed from this block
  122. */
  123. size_t alloc_failures;
  124. /*----------------------------------------------------- */
  125. };
  126. /****************************************************************
  127. * BLOCKPOOL OPERATIONS
  128. **************************************************************** */
  129. /**
  130. * This operation initialises an instance of a blockpool.
  131. *
  132. *
  133. * \pre 'blocksize' must be an multiple of 'sizeof(void *)'.
  134. * (If the client declares a structure for the block this should be handled
  135. * automatically by the compiler)
  136. *
  137. * \post If the size constraint is not met an assert will fire.
  138. * \post Following initialisation the allocation of memory can be performed.
  139. */
  140. extern void lub_blockpool_init(
  141. /**
  142. * the "blockpool" instance to initialise.
  143. */
  144. lub_blockpool_t * blockpool,
  145. /**
  146. * the memory to be managed.
  147. */
  148. void *memory,
  149. /**
  150. * The size in bytes of each block.
  151. */
  152. size_t blocksize,
  153. /** The number of blocks to be managed. NB the client is
  154. * responsible for ensuring that (blocksize x blockcount)
  155. * bytes of memory are available for use.
  156. */
  157. unsigned blockcount);
  158. /**
  159. * This operation allocates a "block" of memory from a "blockpool"
  160. *
  161. *
  162. * \pre
  163. * The blockpool must have been initialised.
  164. *
  165. * \return
  166. * A pointer to a "block" of memory, or NULL if there is none left for
  167. * allocation.
  168. *
  169. * \post
  170. * The behaviour is undefined if the "blockpool" is uninitialised.
  171. */
  172. extern void *lub_blockpool_alloc(
  173. /**
  174. * the "blockpool" instance to invoke this operation upon
  175. */
  176. lub_blockpool_t * blockpool);
  177. /**
  178. * This operation de-allocates a "block" of memory back into a "blockpool"
  179. *
  180. * \pre
  181. * The specified block must have been previously allocated using
  182. * lub_blockpool_alloc()
  183. *
  184. * \post
  185. * The de-allocated block become available for subsequent
  186. * lub_blockpool_alloc() requests.
  187. */
  188. extern void lub_blockpool_free(
  189. /**
  190. * the "blockpool" instance to invoke this operation upon
  191. */
  192. lub_blockpool_t * blockpool,
  193. /**
  194. * the "block" to release back to the pool
  195. */
  196. void *block);
  197. /**
  198. * This operation fills out a statistics structure with the details for the
  199. * specified blockpool.
  200. *
  201. * \pre
  202. * - none
  203. *
  204. * \post
  205. * - the results filled out are a snapshot of the statistics as the time
  206. * of the call.
  207. */
  208. void lub_blockpool__get_stats(
  209. /**
  210. * The instance on which to operate
  211. */
  212. lub_blockpool_t * instance,
  213. /**
  214. * A client provided structure to fill out with the blockpool details
  215. */
  216. lub_blockpool_stats_t * stats);
  217. #endif /* _lub_blockpool_h */
  218. /** @} blockpool */