Object PoolPool.h
The object pool is a set of pre allocated objects kept ready to use, rather than allocating and destroying them on demand. A client of the pool requests an object from the pool and perform operations on the returned object. When the client has finished, it returns the object to the pool rather than destroying it.
Object pooling can offer a significant performance boost in situations where the cost of initializing a class instance is high, the rate of instantiation of a class is high, and the number of instances in use at any one time is low. The pooled object is obtained in predictable time when creation of the new objects may take variable time.
Contents
Function list
| C function name | Access type | C++ function name | Access type |
|---|---|---|---|
| Alloc | RW | (constructor) Pool | RW |
| Capacity | RO | (destructor) ~Pool | RW |
| Clear | RW | Alloc | RW |
| Free | RW | Capacity | RO |
| FreePool | RW | Clear | RW |
| InitPool | RW | Free | RW |
| IsAlloc | RO | IsAlloc | RO |
| IsEmpty | RO | IsEmpty | RO |
| IsFree | RO | IsFree | RO |
| IsFull | RO | IsFull | RO |
| IsInit | RO | IsInit | RO |
| Size | RO | Size | RO |
| C function name | Access type | C++ function name | Access type |
Constructor
Cvoid Pool_InitPool (struct Pool *pool, size_t capacity, size_t osize, uint8_t align);
C++Pool::Pool (size_t capacity, size_t osize, uint8_t align);
Description: Init new object pool instance.
Access type: RW
Parameters:
- pool - pointer to the pool structure
- capacity - max count of objects that the pool can hold
- osize - typical object size which will be stored into the pool
- align - power of 2 to align the objects. Align factor is compute by formula: 2align. Min align is 3, which means 8 bytes.
Return value: None.
Destructor
Cvoid Pool_FreePool (struct Pool *pool);
C++Pool::~Pool (void);
Description: Reset the object pool instance and release all memory blocks are used by the object.
Access type: RW
Parameters:
- pool - pointer to the pool structure
Return value: None.
Pool functions
Object pool provides basic functions to allocate and release objects from the pool, check objects status (is allocated/released) and clearing the pool. Object pool store object's status internally, so they can have no field to trace their status. If you try to make a double release of an object, poll will check this situation and will not modify already deallocated object.
Allocate new object
Cvoid* Pool_Alloc (struct Pool *pool);
C++void* Pool::Alloc (void);
Description: Allocate new object in the object pool.
Access type: RW
Parameters:
- pool - pointer to the pool structure
Return value:
- Pointer to newly allocated object.
- NULL if pool is full and cannot allocate one more object.
Deallocate existing object
Cvoid Pool_Free (struct Pool *pool, void *ptr);
C++void Pool::Free (void *ptr);
Description: Deallocate existing object in the object pool. If the object is already free, then do nothing.
Access type: RW
Parameters:
- pool - pointer to the pool structure
- ptr - pointer to the object to free
Return value: None.
Check if object is allocated
Cbool Pool_IsAlloc (const struct Pool *pool, void *ptr);
C++bool Pool::IsAlloc (void *ptr) const;
Description: Check if target object into the object pool is allocated.
Access type: RO
Parameters:
- pool - pointer to the pool structure
- ptr - pointer to the object to check
Return value:
- TRUE (1) if target object is allocated.
- FALSE (0) if target object is not allocated.
Check if object is free
Cbool Pool_IsFree (const struct Pool *pool, void *ptr);
C++bool Pool::IsFree (void *ptr) const;
Description: Check if target object into the object pool is free.
Access type: RO
Parameters:
- pool - pointer to the pool structure
- ptr - pointer to the object to check
Return value:
- TRUE (1) if target object is free.
- FALSE (0) if target object is not free.
Clear object pool
Cvoid Pool_Clear (struct Pool *pool);
C++void Pool::Clear (void);
Description: Recreate the object pool and mark all objects as empty.
Access type: RW
Parameters:
- pool - pointer to the pool structure
Return value: None.
Pool properties
Pool capacity
Csize_t Pool_Capacity (const struct Pool *pool);
C++size_t Pool::Capacity (void) const;
Description: Return the object pool capacity.
Access type: RO
Parameters:
- pool - pointer to the pool structure
Return value: Max count of objects that pool can hold.
Pool size
Csize_t Pool_Size (const struct Pool *pool);
C++size_t Pool::Size (void) const;
Description: Return current size of the object pool (count of allocated objects).
Access type: RO
Parameters:
- pool - pointer to the pool structure
Return value: Count of allocated objects inside the pool.
Check if pool is full
Cbool Pool_IsFull (const struct Pool *pool);
C++bool Pool::IsFull (void) const;
Description: Check if the object pool is full.
Access type: RO
Parameters:
- pool - pointer to the pool structure
Return value:
- TRUE (1) if object pool is full.
- FALSE (0) if object pool is not full.
Check if pool is empty
Cbool Pool_IsEmpty (const struct Pool *pool);
C++bool Pool::IsEmpty (void) const;
Description: Check if the object pool is empty.
Access type: RO
Parameters:
- pool - pointer to the pool structure
Return value:
- TRUE (1) if object pool is empty.
- FALSE (0) if object pool is not empty.
Check if pool is initialized
Cbool Pool_IsInit (const struct Pool *pool);
C++bool Pool::IsInit (void) const;
Description: Check if the object pool is initialized.
Access type: RO
Parameters:
- pool - pointer to the pool structure
Return value:
- TRUE (1) if object pool is initialized.
- FALSE (0) if object pool is not initialized.