Zen API
 All Classes Files Functions Variables Typedefs Friends Macros Modules Pages
kPoolAlloc Class Reference

Description

Allocates small buffers from larger blocks and/or caches deallocated buffers for later reuse.

This memory allocator can be used to improve performance in some circumstances. It can reduce the number of individual requests to an underlying allocator by allocating multiple small memory buffers from larger blocks. It can also cache deallocated buffers for later reuse, reducing the frequency of allocation requests made to the underlying allocator.

For each memory request, a 'rank' is determined by calculating the base-2 logarithm of the requested size and then rounding up. The rank determines the true size of the buffer that will be allocated (requests are rounded up to the nearest power of two). Rank-based buffer management provides simple organization and fast reallocation; the cost is increased memory space.

Parameters are provided to control which ranks should be allocated from larger blocks, which ranks should be cached upon deallocation, memory capacities, etc. Memory can be reserved using the kPoolAlloc_Reserve and kPoolAlloc_ReserveAt functions, and/or dynamically allocated from the underlying allocator as needed.

The operations provided in this class should be used in the following order:

  • Construct a kPoolAlloc instance.
  • Perform configuration.
  • Use the kPoolAlloc_Start method to prepare the allocator for use.
  • Use the kPoolAlloc_Reserve or kPoolAlloc_ReserveAt methods to make pre-emptive allocations.
  • Use the kAlloc_Get/kAlloc_Free methods to perform allocations/deallocations.
  • Destroy the kPoolAlloc instance when no longer needed.

All outstanding memory allocations must be freed before destroying the allocator.

Public Member Functions

kSize kPoolAlloc_BlockCapacity (kPoolAlloc object)
 Returns the maximum amount of memory that can be used for block-based allocations. More...
 
kBool kPoolAlloc_BlockReuseEnabled (kPoolAlloc object)
 Reports whether blocks can be reused between ranks. More...
 
kSize kPoolAlloc_BlockSize (kPoolAlloc object)
 Returns the approximate size of large memory blocks used to satisfy small memory requests. More...
 
kSize kPoolAlloc_BufferCountAt (kPoolAlloc object, kSize rank)
 Reports the total number of memory buffers at the given rank. More...
 
kSize kPoolAlloc_CacheCapacity (kPoolAlloc object)
 Returns the maximum total amount of memory that can be used to cache buffers upon deallocation. More...
 
kStatus kPoolAlloc_Clear (kPoolAlloc object)
 Returns surplus memory to the underlying allocator. More...
 
kStatus kPoolAlloc_ClearAll (kPoolAlloc object)
 Removes any existing memory reservations and returns surplus memory to the underlying allocator. More...
 
kStatus kPoolAlloc_Construct (kPoolAlloc *object, kAlloc allocator)
 Constructs a kPoolAlloc object. More...
 
kStatus kPoolAlloc_EnableBlockReuse (kPoolAlloc object, kBool enabled)
 Determines whether blocks can be reused between ranks. More...
 
kSize kPoolAlloc_MaxBlockBufferSize (kPoolAlloc object)
 Returns the size limit for memory requests that can be allocated from larger blocks. More...
 
kSize kPoolAlloc_MaxCachedBufferSize (kPoolAlloc object)
 Returns the size limit for memory requests that can be cached upon deallocation. More...
 
kStatus kPoolAlloc_Reserve (kPoolAlloc object, kSize size)
 Specifies the minimum amount of memory that should be set aside for blocks. More...
 
kStatus kPoolAlloc_ReserveAt (kPoolAlloc object, kSize rank, kSize size)
 Specifies the minimum amount of memory that should be set aside at a particular rank. More...
 
kStatus kPoolAlloc_SetBlockCapacity (kPoolAlloc object, kSize size)
 Sets the maximum total amount of memory that can be used for block-based allocations. More...
 
kStatus kPoolAlloc_SetBlockSize (kPoolAlloc object, kSize size)
 Sets the approximate size of large memory blocks used to satisfy small memory requests. More...
 
kStatus kPoolAlloc_SetCacheCapacity (kPoolAlloc object, kSize size)
 Sets the maximum total amount of memory that can be used to cache buffers upon deallocation. More...
 
kStatus kPoolAlloc_SetMaxBlockBufferSize (kPoolAlloc object, kSize size)
 Sets the size limit for memory requests that can be allocated from larger blocks. More...
 
kStatus kPoolAlloc_SetMaxCachedBufferSize (kPoolAlloc object, kSize size)
 Sets the size limit for memory requests that can be cached upon deallocation. More...
 
kStatus kPoolAlloc_SetTotalCapacity (kPoolAlloc object, kSize size)
 Sets the total amount of memory that can be requested from the underlying allocator. More...
 
kStatus kPoolAlloc_Start (kPoolAlloc object)
 Prepares the allocator for first use. More...
 
kSize kPoolAlloc_TotalCapacity (kPoolAlloc object)
 Returns the total amount of memory that can be requested from the underlying allocator. More...
 
kSize kPoolAlloc_TotalSize (kPoolAlloc object)
 Reports the current amount of memory drawn from the underlying allocator. More...
 

The documentation for this class was generated from the following file: