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

Description

Public Member Functions

Member Function Documentation