1
0

partition.h 7.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260
  1. /*
  2. * lub_partition.c
  3. */
  4. /**
  5. \ingroup lub
  6. \defgroup lub_heap heap
  7. @{
  8. \brief A thread safe dynamic memory alloction system for use in a multitasking
  9. operating system.
  10. This is a high level client of the lub_heap component and provides the following
  11. additional features:
  12. \section auto_resources Automatically obtains its resources
  13. The client doesn't need to provide memory storage for this partition. It
  14. will automatically obtain this from the system pool (malloc/free etc)
  15. \section performance Multi-threading performance
  16. If cache details are provided then a small high performance heap,
  17. just big enough to hold the cache, is created on a per thread
  18. basis. This is referenced using thread specific storage within the
  19. owning thread and if it is unable to satisfy the request then a
  20. slower mutex locked global heap is created and used instead.
  21. \section auto_extension Automatically extends itself
  22. - The (slower) global heap will automatically extend itself as needed.
  23. \author Graeme McKerrell
  24. \date Created On : Wed Jun 27 14:00:00 2007
  25. \version UNTESTED
  26. */
  27. #ifndef _lub_partition_h
  28. #define _lub_partition_h
  29. #include <stddef.h>
  30. #include "lub/types.h"
  31. #include "lub/c_decl.h"
  32. #include "lub/heap.h"
  33. _BEGIN_C_DECL
  34. /**
  35. * This type is used to reference an instance of a heap.
  36. */
  37. typedef struct _lub_partition lub_partition_t;
  38. /**
  39. * This type defines a fundamental allocation function which
  40. * can be used to extend the partition as needed.
  41. */
  42. typedef void *lub_partition_sysalloc_fn(size_t required);
  43. /**
  44. * This type is used to specify any local requirements
  45. */
  46. typedef struct _lub_partition_spec lub_partition_spec_t;
  47. struct _lub_partition_spec
  48. {
  49. /**
  50. * Indicates whether or not to use a thread specific heap will be created
  51. * for each client of the partition.
  52. */
  53. bool_t use_local_heap;
  54. /**
  55. * The maximum block size for the local heap.
  56. */
  57. lub_heap_align_t max_local_block_size;
  58. /**
  59. * The number of maximum sized blocks to make available.
  60. *
  61. * If this is non zero then a local heap containing a cache with
  62. * (num_max_block * max_block_size) size buckets will be created
  63. *
  64. * If this is zero then a local heap of size max_block_size
  65. * will be created (without a cache)
  66. */
  67. size_t num_local_max_blocks;
  68. /**
  69. * When the partition grows each new segment will be at least this many bytes in size
  70. */
  71. size_t min_segment_size;
  72. /**
  73. * The limit in total bytes which can be allocated from the malloc hook
  74. * for the growth of this partition
  75. */
  76. size_t memory_limit;
  77. /**
  78. * If non-NULL then this pointer references the fundamental memory allocation
  79. * function which should be used to extend the partition.
  80. * If NULL then the standard 'malloc' function will be used.
  81. */
  82. lub_partition_sysalloc_fn *sysalloc;
  83. };
  84. /**
  85. * This operation creates a partition
  86. *
  87. * \pre
  88. * - The system pool needs to be accessible
  89. *
  90. * \return
  91. * - a reference to a partition object which can be used to allocate
  92. * memory
  93. *
  94. * \post
  95. * - memory allocations can be invoked on the returned intance.
  96. */
  97. lub_partition_t *
  98. lub_partition_create(
  99. /**
  100. * This is used to specify the details to be used for
  101. * the partition.
  102. */
  103. const lub_partition_spec_t *spec
  104. );
  105. /**
  106. * This operation starts the process of killing a partition.
  107. *
  108. * \pre
  109. * - The partition needs to have been created.
  110. *
  111. * \return
  112. * - none
  113. *
  114. * \post
  115. * - The partition will no longer hand out memory.
  116. * - When the final outstanding piece of memory is handed back
  117. * the partition will destroy itself.
  118. * - Upon final destruction any resources obtained from the
  119. * system pool will be returned.
  120. */
  121. void
  122. lub_partition_kill(
  123. /**
  124. * The heap instance on which to operate
  125. */
  126. lub_partition_t *instance
  127. );
  128. /**
  129. * This operation changes the size of the object referenced by a passed in
  130. * pointer to "size". The contents will be unchanged up to the minimum of the old
  131. * and new sizes. If the new size is larger, the new space is uninitialised.
  132. *
  133. * \pre
  134. * - The partition needs to have been created.
  135. * - If "*ptr" contains a non-NULL value then this MUST have
  136. * been allocated using this operation, from the same heap instance.
  137. *
  138. * \return
  139. * - the status of the operation.
  140. *
  141. * \post
  142. * - The client takes responsiblity for releasing any allocated memory when they
  143. * are finished with it.
  144. * - If *ptr contains a non-NULL value, then after a succesfull call, the
  145. * initial memory referenced by it may have been released for reuse,
  146. * and the pointer modified to reference some new memory.
  147. * - *ptr may contain NULL in which case no memory will be released back to the
  148. * heap for reuse, and the pointer is filled out with the allocated memory.
  149. * - (size == 0) No new memory will be allocated, *ptr will be set to NULL,
  150. * and any original memory referenced by it will have been released.
  151. */
  152. lub_heap_status_t
  153. lub_partition_realloc(
  154. /**
  155. * The partition instance on which to operate
  156. */
  157. lub_partition_t *instance,
  158. /**
  159. * Reference to a pointer containing previously allocated memory
  160. * or NULL.
  161. */
  162. char **ptr,
  163. /**
  164. * The number of bytes required for the object
  165. */
  166. size_t size,
  167. /**
  168. * The alignment required for a new allocations.
  169. */
  170. lub_heap_align_t alignment
  171. );
  172. /**
  173. * This operation checks the integrety of the memory in the specified
  174. * partition.
  175. * Corruption will be spotted the first time a check is performed AFTER
  176. * it has occured.
  177. * \pre
  178. * - the specified partition will have been created
  179. *
  180. * \return
  181. * - BOOL_TRUE if the partition is OK
  182. * - BOOL_FALSE if the partition is corrupted.
  183. *
  184. * \post
  185. * - none
  186. */
  187. extern bool_t
  188. lub_partition_check_memory(lub_partition_t *instance);
  189. /**
  190. * This operation dumps the salient details of the specified partition to stdout
  191. */
  192. void
  193. lub_partition_show(
  194. /**
  195. * The instance on which to operate
  196. */
  197. lub_partition_t *instance,
  198. /**
  199. * Whether to be verbose or not
  200. */
  201. bool_t verbose
  202. );
  203. /**
  204. * This function is invoked whenever a call to lub_partition_realloc()
  205. * fails.
  206. * It is provided as a debugging aid; simple set a breakpoint to
  207. * stop execution of the program and any failures will be caught in context.
  208. */
  209. void
  210. lub_partition_stop_here(
  211. /**
  212. * The failure status of the the call to realloc
  213. */
  214. lub_heap_status_t status,
  215. /**
  216. * The old value of the pointer passed in
  217. */
  218. char *old_ptr,
  219. /**
  220. * The requested number of bytes
  221. */
  222. size_t new_size
  223. );
  224. /**
  225. * This causes leak detection to be disabled for this partition
  226. */
  227. void
  228. lub_partition_disable_leak_detection(
  229. /**
  230. * The instance on which to operate
  231. */
  232. lub_partition_t *instance
  233. );
  234. /**
  235. * This causes leak detection to be enabled for this partition
  236. */
  237. void
  238. lub_partition_enable_leak_detection(
  239. /**
  240. * The instance on which to operate
  241. */
  242. lub_partition_t *instance
  243. );
  244. _END_C_DECL
  245. #endif /* _lub_partition_h */
  246. /** @} */