BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_pool
Next|Prev|Up
The Structure
Members
Operations
BrPoolBlockAllocate()
BrPoolBlockFree()
BrPoolEmpty()
Copy/Assign
Access & Maintenance
Referencing & Lifetime
Initialisation
Construction & Destruction
BrPoolAllocate()
BrPoolFree()
Supplementary

br_pool


The Structure

This structure holds details of a memory block pool (an optimised memory allocation scheme on a per data structure basis). This is ideal for cases where a particular data structure has intensive dynamic storage, e.g. matrices.

Note that currently, there is no automatic contraction of Pools, nor are there functions to achieve this (with the current implementation it would have a relatively high processing overhead). Therefore, it may be wise to destroy Pools when possible, if they have irregular or sporadic use, or memory is at a premium.

The typedef

(See pool.h for precise declaration and ordering)

Primary

br_pool_block * free Linked list of unused blocks

br_uint_32 block_size Size of each item

br_uint_32 chunk_size Number of blocks to increase pool by

int mem_type Memory class of blocks

Related Functions

Memory Management

BrAllocatorSet()
100.

Members

Primary

br_pool_block * free

This is a pointer to the next available block of memory (of size block_size). When freed, blocks are cast as br_pool_block303 and inserted at the head of the list to keep track of them. An allocation simply removes the item at the head from the list. It may then be initialised as required.

br_uint_32 block_size

This is the size of each item, or memory block. Its value must be greater than or equal to sizeof(br_pool_block), if not, memory corruption will ensue. This is typically 4 bytes, but given that pools are intended for larger structures, this is not a significant restriction. See BrPoolAllocate()301.

br_uint_32 chunk_size

When all the blocks in a pool are allocated (or the pool is empty), the value of this member determines the number of blocks that will be added to the pool to enable further block allocations.

uint mem_type

This is the memory class from which the blocks should be allocated. Any number of pools may exist for a given memory class.

Operations


BrPoolBlockAllocate()

Description:
Allocate a block from a pool. If the pool is full, it will expand as necessary.

Declaration:
void* BrPoolBlockAllocate(br_pool* pool)

Arguments:
br_pool * pool

A pointer to the relevant pool.

Result:
void *

Returns a pointer to the allocated block, or NULL if unsuccessful.


BrPoolBlockFree()

Description:
Deallocate a block from a pool.

Declaration:
void BrPoolBlockFree(br_pool* pool, void* b)

Arguments:
br_pool * pool

A pointer to the relevant pool.

void * b

A pointer to the block to deallocate.


BrPoolEmpty()

Description:
Mark all blocks in a pool as unused.

Declaration:
void BrPoolEmpty(br_pool* pool)

Arguments:
br_pool * pool

A pointer to the pool to be emptied.


Copy/Assign

Do not copy.

Access & Maintenance

No members should be modified. The structure will be maintained until the pool is freed using BrPoolFree()302. No additional maintenance required.

Referencing & Lifetime

Do not reference a copy. Ensure that references to a pool descriptor do not outlast the pool.

Initialisation

Initialisation is performed by BrPoolAllocate()301.

Effectively this sets free to NULL, block_size to the specified value (aligned appropriately), chunk_size to the specified value, and mem_type to the specified value.

Construction & Destruction

Memory pool structures should be constructed by BrPoolAllocate()301, as this will allocate the pool descriptors from the pool resource class. Some Pool functions depend on this.


BrPoolAllocate()

Description:
Create a new block pool.

Declaration:
br_pool* BrPoolAllocate(int block_size, int chunk_size, br_uint_8 mem_type)

Arguments:
int block_size

The size of each block, in bytes. Minimum value is 1, though note that this size will be rounded up to the next multiple of a suitable alignment factor, typically 8 (BR_POOL_ALIGN+1). Pools are not intended for simple data structures.

int chunk_size

The number of blocks to allocate each time the pool becomes full. The value should be between 1 and say, 10% of the maximum number of blocks allocated at any one time. Naturally, there is a compromise between saving processing overhead for each memory allocation (only when the pool grows), and saving memory overhead in terms of average unused blocks.

br_uint_8 mem_type

Memory type. More than one pool may be created for a particular memory class.

Result:
br_pool *

Returns a pointer to the new pool, or NULL if it could not be created.


BrPoolFree()

Description:
Deallocate an entire pool, thereby losing any blocks it may contain.

Declaration:
void BrPoolFree(br_pool* pool)

Arguments:
br_pool * pool

A pointer to the pool to be deallocated.


Supplementary

Given that Pools are registered in the "POOL" resource class, the resource class supplementary functions are available.


Generated with
CERN WebMaker