Template of a synchronised memory pool with block type and local storage. More...

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

Inheritance diagram for os::rtos::memory_pool_inclusive< T, N >:

Public Types
using	allocator_type = memory::allocator< thread::stack::allocation_element_t >
	Default RTOS allocator.

using	size_t = uint16_t
	Type of memory pool size storage.

using	value_type = T
	Local type of message.

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_inclusive (const attributes &attr=initializer)
	Construct a memory pool object instance.

	memory_pool_inclusive (const char *name, const attributes &attr=initializer)
	Construct a named memory pool object instance.

virtual	~memory_pool_inclusive () override
	Destruct the memory pool object instance.

Public Member Functions
value_type *	alloc (void)
	Allocate a memory block.

value_type *	try_alloc (void)
	Allocate a memory block.

value_type *	timed_alloc (clock::duration_t timeout)
	Allocate a memory block with timeout.

result_t	free (value_type *block)
	Free the memory block.

Operators
bool	operator== (const memory_pool &rhs) const
	Compare memory pools.

Public Member Functions
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 std::size_t	blocks = N
	Local constant based on template definition.

static const attributes	initializer
	Default memory pool initialiser.

static constexpr memory_pool::size_t	max_size
	Maximum pool size.

Protected Attributes
Private Member Variables
arena< void *, blocks, sizeof(T)>	arena_
	Local storage for the pool.

Detailed Description

template<typename T, std::size_t N>
class os::rtos::memory_pool_inclusive< T, N >

Template of a synchronised memory pool with block type and local storage.

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

Member Typedef Documentation

◆ allocator_type

using os::rtos::memory_pool::allocator_type = memory::allocator<thread::stack::allocation_element_t>

inherited

Default RTOS allocator.

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

◆ value_type

template<typename T , std::size_t N>

using os::rtos::memory_pool_inclusive< T, N >::value_type = T

Local type of message.

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

Constructor & Destructor Documentation

◆ memory_pool_inclusive() [1/2]

template<typename T , std::size_t N>

os::rtos::memory_pool_inclusive< T, N >::memory_pool_inclusive ( const attributes & attr = initializer )

Construct a memory pool object instance.

Parameters

[in] attr Reference to attributes.

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.

The storage shall be statically allocated inside the memory pool object instance.

Implemented as a wrapper over the parent constructor, automatically passing the message size and the storage details.

Warning: Cannot be invoked from Interrupt Service Routines.

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

◆ memory_pool_inclusive() [2/2]

template<typename T , std::size_t N>

os::rtos::memory_pool_inclusive< T, N >::memory_pool_inclusive	(	const char *	name,
		const attributes &	attr = `initializer`
	)

Construct a named memory pool object instance.

Parameters

[in]	name	Pointer to name.
[in]	attr	Reference to attributes.

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.

The storage shall be statically allocated inside the memory pool object instance.

Implemented as a wrapper over the parent constructor, automatically passing the message size and the storage details.

Warning: Cannot be invoked from Interrupt Service Routines.

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

◆ ~memory_pool_inclusive()

template<typename T , std::size_t N>

os::rtos::memory_pool_inclusive< T, N >::~memory_pool_inclusive

overridevirtual

Destruct the memory pool object instance.

This destructor shall destroy the 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.

Warning: Cannot be invoked from Interrupt Service Routines.

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

Member Function Documentation

◆ alloc()

template<typename T , std::size_t N>

memory_pool_inclusive< T, N >::value_type * os::rtos::memory_pool_inclusive< T, N >::alloc ( void )

inline

Allocate a memory block.

Parameters: None.

Returns: Pointer to memory block, or nullptr if interrupted.

Wrapper over the parent method, automatically passing the cast.

See also: memory_pool::alloc().

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

◆ 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 926 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 917 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

blocks	Number of blocks.
block_size_bytes	Size of block.

Returns: Total required storage in bytes, including internal alignment.

Definition at line 190 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 935 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

true	The memory pool has no allocated blocks.
false	The memory pool has allocated blocks.

Note: Can be invoked from Interrupt Service Routines.

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

◆ free() [1/2]

template<typename T , std::size_t N>

result_t os::rtos::memory_pool_inclusive< T, N >::free ( value_type * block )

inline

Free the memory block.

Parameters: None.

Return values

result::ok	The memory block was released.
EINVAL	The block does not belong to the memory pool.

Wrapper over the parent method, automatically passing the cast.

See also: memory_pool::free().

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

◆ free() [2/2]

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

inherited

Free the memory block.

Parameters

[in] block Pointer to memory block to free.

Return values

result::ok	The memory block was released.
EINVAL	The 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 785 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

true	All memory blocks are allocated.
false	There are still memory blocks that can be allocated.

Note: Can be invoked from Interrupt Service Routines.

Definition at line 953 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 774 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

ptr	Pointer to object.
bytes	Number 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 137 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

ptr	Pointer to array of objects.
bytes	Number 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 158 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

bytes Number 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 59 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

bytes	Number of bytes to emplace.
ptr	Pointer 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 96 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

bytes Number 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 77 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

bytes	Number of bytes to emplace.
ptr	Pointer 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 113 of file os-inlines.h.

◆ operator==()

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

inlineinherited

Compare memory pools.

Return values

true	The given memory pool is the same as this memory pool.
false	The memory pools are different.

Identical memory pools should have the same memory address.

Definition at line 908 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 962 of file os-mempool.h.

◆ reset()

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

inherited

Reset the memory pool.

Parameters: None.

Return values

result::ok	The memory pool was reset.
EPERM	Cannot 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()

template<typename T , std::size_t N>

memory_pool_inclusive< T, N >::value_type * os::rtos::memory_pool_inclusive< T, N >::timed_alloc ( clock::duration_t timeout )

inline

Allocate a memory block with timeout.

Parameters

[in] timeout Timeout to wait, in clock units (ticks or seconds).

Returns: Pointer to memory block, or nullptr if timeout.

Wrapper over the parent method, automatically passing the cast.

See also: memory_pool::timed_alloc().

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

◆ try_alloc()

template<typename T , std::size_t N>

memory_pool_inclusive< T, N >::value_type * os::rtos::memory_pool_inclusive< T, N >::try_alloc ( void )

inline

Allocate a memory block.

Parameters: None.

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

Wrapper over the parent method, automatically passing the cast.

See also: memory_pool::try_alloc().

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

Member Data Documentation

◆ arena_

template<typename T , std::size_t N>

arena<void*, blocks, sizeof(T)> os::rtos::memory_pool_inclusive< T, N >::arena_

protected

Local storage for the pool.

The local storage is large enough to include blocks blocks of type T. For performance reasons, the individual components are aligned as pointers.

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

◆ blocks

template<typename T , std::size_t N>

const std::size_t os::rtos::memory_pool_inclusive< T, N >::blocks = N

static

Local constant based on template definition.

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

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

os-mempool.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ allocator_type

◆ value_type

Constructor & Destructor Documentation

◆ memory_pool_inclusive() [1/2]

◆ memory_pool_inclusive() [2/2]

◆ ~memory_pool_inclusive()

Member Function Documentation

◆ alloc()

◆ block_size()

◆ capacity()

◆ compute_allocated_size_bytes()

◆ count()

◆ empty()

◆ free() [1/2]

◆ free() [2/2]

◆ full()

◆ name()

◆ operator delete()

◆ operator delete[]()

◆ operator new() [1/2]

◆ operator new() [2/2]

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

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

◆ operator==()

◆ pool()

◆ reset()

◆ timed_alloc()

◆ try_alloc()

Member Data Documentation

◆ arena_

◆ blocks