QP/C++  7.4.0-rc.1
Real-Time Embedded Framework
Loading...
Searching...
No Matches
QP::QMPool Class Reference

Native QF Memory Pool. More...

#include "qmpool.hpp"

Public Member Functions

 QMPool ()
 
void init (void *const poolSto, std::uint_fast32_t const poolSize, std::uint_fast16_t const blockSize) noexcept
 
void * get (std::uint_fast16_t const margin, std::uint_fast8_t const qsId) noexcept
 
void put (void *const block, std::uint_fast8_t const qsId) noexcept
 
QMPoolSize getBlockSize () const noexcept
 
QMPoolCtr getNMin () const noexcept
 
QMPoolCtr getNFree () const noexcept
 
void * getFromISR (std::uint_fast16_t const margin, std::uint_fast8_t const qsId) noexcept
 
void putFromISR (void *const b, std::uint_fast8_t const qsId) noexcept
 

Private Member Functions

 QMPool (QEQueue const &other)=delete
 
QMPooloperator= (QMPool const &other)=delete
 

Private Attributes

QFreeBlockm_start
 
QFreeBlockm_end
 
QFreeBlock *volatile m_free_head
 
QMPoolSize m_blockSize
 
QMPoolCtr m_nTot
 
QMPoolCtr volatile m_nFree
 
QMPoolCtr m_nMin
 

Detailed Description

Native QF Memory Pool.

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 fragmentation.

The QP::QMPool class describes the native QF memory pool, which can be used as the event pool for mutable event allocation, or as a fast, deterministic fixed block-size heap for any other objects in your application.

Note
QMPool 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.

Definition at line 101 of file qmpool.hpp.

Constructor & Destructor Documentation

◆ QMPool() [1/2]

QP::QMPool::QMPool ( )
inline

Default constructor of QP::QMPool

Definition at line 112 of file qmpool.hpp.

◆ QMPool() [2/2]

QP::QMPool::QMPool ( QEQueue const & other)
privatedelete

Member Function Documentation

◆ init()

void QP::QMPool::init ( void *const poolSto,
std::uint_fast32_t const poolSize,
std::uint_fast16_t const blockSize )
noexcept

Initializes the native QF memory pool

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
Precondition qf_mem:100
  • the memory block must be valid
  • the poolSize must fit at least one free block
  • the blockSize must not be too close to the top of the dynamic range
Attention
The caller of 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 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 QF_getPoolMin() function.
This function uses a potentially long critical section, because it is intended to be called only during the initialization of the system, when timing is not critical.
Many QF ports use memory pools to implement the event pools.
Traceability
  • DVR-QP-MC4-R11_05

Definition at line 72 of file qf_mem.cpp.

◆ get()

void * QP::QMPool::get ( std::uint_fast16_t const margin,
std::uint_fast8_t const qsId )
noexcept

Obtain a memory block from a memory pool.

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]qsIdQS-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 me must be initialized before any events can be requested from it. Also, the 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.
Traceability
  • DVR-QP-MC4-R18_03
  • DVR-QP-MC4-R11_05
  • DVR-QP-MC4-R18_03

Definition at line 139 of file qf_mem.cpp.

◆ put()

void QP::QMPool::put ( void *const block,
std::uint_fast8_t const qsId )
noexcept

Recycles a memory block back to a memory pool.

Recycle a memory block to the fixed block-size memory pool.

Parameters
[in]blockpointer to the memory block that is being recycled
[in]qsIdQS-id of this state machine (for QS local filter)
Precondition qf_mem:200
  • the number of free blocks cannot exceed the total # blocks
  • the block pointer must be in range for this pool.
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.
Traceability
  • DVR-QP-MC4-R11_05
  • DVR-QP-MC4-R18_03

Definition at line 216 of file qf_mem.cpp.

◆ getBlockSize()

QMPoolSize QP::QMPool::getBlockSize ( ) const
noexcept

Definition at line 255 of file qf_mem.cpp.

◆ getNMin()

QMPoolCtr QP::QMPool::getNMin ( ) const
inlinenoexcept

Definition at line 132 of file qmpool.hpp.

◆ getNFree()

QMPoolCtr QP::QMPool::getNFree ( ) const
inlinenoexcept

Definition at line 135 of file qmpool.hpp.

◆ operator=()

QMPool & QP::QMPool::operator= ( QMPool const & other)
privatedelete

◆ getFromISR()

void * QP::QMPool::getFromISR ( std::uint_fast16_t const margin,
std::uint_fast8_t const qsId )
noexcept

◆ putFromISR()

void QP::QMPool::putFromISR ( void *const b,
std::uint_fast8_t const qsId )
noexcept

Member Data Documentation

◆ m_start

QFreeBlock* QP::QMPool::m_start
private

Start of the memory managed by this memory pool

Definition at line 103 of file qmpool.hpp.

◆ m_end

QFreeBlock* QP::QMPool::m_end
private

End of the memory managed by this memory pool

Definition at line 104 of file qmpool.hpp.

◆ m_free_head

QFreeBlock* volatile QP::QMPool::m_free_head
private

Head of linked list of free memory blocks

Definition at line 105 of file qmpool.hpp.

◆ m_blockSize

QMPoolSize QP::QMPool::m_blockSize
private

Memory block size [bytes] held by this fixed-size pool.

Definition at line 106 of file qmpool.hpp.

◆ m_nTot

QMPoolCtr QP::QMPool::m_nTot
private

Total number of memory blocks in this pool

Definition at line 107 of file qmpool.hpp.

◆ m_nFree

QMPoolCtr volatile QP::QMPool::m_nFree
private

Number of free memory blocks remaining in the pool at this point

Definition at line 108 of file qmpool.hpp.

◆ m_nMin

QMPoolCtr QP::QMPool::m_nMin
private

Minimum number of free blocks ever present in this pool

This attribute remembers the low watermark of the pool, which provides a valuable information for sizing event pools. (

See also
QF_getPoolMin()).

Definition at line 109 of file qmpool.hpp.


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