1
0

dblockpool.h 4.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140
  1. /**
  2. \ingroup lub
  3. \defgroup lub_dblockpool dblockpool
  4. @{
  5. \brief This interface provides a dynamic facility to manage the allocation and
  6. deallocation of fixed sized blocks of memory.
  7. It dynamically allocates chunks of memory each of which is used as a "blockpool".
  8. This dynamic memory is taken from the standard heap via "malloc()".
  9. This type of memory manager is very fast and doesn't suffer from
  10. any memory fragmentation problems.
  11. This allocator can reuse blocks in the order in which they are freed,
  12. this is significant for some applications where you don't want to
  13. re-use a particular freed block too soon. e.g. hardware timing
  14. limits on re-use.
  15. \author Graeme McKerrell
  16. \date Created On : Fri Feb 24 14:50:18 2005
  17. \version TESTED
  18. */
  19. /*---------------------------------------------------------------
  20. * HISTORY
  21. * 24-Feb-2006 Graeme McKerrell
  22. * Initial version
  23. *---------------------------------------------------------------
  24. * Copyright (C) 2006 Newport Networks. All Rights Reserved.
  25. *--------------------------------------------------------------- */
  26. #ifndef _lub_dblockpool_h
  27. #define _lub_dblockpool_h
  28. #include <stddef.h>
  29. #include "c_decl.h"
  30. _BEGIN_C_DECL
  31. /****************************************************************
  32. * TYPE DEFINITIONS
  33. **************************************************************** */
  34. /**
  35. * This type represents a "dblockpool" instance.
  36. */
  37. typedef struct _lub_dblockpool lub_dblockpool_t;
  38. /**
  39. * CLIENTS MUST NOT USE THESE FIELDS DIRECTLY
  40. */
  41. struct _lub_dblockpool {
  42. struct _lub_dblockpool_chunk *first_chunk;
  43. size_t block_size;
  44. unsigned chunk_size;
  45. unsigned max_chunks;
  46. };
  47. /****************************************************************
  48. * DBLOCKPOOL OPERATIONS
  49. **************************************************************** */
  50. /**
  51. * This operation initialises an instance of a dblockpool.
  52. *
  53. * \pre 'blocksize' must be an multiple of 'sizeof(void *)'.
  54. * (If the client declares a structure for the block this should be handled
  55. * automatically by the compiler)
  56. *
  57. * \post If the size constraint is not met an assert will fire.
  58. * \post Following initialisation the allocation of memory can be performed.
  59. */
  60. extern void lub_dblockpool_init(
  61. /**
  62. * the "dblockpool" instance to initialise.
  63. */
  64. lub_dblockpool_t * instance,
  65. /**
  66. * The size in bytes of each block.
  67. */
  68. size_t blocksize,
  69. /**
  70. * The number of blocks to be managed in a chunk.
  71. */
  72. unsigned chunksize,
  73. /**
  74. * The maximum number of chunks to be allocated.
  75. * (a value of zero means unlimited...)
  76. */
  77. unsigned max_chunks);
  78. /**
  79. * This operation finalises an instance of a dblockpool.
  80. *
  81. * \pre 'instance' must have been initialised first.
  82. *
  83. * \post All the dynamic memory allocated will be released.
  84. */
  85. extern void lub_dblockpool_fini(
  86. /**
  87. * the "dblockpool" instance to finalise.
  88. */
  89. lub_dblockpool_t * instance);
  90. /**
  91. * This operation allocates a "block" of memory from a "dblockpool"
  92. *
  93. *
  94. * \pre
  95. * The dblockpool must have been initialised.
  96. *
  97. * \return
  98. * A pointer to a "block" of memory, or NULL if there is none left for
  99. * allocation.
  100. *
  101. * \post
  102. * The behaviour is undefined if the "dblockpool" is uninitialised.
  103. */
  104. extern void *lub_dblockpool_alloc(
  105. /**
  106. * the "dblockpool" instance to operate on
  107. */
  108. lub_dblockpool_t * instance);
  109. /**
  110. * This operation de-allocates a "block" of memory back into a "blockpool"
  111. *
  112. * \pre
  113. * The specified block must have been previously allocated using
  114. * lub_blockpool_alloc()
  115. *
  116. * \post
  117. * The de-allocated block become available for subsequent
  118. * lub_blockpool_alloc() requests.
  119. */
  120. extern void lub_dblockpool_free(
  121. /**
  122. * the "blockpool" instance to invoke this operation upon
  123. */
  124. lub_dblockpool_t * instance,
  125. /**
  126. * the "block" to release back to the pool
  127. */
  128. void *block);
  129. _END_C_DECL
  130. #endif /* _lub_dblockpool_h */
  131. /** @} lub_dblockpool */