Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups 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...

## Member Function Documentation

kSize kPoolAlloc_BlockCapacity | ( | kPoolAlloc | object | ) |

Returns the maximum amount of memory that can be used for block-based allocations.

Parameters

  object | kPoolAlloc object.

Returns
  Block memory capacity, in bytes.

kBool kPoolAlloc_BlockReuseEnabled | ( | kPoolAlloc | object | ) |

Reports whether blocks can be reused between ranks.

Parameters

  object | kPoolAlloc object.

Returns
  kTRUE if block reuse is enabled; kFALSE otherwise.

kSize kPoolAlloc_BlockSize | ( | kPoolAlloc | object | ) |

Returns the approximate size of large memory blocks used to satisfy small memory requests.

Parameters

  object | kPoolAlloc object.

Returns
  Block size, in bytes.

kSize kPoolAlloc_BufferCountAt | ( | kPoolAlloc | object,
|  | kSize | rank
| ) |  |

Reports the total number of memory buffers at the given rank.

This function reports the total number of buffers, including buffers currently in use (allocated via kAlloc_Get and not yet freed) and buffers cached for later use.

Parameters

  object | kPoolAlloc object.
  rank | Memory rank (base-2 logarithm of memory size).

Returns
  Buffer count.

kSize kPoolAlloc_CacheCapacity | ( | kPoolAlloc | object | ) |

Returns the maximum total amount of memory that can be used to cache buffers upon deallocation.

Parameters

  object | kPoolAlloc object.

Returns
  Cached memory capacity, in bytes.

kStatus kPoolAlloc_Clear | ( | kPoolAlloc | object | ) |

Returns surplus memory to the underlying allocator.

For block-based ranks, any unused blocks will be returned to the underlying allocator. Reservations made using kPoolAlloc_Reserve/kPoolAlloc_ReserveAt are honored; those blocks will be preserved for later use.

For ranks configured to cache buffers upon deallocation, any unused buffers will be returned to the underlying allocator. Reservations made using kPoolAlloc_ReserveAt are honored; those buffers will be preserved for later use.

Parameters

  object | kPoolAlloc object.

Returns
  Operation status.

kStatus kPoolAlloc_ClearAll | ( | kPoolAlloc | object | ) |

Removes any existing memory reservations and returns surplus memory to the underlying allocator.

Parameters

  object | kPoolAlloc object.

Returns
  Operation status.

kStatus kPoolAlloc_Construct | ( | kPoolAlloc * | object,
|  | kAlloc | allocator
| ) |  |

Constructs a kPoolAlloc object.

The 'allocator' argument specifies the underlying memory allocator used by this kPoolAlloc instance to satisfy memory requests.

Parameters

  object | Destination for the constructed object handle.
  allocator | Memory allocator (or kNULL for default).

Returns
  Operation status.

kStatus kPoolAlloc_EnableBlockReuse | ( | kPoolAlloc | object,
|  | kBool | enabled
| ) |  |

Determines whether blocks can be reused between ranks.

When a memory request qualifies for block-based allocation, and no free buffers are available at the required rank, a new block must be provided. If block reuse is enabled, then free blocks from other ranks can be reassigned as needed. If block reuse is disabled, then blocks remain at the rank to which they are first assigned.

Block reuse can increase allocation time slightly, due to the need to search through all ranks for a free block. Reuse is enabled by default.

Parameters

  object | kPoolAlloc object.
  enabled | kTRUE to enable reuse; kFALSE otherwise.

Returns
  Operation status.

kSize kPoolAlloc_MaxBlockBufferSize | ( | kPoolAlloc | object | ) |

Returns the size limit for memory requests that can be allocated from larger blocks.

Parameters

  object | kPoolAlloc object.

Returns
  Maximum size for a block-based allocation, in bytes.

kSize kPoolAlloc_MaxCachedBufferSize | ( | kPoolAlloc | object | ) |

Returns the size limit for memory requests that can be cached upon deallocation.

Parameters

  object | kPoolAlloc object.

Returns
  Maximum cached allocation size, in bytes.

kStatus kPoolAlloc_Reserve | ( | kPoolAlloc | object,
|  | kSize | size
| ) |  |

Specifies the minimum amount of memory that should be set aside for blocks.

This function can be used to ensure that the specified amount of memory is set aside for block-based allocations. The amount of memory specified is inclusive of any existing block memory (e.g., individual rank reservations).

This function cannot be used before calling kPoolAlloc_Start.

Parameters

  object | kPoolAlloc object.
  size | Amount of memory to reserve, in bytes.

Returns
  Operation status.

kStatus kPoolAlloc_ReserveAt | ( | kPoolAlloc | object,
|  | kSize | rank,
|  | kSize | size
| ) |  |

Specifies the minimum amount of memory that should be set aside at a particular rank.

This function can be used to ensure that the specified amount of memory is set aside for block-based allocations at a specific rank.

This function can also be used to pre-cache individual buffers at a specific rank. However, these buffers may later be deallocated if the CacheCapacity limit is reached.

This function cannot be used before calling kPoolAlloc_Start.

Parameters

  object | kPoolAlloc object.
  rank | Memory rank (base-2 logarithm of memory size).
  size | Amount of memory to reserve, in bytes.

Returns
  Operation status.

kStatus kPoolAlloc_SetBlockCapacity | ( | kPoolAlloc | object,
|  | kSize | size
| ) |  |

Sets the maximum total amount of memory that can be used for block-based allocations.

Blocks are dynamically allocated when needed; this property controls the maximum amount of memory that can be used for blocks. This property is kSIZE_MAX by default.

Parameters

  object | kPoolAlloc object.
  size | Block memory capacity, in bytes.

Returns
  Operation status.

kStatus kPoolAlloc_SetBlockSize | ( | kPoolAlloc | object,
|  | kSize | size
| ) |  |

Sets the approximate size of large memory blocks used to satisfy small memory requests.

Blocks are assigned to one rank at a time. Multiple small allocations are typically performed from each larger block. The number of allocations that can be performed from a single block depends on the rank.

A common block size is used for all ranks to allow free blocks to be transferred between ranks (if reuse is enabled).

Parameters

  object | kPoolAlloc object.
  size | Block size, in bytes.

Returns
  Operation status.

kStatus kPoolAlloc_SetCacheCapacity | ( | kPoolAlloc | object,
|  | kSize | size
| ) |  |

Sets the maximum total amount of memory that can be used to cache buffers upon deallocation.

This property does not affect block-based allocations, which can be limited using the kPoolAlloc_SetBlockCapacity function.

This property is kSIZE_MAX by default.

Parameters

  object | kPoolAlloc object.
  size | Cached memory capacity, in bytes.

Returns
  Operation status.

kStatus kPoolAlloc_SetMaxBlockBufferSize | ( | kPoolAlloc | object,
|  | kSize | size
| ) |  |

Sets the size limit for memory requests that can be allocated from larger blocks.

This property must be smaller than the BlockSize property. By default, this property is zero (block-based allocation is disabled).

Parameters

  object | kPoolAlloc object.
  size | Maximum block-based allocation size, in bytes.

Returns
  Operation status.

kStatus kPoolAlloc_SetMaxCachedBufferSize | ( | kPoolAlloc | object,
|  | kSize | size
| ) |  |

Sets the size limit for memory requests that can be cached upon deallocation.

Small allocations are typically configured to be provided by block-based allocation, which automatically caches deallocated buffers for reuse. But larger (individually allocated) buffers can also be cached upon deallocation for later use. This property controls the maximum buffer size than can be cached upon deallocation.

This property is zero by default (caching of individual allocations is disabled).

Parameters

  object | kPoolAlloc object.
  size | Maximum cached allocation size, in bytes.

Returns
  Operation status.

kStatus kPoolAlloc_SetTotalCapacity | ( | kPoolAlloc | object,
|  | kSize | size
| ) |  |

Sets the total amount of memory that can be requested from the underlying allocator.

This property is kSIZE_MAX by default.

Parameters

  object | kPoolAlloc object.
  size | Amount of memory that can be requested from underlying allocator, in bytes.

Returns
  Operation status.

kStatus kPoolAlloc_Start | ( | kPoolAlloc | object | ) |

Prepares the allocator for first use.

This function should be called after configuration properties have been provided, and before using memory reservation or allocation functions.

Configuration functions cannot be used after calling kPoolAlloc_Start.

Parameters

  object | kPoolAlloc object.

Returns
  Operation status.

kSize kPoolAlloc_TotalCapacity | ( | kPoolAlloc | object | ) |

Returns the total amount of memory that can be requested from the underlying allocator.

Parameters

  object | kPoolAlloc object.

Returns
  Amount of memory that can be requested from underlying allocator, in bytes.

kSize kPoolAlloc_TotalSize | ( | kPoolAlloc | object | ) |

Reports the current amount of memory drawn from the underlying allocator.

Total does not include the kPoolAlloc object header; all other memory is included.

Parameters

  object | kPoolAlloc object.

Returns
  Total memory, in bytes.

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

- Utils/kPoolAlloc.h