1
0

partition.h 7.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241
  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. * Indicates whether or not to use a thread specific heap will be created
  50. * for each client of the partition.
  51. */
  52. bool_t use_local_heap;
  53. /**
  54. * The maximum block size for the local heap.
  55. */
  56. lub_heap_align_t max_local_block_size;
  57. /**
  58. * The number of maximum sized blocks to make available.
  59. *
  60. * If this is non zero then a local heap containing a cache with
  61. * (num_max_block * max_block_size) size buckets will be created
  62. *
  63. * If this is zero then a local heap of size max_block_size
  64. * will be created (without a cache)
  65. */
  66. size_t num_local_max_blocks;
  67. /**
  68. * When the partition grows each new segment will be at least this many bytes in size
  69. */
  70. size_t min_segment_size;
  71. /**
  72. * The limit in total bytes which can be allocated from the malloc hook
  73. * for the growth of this partition
  74. */
  75. size_t memory_limit;
  76. /**
  77. * If non-NULL then this pointer references the fundamental memory allocation
  78. * function which should be used to extend the partition.
  79. * If NULL then the standard 'malloc' function will be used.
  80. */
  81. lub_partition_sysalloc_fn *sysalloc;
  82. };
  83. /**
  84. * This operation creates a partition
  85. *
  86. * \pre
  87. * - The system pool needs to be accessible
  88. *
  89. * \return
  90. * - a reference to a partition object which can be used to allocate
  91. * memory
  92. *
  93. * \post
  94. * - memory allocations can be invoked on the returned intance.
  95. */
  96. lub_partition_t *lub_partition_create(
  97. /**
  98. * This is used to specify the details to be used for
  99. * the partition.
  100. */
  101. const lub_partition_spec_t * spec);
  102. /**
  103. * This operation starts the process of killing a partition.
  104. *
  105. * \pre
  106. * - The partition needs to have been created.
  107. *
  108. * \return
  109. * - none
  110. *
  111. * \post
  112. * - The partition will no longer hand out memory.
  113. * - When the final outstanding piece of memory is handed back
  114. * the partition will destroy itself.
  115. * - Upon final destruction any resources obtained from the
  116. * system pool will be returned.
  117. */
  118. void lub_partition_kill(
  119. /**
  120. * The heap instance on which to operate
  121. */
  122. lub_partition_t * instance);
  123. /**
  124. * This operation changes the size of the object referenced by a passed in
  125. * pointer to "size". The contents will be unchanged up to the minimum of the old
  126. * and new sizes. If the new size is larger, the new space is uninitialised.
  127. *
  128. * \pre
  129. * - The partition needs to have been created.
  130. * - If "*ptr" contains a non-NULL value then this MUST have
  131. * been allocated using this operation, from the same heap instance.
  132. *
  133. * \return
  134. * - the status of the operation.
  135. *
  136. * \post
  137. * - The client takes responsiblity for releasing any allocated memory when they
  138. * are finished with it.
  139. * - If *ptr contains a non-NULL value, then after a succesfull call, the
  140. * initial memory referenced by it may have been released for reuse,
  141. * and the pointer modified to reference some new memory.
  142. * - *ptr may contain NULL in which case no memory will be released back to the
  143. * heap for reuse, and the pointer is filled out with the allocated memory.
  144. * - (size == 0) No new memory will be allocated, *ptr will be set to NULL,
  145. * and any original memory referenced by it will have been released.
  146. */
  147. lub_heap_status_t lub_partition_realloc(
  148. /**
  149. * The partition instance on which to operate
  150. */
  151. lub_partition_t * instance,
  152. /**
  153. * Reference to a pointer containing previously allocated memory
  154. * or NULL.
  155. */
  156. char **ptr,
  157. /**
  158. * The number of bytes required for the object
  159. */
  160. size_t size,
  161. /**
  162. * The alignment required for a new allocations.
  163. */
  164. lub_heap_align_t alignment);
  165. /**
  166. * This operation checks the integrety of the memory in the specified
  167. * partition.
  168. * Corruption will be spotted the first time a check is performed AFTER
  169. * it has occured.
  170. * \pre
  171. * - the specified partition will have been created
  172. *
  173. * \return
  174. * - BOOL_TRUE if the partition is OK
  175. * - BOOL_FALSE if the partition is corrupted.
  176. *
  177. * \post
  178. * - none
  179. */
  180. extern bool_t lub_partition_check_memory(lub_partition_t * instance);
  181. /**
  182. * This operation dumps the salient details of the specified partition to stdout
  183. */
  184. void lub_partition_show(
  185. /**
  186. * The instance on which to operate
  187. */
  188. lub_partition_t * instance,
  189. /**
  190. * Whether to be verbose or not
  191. */
  192. bool_t verbose);
  193. /**
  194. * This function is invoked whenever a call to lub_partition_realloc()
  195. * fails.
  196. * It is provided as a debugging aid; simple set a breakpoint to
  197. * stop execution of the program and any failures will be caught in context.
  198. */
  199. void lub_partition_stop_here(
  200. /**
  201. * The failure status of the the call to realloc
  202. */
  203. lub_heap_status_t status,
  204. /**
  205. * The old value of the pointer passed in
  206. */
  207. char *old_ptr,
  208. /**
  209. * The requested number of bytes
  210. */
  211. size_t new_size);
  212. /**
  213. * This causes leak detection to be disabled for this partition
  214. */
  215. void lub_partition_disable_leak_detection(
  216. /**
  217. * The instance on which to operate
  218. */
  219. lub_partition_t * instance);
  220. /**
  221. * This causes leak detection to be enabled for this partition
  222. */
  223. void lub_partition_enable_leak_detection(
  224. /**
  225. * The instance on which to operate
  226. */
  227. lub_partition_t * instance);
  228. _END_C_DECL
  229. #endif /* _lub_partition_h */
  230. /** @} */