QP/C++  7.0.1
Real-Time Embedded Framework
QMPool Class Reference

Native QF memory pool class. More...

#include <qmpool.hpp>

Public Member Functions

 QMPool (void)
 public default constructor More...
 
void init (void *const poolSto, std::uint_fast32_t poolSize, std::uint_fast16_t blockSize) noexcept
 Initializes the native QF event pool. More...
 
void * get (std::uint_fast16_t const margin, std::uint_fast8_t const qs_id) noexcept
 Obtains a memory block from a memory pool. More...
 
void put (void *const b, std::uint_fast8_t const qs_id) noexcept
 Returns a memory block back to a memory pool. More...
 
QMPoolSize getBlockSize (void) const noexcept
 return the fixed block-size of the blocks managed by this pool More...
 

Private Member Functions

 QMPool (QMPool const &)=delete
 disallow copying of QMPools More...
 
QMPooloperator= (QMPool const &)=delete
 

Private Attributes

void * m_start
 start of the memory managed by this memory pool More...
 
void * m_end
 end of the memory managed by this memory pool More...
 
void *volatile m_free_head
 head of linked list of free blocks More...
 
QMPoolSize m_blockSize
 maximum block size (in bytes) More...
 
QMPoolCtr m_nTot
 total number of blocks More...
 
QMPoolCtr volatile m_nFree
 number of free blocks remaining More...
 
QMPoolCtr m_nMin
 minimum number of free blocks ever present in this pool More...
 

Friends

class QF
 
class QS
 

Detailed Description

Description
A fixed block-size memory pool is a very fast and efficient data structure for dynamic allocation of fixed block-size chunks of memory. A memory pool offers fast and deterministic allocation and recycling of memory blocks and is not subject to fragmenation.

The QP::QMPool class describes the native QF memory pool, which can be used as the event pool for dynamic event allocation, or as a fast, deterministic fixed block-size heap for any other objects in your application.
Note
The QP::QMPool class contains only data members for managing a memory pool, but does not contain the pool storage, which must be provided externally during the pool initialization.
The native QF event pool is configured by defining the macro QF_EPOOL_TYPE_ as QP::QMPool in the specific QF port header file.

Definition at line 98 of file qmpool.hpp.

Constructor & Destructor Documentation

◆ QMPool() [1/2]

QMPool ( void  )
Description
Default constructor of a fixed block-size memory pool.
Note
The memory pool is not ready to use directly after instantiation. To become ready, the QP::QMPool::init() must be called to give the pool memory, size of this memory, and the block size to manage.

Definition at line 60 of file qf_mem.cpp.

◆ QMPool() [2/2]

QMPool ( QMPool const &  )
privatedelete

disallow assigning of QMPools

Member Function Documentation

◆ init()

void init ( void *const  poolSto,
std::uint_fast32_t  poolSize,
std::uint_fast16_t  blockSize 
)
noexcept
Description
Initialize a fixed block-size memory pool by providing it with the pool memory to manage, size of this memory, and the block size.
Parameters
[in]poolStopointer to the memory buffer for pool storage
[in]poolSizesize of the storage buffer in bytes
[in]blockSizefixed-size of the memory blocks in bytes
Attention
The caller of QP::QMPool::init() must make sure that the poolSto pointer is properly aligned. In particular, it must be possible to efficiently store a pointer at the location pointed to by poolSto. Internally, the QP::QMPool::init() function rounds up the block size blockSize so that it can fit an integer number of pointers. This is done to achieve proper alignment of the blocks within the pool.
Note
Due to the rounding of block size the actual capacity of the pool might be less than (poolSize / blockSize). You can check the capacity of the pool by calling the QP::QF::getPoolMin() function.
This function is not protected by a critical section, because it is intended to be called only during the initialization of the system, when interrupts are not allowed yet.
Many QF ports use memory pools to implement the event pools.
Precondition
The memory block must be valid and the poolSize must fit at least one free block and the blockSize must not be too close to the top of the dynamic range

Definition at line 100 of file qf_mem.cpp.

◆ get()

void * get ( std::uint_fast16_t const  margin,
std::uint_fast8_t const  qs_id 
)
noexcept
Description
The function allocates a memory block from the pool and returns a pointer to the block back to the caller.
Parameters
[in]marginthe minimum number of unused blocks still available in the pool after the allocation.
[in]qs_idQS-id of this state machine (for QS local filter)
Returns
A pointer to a memory block or NULL if no more blocks are available in the memory pool.
Note
This function can be called from any task level or ISR level.
The memory pool must be initialized before any events can be requested from it. Also, the QP::QMPool::get() function uses internally a QF critical section, so you should be careful not to call it from within a critical section when nesting of critical section is not supported.
Attention
An allocated block must be later returned back to the same pool from which it has been allocated.
See also
QP::QMPool::put()

Definition at line 224 of file qf_mem.cpp.

◆ put()

void put ( void *const  b,
std::uint_fast8_t const  qs_id 
)
noexcept
Description
Recycle a memory block to the fixed block-size memory pool.
Parameters
[in]bpointer to the memory block that is being recycled
[in]qs_idQS-id of this state machine (for QS local filter)
Attention
The recycled block must be allocated from the same memory pool to which it is returned.
Note
This function can be called from any task level or ISR level.
See also
QP::QMPool::get()
Precondition
# free blocks cannot exceed the total # blocks and the block pointer must be in range to come from this pool.

Definition at line 171 of file qf_mem.cpp.

◆ getBlockSize()

QMPoolSize getBlockSize ( void  ) const
inlinenoexcept

Definition at line 142 of file qmpool.hpp.

◆ operator=()

QMPool & operator= ( QMPool const &  )
privatedelete

Friends And Related Function Documentation

◆ QF

friend class QF
friend

Definition at line 161 of file qmpool.hpp.

◆ QS

friend class QS
friend

Definition at line 162 of file qmpool.hpp.

Field Documentation

◆ m_start

void* m_start
private

Definition at line 102 of file qmpool.hpp.

◆ m_end

void* m_end
private

Definition at line 105 of file qmpool.hpp.

◆ m_free_head

void* volatile m_free_head
private

Definition at line 108 of file qmpool.hpp.

◆ m_blockSize

QMPoolSize m_blockSize
private

Definition at line 111 of file qmpool.hpp.

◆ m_nTot

QMPoolCtr m_nTot
private

Definition at line 114 of file qmpool.hpp.

◆ m_nFree

QMPoolCtr volatile m_nFree
private

Definition at line 117 of file qmpool.hpp.

◆ m_nMin

QMPoolCtr m_nMin
private
Note
This attribute remembers the low watermark of the pool, which provides a valuable information for sizing event pools.
See also
QP::QF::getPoolMin().

Definition at line 125 of file qmpool.hpp.


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