µOS++ IIIe Reference 7.0.0
The third edition of µOS++, a POSIX inspired open source framework, written in C++
Loading...
Searching...
No Matches
os::rtos::memory_pool_allocated< Allocator > Class Template Reference

Template of a synchronised memory pool with allocator. More...

#include <cmsis-plus/rtos/os.h>

+ Inheritance diagram for os::rtos::memory_pool_allocated< Allocator >:

Public Types

using allocator_type = Allocator
 Standard allocator type definition.
 
using size_t = uint16_t
 Type of memory pool size storage.
 

Public Member Functions

template<typename T >
constexpr std::size_t compute_allocated_size_bytes (std::size_t blocks, std::size_t block_size_bytes)
 Calculator for pool storage requirements.
 
Constructors & Destructor
 memory_pool_allocated (std::size_t blocks, std::size_t block_size_bytes, const attributes &attr=initializer, const allocator_type &allocator=allocator_type())
 Construct a memory pool object instance.
 
 memory_pool_allocated (const char *name, std::size_t blocks, std::size_t block_size_bytes, const attributes &attr=initializer, const allocator_type &allocator=allocator_type())
 Construct a named memory pool object instance.
 
virtual ~memory_pool_allocated () override
 Destruct the memory pool object instance.
 
Operators
bool operator== (const memory_pool &rhs) const
 Compare memory pools.
 
Public Member Functions
void * alloc (void)
 Allocate a memory block.
 
void * try_alloc (void)
 Try to allocate a memory block.
 
void * timed_alloc (clock::duration_t timeout)
 Allocate a memory block with timeout.
 
result_t free (void *block)
 Free the memory block.
 
std::size_t capacity (void) const
 Get memory pool capacity.
 
std::size_t count (void) const
 Get blocks count.
 
std::size_t block_size (void) const
 Get block size.
 
bool empty (void) const
 Check if the memory pool is empty.
 
bool full (void) const
 Check if the memory pool is full.
 
result_t reset (void)
 Reset the memory pool.
 
void * pool (void)
 Get the pool storage address.
 
Public Member Functions
const char * name (void) const
 Get object name.
 

Static Public Member Functions

Operators
static void * operator new (std::size_t bytes)
 Allocate space for a new object instance using the RTOS system allocator.
 
static void * operator new (std::size_t bytes, void *ptr)
 Emplace a new object instance.
 
static void * operator new[] (std::size_t bytes)
 Allocate space for an array of new object instances using the RTOS system allocator.
 
static void * operator new[] (std::size_t bytes, void *ptr)
 Emplace an array of new object instances.
 
static void operator delete (void *ptr, std::size_t bytes)
 Deallocate the dynamically allocated object instance. using the RTOS system allocator.
 
static void operator delete[] (void *ptr, std::size_t bytes)
 Deallocate the dynamically allocated array of object. instances using the RTOS system allocator.
 

Static Public Attributes

static const attributes initializer
 Default memory pool initialiser.
 
static constexpr memory_pool::size_t max_size
 Maximum pool size.
 

Detailed Description

template<typename Allocator = memory::allocator<void*>>
class os::rtos::memory_pool_allocated< Allocator >

Template of a synchronised memory pool with allocator.

Definition at line 548 of file os-mempool.h.

Member Typedef Documentation

◆ allocator_type

template<typename Allocator = memory::allocator<void*>>
using os::rtos::memory_pool_allocated< Allocator >::allocator_type = Allocator

Standard allocator type definition.

Definition at line 555 of file os-mempool.h.

Constructor & Destructor Documentation

◆ memory_pool_allocated() [1/2]

template<typename Allocator >
os::rtos::memory_pool_allocated< Allocator >::memory_pool_allocated ( std::size_t  blocks,
std::size_t  block_size_bytes,
const attributes attr = initializer,
const allocator_type allocator = allocator_type () 
)
inline

Construct a memory pool object instance.

Parameters
[in]blocksThe maximum number of items in the pool.
[in]block_size_bytesThe size of an item, in bytes.
[in]attrReference to attributes.
[in]allocatorReference to allocator. Default a local temporary instance.

This constructor shall initialise a memory pool object with attributes referenced by attr. If the attributes specified by attr are modified later, the memory pool attributes shall not be affected. Upon successful initialisation, the state of the memory pool variable shall become initialised.

Only the memory pool itself may be used for allocations. It is not allowed to make copies of condition variable objects.

In cases where default memory pool attributes are appropriate, the variable memory_pool::initializer can be used to initialise condition variables. The effect shall be equivalent to creating a memory pool object with the simple constructor.

If the attributes define a storage area (via mp_pool_address and mp_pool_size_bytes), that storage is used, otherwise the storage is dynamically allocated using the RTOS specific allocator (rtos::memory::allocator).

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 1001 of file os-mempool.h.

◆ memory_pool_allocated() [2/2]

template<typename Allocator >
os::rtos::memory_pool_allocated< Allocator >::memory_pool_allocated ( const char *  name,
std::size_t  blocks,
std::size_t  block_size_bytes,
const attributes attr = initializer,
const allocator_type allocator = allocator_type () 
)

Construct a named memory pool object instance.

Parameters
[in]namePointer to name.
[in]blocksThe maximum number of items in the pool.
[in]block_size_bytesThe size of an item, in bytes.
[in]attrReference to attributes.
[in]allocatorReference to allocator. Default a local temporary instance.

This constructor shall initialise a named memory pool object with attributes referenced by attr. If the attributes specified by attr are modified later, the memory pool attributes shall not be affected. Upon successful initialisation, the state of the memory pool variable shall become initialised.

Only the memory pool itself may be used for allocations. It is not allowed to make copies of condition variable objects.

In cases where default memory pool attributes are appropriate, the variable memory_pool::initializer can be used to initialise condition variables. The effect shall be equivalent to creating a memory pool object with the simple constructor.

If the attributes define a storage area (via mp_pool_address and mp_pool_size_bytes), that storage is used, otherwise the storage is dynamically allocated using the RTOS specific allocator (rtos::memory::allocator).

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 1035 of file os-mempool.h.

◆ ~memory_pool_allocated()

template<typename Allocator >
os::rtos::memory_pool_allocated< Allocator >::~memory_pool_allocated
overridevirtual

Destruct the memory pool object instance.

This destructor shall destroy a memory pool object; the object becomes, in effect, uninitialised. An implementation may cause the destructor to set the object to an invalid value.

It shall be safe to destroy an initialised memory pool object upon which no threads are currently blocked. Attempting to destroy a memory pool object upon which other threads are currently blocked results in undefined behaviour.

If the storage for the memory pool was dynamically allocated, it is deallocated using the same allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 1092 of file os-mempool.h.

Member Function Documentation

◆ alloc()

void * os::rtos::memory_pool::alloc ( void  )
inherited

Allocate a memory block.

Parameters
None.
Returns
Pointer to memory block, or nullptr if interrupted.

The alloc() function shall allocate a fixed size memory block from the memory pool.

If the memory pool is empty, alloc() shall block until a block is freed or until alloc() is cancelled/interrupted. If more than one thread is waiting to allocate a block, when a block is freed and the Priority Scheduling option is supported, then the thread of highest priority that has been waiting the longest shall be selected to allocate the block. Otherwise, it is unspecified which waiting thread allocates the block.

This function uses a critical section to protect against simultaneous access from other threads or interrupts.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 508 of file os-mempool.cpp.

◆ block_size()

std::size_t os::rtos::memory_pool::block_size ( void  ) const
inlineinherited

Get block size.

Parameters
None.
Returns
The block size, in bytes.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 931 of file os-mempool.h.

◆ capacity()

std::size_t os::rtos::memory_pool::capacity ( void  ) const
inlineinherited

Get memory pool capacity.

Parameters
None.
Returns
The max number of blocks in the pool.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 922 of file os-mempool.h.

◆ compute_allocated_size_bytes()

template<typename T >
constexpr std::size_t os::rtos::memory_pool::compute_allocated_size_bytes ( std::size_t  blocks,
std::size_t  block_size_bytes 
)
inlineconstexprinherited

Calculator for pool storage requirements.

Parameters
blocksNumber of blocks.
block_size_bytesSize of block.
Returns
Total required storage in bytes, including internal alignment.

Definition at line 188 of file os-mempool.h.

◆ count()

std::size_t os::rtos::memory_pool::count ( void  ) const
inlineinherited

Get blocks count.

Parameters
None.
Returns
The number of blocks used from the queue.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 940 of file os-mempool.h.

◆ empty()

bool os::rtos::memory_pool::empty ( void  ) const
inlineinherited

Check if the memory pool is empty.

Parameters
None
Return values
trueThe memory pool has no allocated blocks.
falseThe memory pool has allocated blocks.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 949 of file os-mempool.h.

◆ free()

result_t os::rtos::memory_pool::free ( void *  block)
inherited

Free the memory block.

Parameters
[in]blockPointer to memory block to free.
Return values
result::okThe memory block was released.
EINVALThe block does not belong to the memory pool.

Return a memory block previously allocated by alloc() back to the memory pool.

It uses a critical section to protect simultaneous access from other threads or interrupts.

Note
Can be invoked from Interrupt Service Routines.

Definition at line 783 of file os-mempool.cpp.

◆ full()

bool os::rtos::memory_pool::full ( void  ) const
inlineinherited

Check if the memory pool is full.

Parameters
None.
Return values
trueAll memory blocks are allocated.
falseThere are still memory blocks that can be allocated.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 958 of file os-mempool.h.

◆ name()

const char * os::rtos::internal::object_named::name ( void  ) const
inlineinherited

Get object name.

Parameters
None.
Returns
A null terminated string.

All objects return a non-null string; anonymous objects return "-".

Note
Can be invoked from Interrupt Service Routines.

Definition at line 759 of file os-decls.h.

◆ operator delete()

void os::rtos::internal::object_named_system::operator delete ( void *  ptr,
std::size_t  bytes 
)
inlinestaticinherited

Deallocate the dynamically allocated object instance. using the RTOS system allocator.

Parameters
ptrPointer to object.
bytesNumber of bytes to deallocate.
Returns
Nothing.

The deallocation function (3.7.4.2) called by a delete-expression to render the value of ptr invalid.

ptr shall be a null pointer or its value shall be a value returned by an earlier call to the (possibly replaced) operator new() which has not been invalidated by an intervening call to operator delete(void*).

If ptr is null, does nothing. Otherwise, reclaims the storage allocated by the earlier call to operator new.

The storage is deallocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 122 of file os-inlines.h.

◆ operator delete[]()

void os::rtos::internal::object_named_system::operator delete[] ( void *  ptr,
std::size_t  bytes 
)
inlinestaticinherited

Deallocate the dynamically allocated array of object. instances using the RTOS system allocator.

Parameters
ptrPointer to array of objects.
bytesNumber of bytes to deallocate.
Returns
Nothing.

The deallocation function (3.7.4.2) called by the array form of a delete-expression to render the value of ptr invalid.

If ptr is null, does nothing. Otherwise, reclaims the storage allocated by the earlier call to operator new.

The storage is deallocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 143 of file os-inlines.h.

◆ operator new() [1/2]

void * os::rtos::internal::object_named_system::operator new ( std::size_t  bytes)
inlinestaticinherited

Allocate space for a new object instance using the RTOS system allocator.

Parameters
bytesNumber of bytes to allocate.
Returns
Pointer to allocated object.

The allocation function (3.7.4.1) called by a new-expression (5.3.4) to allocate a storage of size bytes suitably aligned to represent any object of that size. Return a non-null pointer to suitably aligned storage (3.7.4).

The storage is allocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 44 of file os-inlines.h.

◆ operator new() [2/2]

void * os::rtos::internal::object_named_system::operator new ( std::size_t  bytes,
void *  ptr 
)
inlinestaticinherited

Emplace a new object instance.

Parameters
bytesNumber of bytes to emplace.
ptrPointer to location to emplace the object.
Returns
Pointer to emplaced object.

The allocation function (3.7.4.1) called by a placement new-expression to allocate a storage of size bytes suitably aligned to represent any object of that size. Return a non-null pointer to suitably aligned storage (3.7.4).

The storage is allocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 81 of file os-inlines.h.

◆ operator new[]() [1/2]

void * os::rtos::internal::object_named_system::operator new[] ( std::size_t  bytes)
inlinestaticinherited

Allocate space for an array of new object instances using the RTOS system allocator.

Parameters
bytesNumber of bytes to allocate.
Returns
Pointer to allocated array.

The allocation function (3.7.4.1) called by the array form of a new-expression (5.3.4) to allocate a storage of size bytes suitably aligned to represent any array object of that size or smaller.

The storage is allocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 62 of file os-inlines.h.

◆ operator new[]() [2/2]

void * os::rtos::internal::object_named_system::operator new[] ( std::size_t  bytes,
void *  ptr 
)
inlinestaticinherited

Emplace an array of new object instances.

Parameters
bytesNumber of bytes to emplace.
ptrPointer to location to emplace the object.
Returns
Pointer to emplaced array.

The allocation function (3.7.4.1) called by the array form of a placement new-expression to allocate a storage of size bytes suitably aligned to represent any array object of that size or smaller.

The storage is allocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 98 of file os-inlines.h.

◆ operator==()

bool os::rtos::memory_pool::operator== ( const memory_pool rhs) const
inlineinherited

Compare memory pools.

Return values
trueThe given memory pool is the same as this memory pool.
falseThe memory pools are different.

Identical memory pools should have the same memory address.

Definition at line 913 of file os-mempool.h.

◆ pool()

void * os::rtos::memory_pool::pool ( void  )
inlineinherited

Get the pool storage address.

Parameters
None.
Returns
Pointer to storage.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 967 of file os-mempool.h.

◆ reset()

result_t os::rtos::memory_pool::reset ( void  )
inherited

Reset the memory pool.

Parameters
None.
Return values
result::okThe memory pool was reset.
EPERMCannot be invoked from an Interrupt Service Routines.

Reset the memory pool to the initial state, with all blocks free.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 843 of file os-mempool.cpp.

◆ timed_alloc()

void * os::rtos::memory_pool::timed_alloc ( clock::duration_t  timeout)
inherited

Allocate a memory block with timeout.

Parameters
[in]timeoutTimeout to wait, in clock units (ticks or seconds).
Returns
Pointer to memory block, or nullptr if timeout.

The timed_alloc() function shall allocate a fixed size memory block from the memory pool.

If the memory pool is empty, timed_alloc() shall block until a block is freed or until timed_alloc() is cancelled/interrupted. If more than one thread is waiting to allocate a block, when a block is freed and the Priority Scheduling option is supported, then the thread of highest priority that has been waiting the longest shall be selected to allocate the block. Otherwise, it is unspecified which waiting thread allocates the block.

The timed_alloc() function shall allocate any of the available blocks, regardless of their age and the order they were freed. However, if no blocks are available, the wait for such a block shall be terminated when the specified timeout expires.

The timeout shall expire after the number of time units (that is when the value of that clock equals or exceeds (now()+duration). The resolution of the timeout shall be the resolution of the clock on which it is based.

Under no circumstance shall the operation fail with a timeout if a block can be allocated from the memory pool immediately. The validity of the timeout need not be checked if the block can be allocated immediately.

The clock used for timeouts can be specified via the clock attribute. By default, the clock derived from the scheduler timer is used, and the durations are expressed in ticks.

This function uses a critical section to protect against simultaneous access from other threads or interrupts.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 669 of file os-mempool.cpp.

◆ try_alloc()

void * os::rtos::memory_pool::try_alloc ( void  )
inherited

Try to allocate a memory block.

Parameters
None.
Returns
Pointer to memory block, or nullptr if no memory available.

Try to allocate a fixed size memory block from the memory pool, if available, return it, otherwise return nullptr.

The timed_alloc() function shall try to allocate a fixed size memory block from the memory pool.

If the memory pool is empty, timed_alloc() shall immediately return 'nullptr'.

This function uses a critical section to protect against simultaneous access from other threads or interrupts.

Note
Can be invoked from Interrupt Service Routines.

Definition at line 604 of file os-mempool.cpp.


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