Zen API

- Home
- Topics
- Types
- Files

All Classes Files Functions Variables Typedefs Friends Macros Modules Pages
Public Member Functions
kPoolAlloc Class Reference
kApi/Utils

## 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:

- Utils/kPoolAlloc.h