C++ API memory management definitions. More...

Namespaces
namespace	std
	Standard std namespace.

Classes
class	os::rtos::memory::allocator_deleter< A >
	Allocator deleter. More...

class	os::rtos::memory::allocator_stateless_default_resource< T >
	Standard allocator based on the RTOS system default memory manager. More...

class	os::rtos::memory::allocator_stateless_polymorphic_synchronized< T, L, get_resource >
	Allocator using memory resources. More...

class	os::memory::block_pool
	Memory resource managing a pool of same size blocks, using an existing arena. More...

class	os::memory::block_pool_typed_allocated< T, A >
	Memory resource managing a dynamically allocated pool. of same size blocks of type T. More...

class	os::memory::block_pool_typed_inclusive< T, N >
	Memory resource managing an internal pool. of same size blocks of type T. More...

class	os::memory::first_fit_top
	Memory resource implementing the first fit, top-down allocation policies, using an existing arena. More...

class	os::memory::first_fit_top_allocated< A >
	Memory resource implementing the first fit, top-down allocation policies, using a dynamically allocated arena. More...

class	os::memory::first_fit_top_inclusive< N >
	Memory resource implementing the first fit, top-down allocation policies, using an internal arena. More...

class	os::memory::lifo
	Memory resource implementing the LIFO allocation/deallocation policies, using an existing arena. More...

class	os::memory::lifo_allocated< A >
	Memory resource implementing the LIFO allocation policies, using a dynamically allocated arena. More...

class	os::memory::lifo_inclusive< N >
	Memory resource implementing the LIFO allocation policies, using an internal arena. More...

class	os::memory::malloc_memory_resource
	A memory manager that allocates memory via the system `std::malloc()` and deallocates via `std::free()`. More...

class	os::rtos::memory::memory_resource
	Memory resource manager (abstract class). More...

class	os::memory::new_delete_memory_resource
	A memory manager that allocates memory via the system `operator new` and deallocates via `operator delete`. More...

class	os::memory::null_memory_resource
	An internal memory manager that throws a `bad_alloc()` exception when trying to allocate. More...

Typedefs
template<typename T >
using	os::rtos::memory::allocator = allocator_stateless_default_resource< T >
	Type of allocator used by the system objects. Must be stateless.

template<typename T , typename U = T>
using	os::rtos::memory::allocator_typed = allocator_stateless_polymorphic_synchronized< T, scheduler::lockable, get_resource_typed< U > >
	Type of an allocator for objects of type T.

using	os::rtos::memory::out_of_memory_handler_t = void(*)(void)
	Type of out of memory handler.

template<typename T , typename U = T>
using	os::rtos::memory::unique_ptr = std::unique_ptr< T, allocator_deleter< allocator_typed< T, U > > >
	Type of a RTOS unique pointer to objects of type T.

Functions
template<typename T , typename A , typename ... Args>
auto	os::rtos::memory::allocate_unique (const A &allocator, Args &&... args)
	Function template to allocate a unique pointer.

new_handler	std::get_new_handler () noexcept
	Get the current handler.

template<typename T , typename ... Args>
std::enable_if<!std::is_array< T >::value, std::shared_ptr< T > >::type	os::rtos::make_shared (Args &&... args)
	Create an object that is owned by a `shared_ptr` and is allocated using the RTOS system allocator.

template<typename T1 , typename T2 , typename L , F get_resource>
bool	os::rtos::memory::operator!= (const allocator_stateless_polymorphic_synchronized< T1, L, get_resource > &lhs, const allocator_stateless_polymorphic_synchronized< T2, L, get_resource > &rhs) noexcept

template<typename T1 , typename T2 , typename L , F get_resource>
bool	os::rtos::memory::operator== (const allocator_stateless_polymorphic_synchronized< T1, L, get_resource > &lhs, const allocator_stateless_polymorphic_synchronized< T2, L, get_resource > &rhs) noexcept

new_handler	std::set_new_handler (new_handler handler) noexcept
	Establishes the function designated by handler as the current `new_handler`.

Variables
std::new_handler	anonymous_namespace{new.cpp}::new_handler_
	The current new handler.

const nothrow_t	std::nothrow

RTOS System Memory Functions
memory_resource *	os::rtos::memory::malloc_resource (void) noexcept
	Get the address of a memory manager based on POSIX `malloc()`.

memory_resource *	os::rtos::memory::set_default_resource (memory_resource *res) noexcept
	Set the default RTOS system memory manager.

memory_resource *	os::rtos::memory::get_default_resource (void) noexcept
	Get the default RTOS system memory manager.

void	os::rtos::memory::init_once_default_resource (void)

Operators
bool	os::rtos::memory::operator== (const memory_resource &lhs, const memory_resource &rhs) noexcept
	Compare the `memory_resource` instances for equality.

bool	os::rtos::memory::operator!= (const memory_resource &lhs, const memory_resource &rhs) noexcept
	Compare the `memory_resource` instances for inequality.

Type Specific Resource Managers
template<typename T >
memory_resource *	os::rtos::memory::set_resource_typed (memory_resource *res) noexcept
	Function template to set a memory resource.

template<typename T >
memory_resource *	os::rtos::memory::get_resource_typed (void) noexcept
	Function template to get a memory resource.

template<>
memory_resource *	os::rtos::memory::set_resource_typed< thread > (memory_resource *res) noexcept

template<>
memory_resource *	os::rtos::memory::get_resource_typed< thread > (void) noexcept

template<>
memory_resource *	os::rtos::memory::set_resource_typed< condition_variable > (memory_resource *res) noexcept

template<>
memory_resource *	os::rtos::memory::get_resource_typed< condition_variable > (void) noexcept

template<>
memory_resource *	os::rtos::memory::set_resource_typed< event_flags > (memory_resource *res) noexcept

template<>
memory_resource *	os::rtos::memory::get_resource_typed< event_flags > (void) noexcept

template<>
memory_resource *	os::rtos::memory::set_resource_typed< memory_pool > (memory_resource *res) noexcept

template<>
memory_resource *	os::rtos::memory::get_resource_typed< memory_pool > (void) noexcept

template<>
memory_resource *	os::rtos::memory::set_resource_typed< message_queue > (memory_resource *res) noexcept

template<>
memory_resource *	os::rtos::memory::get_resource_typed< message_queue > (void) noexcept

template<>
memory_resource *	os::rtos::memory::set_resource_typed< mutex > (memory_resource *res) noexcept

template<>
memory_resource *	os::rtos::memory::get_resource_typed< mutex > (void) noexcept

template<>
memory_resource *	os::rtos::memory::set_resource_typed< semaphore > (memory_resource *res) noexcept

template<>
memory_resource *	os::rtos::memory::get_resource_typed< semaphore > (void) noexcept

template<>
memory_resource *	os::rtos::memory::set_resource_typed< timer > (memory_resource *res) noexcept

template<>
memory_resource *	os::rtos::memory::get_resource_typed< timer > (void) noexcept

Standard operators
void *	operator new (std::size_t bytes)
	Allocate space for a new object instance.

Standard Memory Functions
memory_resource *	os::estd::pmr::new_delete_resource (void) noexcept
	Get the address of a memory manager based on `new/delete`.

memory_resource *	os::estd::pmr::null_memory_resource (void) noexcept
	Get the address of an ineffective memory manager.

memory_resource *	os::estd::pmr::set_default_resource (memory_resource *res) noexcept
	Set the default application memory manager.

memory_resource *	os::estd::pmr::get_default_resource (void) noexcept
	Get the default application memory manager.

Detailed Description

C++ API memory management definitions.

The µOS++ RTOS includes several advanced and flexible memory management features.

First, it defines a configurable memory manager for the application free store (also known as the "heap").

Second, it defines a separate memory manager to be used by the RTOS system objects. This separate manager can be configured to use any allocation policy. It may use either a statically or a dynamically allocated area.

The reason for the system memory manager is to allow RTOS system objects to be separated from application objects; this has several advantages:

it helps to protect the system objects from application bugs; this is beneficial during debug and it can improve reliability in the field.
it helps improve system performances, by allowing to locate the system objects on a fast, on-chip RAM, in case the platform has multiple RAM regions with different performances.

Third, system objects that require dynamic memory may be created with custom allocators, defined by the user.

Access to the application memory manager is done using the standard functions:

malloc()/free() in C (thread safe)
std::malloc()/std::free() in C++ (thread safe)
new/delete in C++ (thread safe)

The default application memory manager is set in the os_startup_initialize_free_store() function, called by the startup code when running on bare metal.

On synthetic POSIX platforms the default memory manager is os::memory::malloc_memory_resource, which uses memory from the system free store.

By default the RTOS system memory manager is the same as the application memory manager, but, for isolation reasons, it is recommended to define a separate memory mananger for the RTOS system objects.

The basic memory management class is os::rtos::memory::memory_resource, which will be standard starting with C++17. The µOS++ version of this class includes several extensions, like out of memory processing and statistics (and this is the reason the class is not defined in os::estd).

Typedef Documentation

◆ allocator

template<typename T >

using os::rtos::memory::allocator = typedef allocator_stateless_default_resource<T>

Type of allocator used by the system objects. Must be stateless.

Template Parameters

T	Type of elements to be allocated.

Definition at line 54 of file os-types.h.

◆ allocator_typed

template<typename T , typename U = T>

using os::rtos::memory::allocator_typed = typedef allocator_stateless_polymorphic_synchronized<T, scheduler::lockable, get_resource_typed<U> >

Type of an allocator for objects of type T.

Template Parameters

T	type of object.

The allocator uses scheduler critical sections to be thread safe, and the default memory resource associated with the given type.

Definition at line 1073 of file os-memory.h.

◆ out_of_memory_handler_t

using os::rtos::memory::out_of_memory_handler_t = typedef void (*)(void)

Type of out of memory handler.

Definition at line 142 of file os-memory.h.

◆ unique_ptr

template<typename T , typename U = T>

using os::rtos::memory::unique_ptr = typedef std::unique_ptr<T, allocator_deleter<allocator_typed<T, U> >>

Type of a RTOS unique pointer to objects of type T.

Template Parameters

T	type of object.

The type is based on the standard unique pointer, but with the specific RTOS deleter.

Definition at line 1084 of file os-memory.h.

Function Documentation

◆ allocate_unique()

template<typename T , typename A , typename ... Args>

auto os::rtos::memory::allocate_unique	(	const A &	allocator,
		Args &&...	args
	)

Function template to allocate a unique pointer.

Template Parameters

T	Type of object to be allocated.
A	Allocator type.
Args	Variable arguments list.

Parameters

allocator	Reference to allocator.
args	Arguments used to construct the object of type T.

Returns: A standard unique pointer with deleter.

◆ get_default_resource() [1/2]

memory_resource * os::estd::pmr::get_default_resource ( void )

inlinenoexcept

Get the default application memory manager.

Parameters: None.

Returns: Pointer to a memory manager object instance.

If not set explicitly by the user, this function will return an instance of malloc_memory_resource on bare metal platforms and of malloc_memory_resource on POSIX platforms.

Definition at line 184 of file memory_resource.

◆ get_default_resource() [2/2]

memory_resource * os::rtos::memory::get_default_resource ( void )

inlinenoexcept

Get the default RTOS system memory manager.

Parameters: None.

Returns: Pointer to a memory manager object instance.

If not set explicitly by the user, this function will return an instance of null_memory_resource on bare metal platforms and of malloc_memory_resource on POSIX platforms.

Definition at line 1133 of file os-memory.h.

◆ get_new_handler()

new_handler std::get_new_handler ( )

noexcept

Get the current handler.

Parameters: None.

Returns: Pointer to user function, or nullptr if not set.

The initial new_handler is a null pointer.

Definition at line 108 of file new.cpp.

◆ get_resource_typed()

template<typename T >

memory_resource * os::rtos::memory::get_resource_typed ( void )

noexcept

Function template to get a memory resource.

Returns: Pointer to current memory resource.

◆ get_resource_typed< condition_variable >()

template<>

memory_resource * os::rtos::memory::get_resource_typed< condition_variable > ( void )

inlinenoexcept

If not set explicitly by the user, this function will return an instance of null_memory_resource on bare metal platforms and of malloc_memory_resource on POSIX platforms.

Definition at line 1162 of file os-memory.h.

◆ get_resource_typed< event_flags >()

template<>

memory_resource * os::rtos::memory::get_resource_typed< event_flags > ( void )

inlinenoexcept

If not set explicitly by the user, this function will return an instance of null_memory_resource on bare metal platforms and of malloc_memory_resource on POSIX platforms.

Definition at line 1177 of file os-memory.h.

◆ get_resource_typed< memory_pool >()

template<>

memory_resource * os::rtos::memory::get_resource_typed< memory_pool > ( void )

inlinenoexcept

If not set explicitly by the user, this function will return an instance of null_memory_resource on bare metal platforms and of malloc_memory_resource on POSIX platforms.

Definition at line 1192 of file os-memory.h.

◆ get_resource_typed< message_queue >()

template<>

memory_resource * os::rtos::memory::get_resource_typed< message_queue > ( void )

inlinenoexcept

If not set explicitly by the user, this function will return an instance of null_memory_resource on bare metal platforms and of malloc_memory_resource on POSIX platforms.

Definition at line 1207 of file os-memory.h.

◆ get_resource_typed< mutex >()

template<>

memory_resource * os::rtos::memory::get_resource_typed< mutex > ( void )

inlinenoexcept

If not set explicitly by the user, this function will return an instance of null_memory_resource on bare metal platforms and of malloc_memory_resource on POSIX platforms.

Definition at line 1222 of file os-memory.h.

◆ get_resource_typed< semaphore >()

template<>

memory_resource * os::rtos::memory::get_resource_typed< semaphore > ( void )

inlinenoexcept

If not set explicitly by the user, this function will return an instance of null_memory_resource on bare metal platforms and of malloc_memory_resource on POSIX platforms.

Definition at line 1237 of file os-memory.h.

◆ get_resource_typed< thread >()

template<>

memory_resource * os::rtos::memory::get_resource_typed< thread > ( void )

inlinenoexcept

If not set explicitly by the user, this function will return an instance of null_memory_resource on bare metal platforms and of malloc_memory_resource on POSIX platforms.

Definition at line 1147 of file os-memory.h.

◆ get_resource_typed< timer >()

template<>

memory_resource * os::rtos::memory::get_resource_typed< timer > ( void )

inlinenoexcept

If not set explicitly by the user, this function will return an instance of null_memory_resource on bare metal platforms and of malloc_memory_resource on POSIX platforms.

Definition at line 1252 of file os-memory.h.

◆ init_once_default_resource()

void os::rtos::memory::init_once_default_resource ( void )

◆ make_shared()

template<typename T , typename ... Args>

std::enable_if<!std::is_array< T >::value, std::shared_ptr< T > >::type os::rtos::make_shared ( Args &&... args )

inline

Create an object that is owned by a shared_ptr and is allocated using the RTOS system allocator.

Parameters

args	Arguments for the T object's constructor.

Returns: A shared_ptr that owns the newly created object.

Exceptions

*	An exception may be thrown from `allocate()` or from the constructor of T.

Definition at line 176 of file os.h.

◆ malloc_resource()

memory_resource * os::rtos::memory::malloc_resource ( void )

noexcept

Get the address of a memory manager based on POSIX malloc().

Parameters: None.

Returns: Pointer to a memory manager object instance.

See also: malloc_memory_resource

Definition at line 189 of file os-memory.cpp.

◆ new_delete_resource()

memory_resource * os::estd::pmr::new_delete_resource ( void )

noexcept

Get the address of a memory manager based on new/delete.

Parameters: None.

Returns: Pointer to a memory manager object instance.

◆ null_memory_resource()

memory_resource * os::estd::pmr::null_memory_resource ( void )

noexcept

Get the address of an ineffective memory manager.

Parameters: None.

Returns: Pointer to a memory manager object instance.

◆ operator new()

void * operator new ( std::size_t bytes )

Allocate space for a new object instance.

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), or else throw a bad-alloc exception. This requirement is binding on a replacement version of this function.

Note: A C++ program may define a function with this function signature that displaces the default version defined by the C++ standard library.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 143 of file new.cpp.

◆ operator!=() [1/2]

template<typename T1 , typename T2 , typename L , F get_resource>

bool os::rtos::memory::operator!=	(	const allocator_stateless_polymorphic_synchronized< T1, L, get_resource > &	lhs,
		const allocator_stateless_polymorphic_synchronized< T2, L, get_resource > &	rhs
	)

noexcept

◆ operator!=() [2/2]

bool os::rtos::memory::operator!=	(	const memory_resource &	lhs,
		const memory_resource &	rhs
	)

inlinenoexcept

Compare the memory_resource instances for inequality.

Parameters

lhs	First instance to compare.
rhs	Second instance to compare.

Return values

true	The two object `memory_resource` instances are not equal.
false	The two object `memory_resource` instances are equal.

Definition at line 1468 of file os-memory.h.

◆ operator==() [1/2]

template<typename T1 , typename T2 , typename L , F get_resource>

bool os::rtos::memory::operator==	(	const allocator_stateless_polymorphic_synchronized< T1, L, get_resource > &	lhs,
		const allocator_stateless_polymorphic_synchronized< T2, L, get_resource > &	rhs
	)

noexcept

◆ operator==() [2/2]

bool os::rtos::memory::operator==	(	const memory_resource &	lhs,
		const memory_resource &	rhs
	)

inlinenoexcept

Compare the memory_resource instances for equality.

Parameters

lhs	First instance to compare.
rhs	Second instance to compare.

Return values

true	The two object `memory_resource` instances are equal.
false	The two object `memory_resource` instances are not equal.

Definition at line 1462 of file os-memory.h.

◆ set_default_resource() [1/2]

memory_resource * os::estd::pmr::set_default_resource ( memory_resource * res )

noexcept

Set the default application memory manager.

Parameters

res	Pointer to new memory manager object instance.

Returns: Pointer to previous memory manager object instance.

Definition at line 58 of file memory-resource.cpp.

◆ set_default_resource() [2/2]

memory_resource * os::rtos::memory::set_default_resource ( memory_resource * res )

noexcept

Set the default RTOS system memory manager.

Parameters

res	Pointer to new memory manager object instance.

Returns: Pointer to previous memory manager object instance.

On bare metal applications, this function is called from os_startup_initialize_free_store(), during the system startup, with a memory manager handling the free RAM.

Warning: This function is not thread safe.

Definition at line 206 of file os-memory.cpp.

◆ set_new_handler()

new_handler std::set_new_handler ( new_handler handler )

noexcept

Establishes the function designated by handler as the current new_handler.

Parameters

handler Pointer to user function.

Returns: The previous handler.

This handler is invoked when the standard operator new() detect an out of memory condition, to give a chance to the application process it properly. If the application can arrange for more memory to be used for allocation, this function should return and the allocation process is retried. If not, this function should gracefully shut down and restart.

The initial new_handler is a null pointer.

Definition at line 86 of file new.cpp.

◆ set_resource_typed()

template<typename T >

memory_resource * os::rtos::memory::set_resource_typed ( memory_resource * res )

noexcept

Function template to set a memory resource.

Parameters

res	Pointer to memory resource.

Returns: Pointer to previous memory resource.

◆ set_resource_typed< condition_variable >()

template<>

memory_resource * os::rtos::memory::set_resource_typed< condition_variable > ( memory_resource * res )

noexcept

On bare metal applications, this function is called from os_startup_initialize_free_store(), during the system startup, with a memory manager specific to this object type.

Definition at line 243 of file os-memory.cpp.

◆ set_resource_typed< event_flags >()

template<>

memory_resource * os::rtos::memory::set_resource_typed< event_flags > ( memory_resource * res )

noexcept

On bare metal applications, this function is called from os_startup_initialize_free_store(), during the system startup, with a memory manager specific to this object type.

Definition at line 261 of file os-memory.cpp.

◆ set_resource_typed< memory_pool >()

template<>

memory_resource * os::rtos::memory::set_resource_typed< memory_pool > ( memory_resource * res )

noexcept

On bare metal applications, this function is called from os_startup_initialize_free_store(), during the system startup, with a memory manager specific to this object type.

Definition at line 279 of file os-memory.cpp.

◆ set_resource_typed< message_queue >()

template<>

memory_resource * os::rtos::memory::set_resource_typed< message_queue > ( memory_resource * res )

noexcept

On bare metal applications, this function is called from os_startup_initialize_free_store(), during the system startup, with a memory manager specific to this object type.

Definition at line 297 of file os-memory.cpp.

◆ set_resource_typed< mutex >()

template<>

memory_resource * os::rtos::memory::set_resource_typed< mutex > ( memory_resource * res )

noexcept

On bare metal applications, this function is called from os_startup_initialize_free_store(), during the system startup, with a memory manager specific to this object type.

Definition at line 315 of file os-memory.cpp.

◆ set_resource_typed< semaphore >()

template<>

memory_resource * os::rtos::memory::set_resource_typed< semaphore > ( memory_resource * res )

noexcept

On bare metal applications, this function is called from os_startup_initialize_free_store(), during the system startup, with a memory manager specific to this object type.

Definition at line 333 of file os-memory.cpp.

◆ set_resource_typed< thread >()

template<>

memory_resource * os::rtos::memory::set_resource_typed< thread > ( memory_resource * res )

noexcept

On bare metal applications, this function is called from os_startup_initialize_free_store(), during the system startup, with a memory manager specific to this object type.

Definition at line 225 of file os-memory.cpp.

◆ set_resource_typed< timer >()

template<>

memory_resource * os::rtos::memory::set_resource_typed< timer > ( memory_resource * res )

noexcept

On bare metal applications, this function is called from os_startup_initialize_free_store(), during the system startup, with a memory manager specific to this object type.

Definition at line 351 of file os-memory.cpp.

Variable Documentation

◆ new_handler_

std::new_handler anonymous_namespace{new.cpp}::new_handler_

The current new handler.

The initial new_handler is a null pointer, initialised as part of the .bss section.

Definition at line 54 of file new.cpp.

◆ nothrow

const nothrow_t std::nothrow

Initial value:

= nothrow_t

{ }

Definition at line 66 of file new.cpp.

Namespaces

Classes

Typedefs

Functions

Variables

RTOS System Memory Functions

Operators

Type Specific Resource Managers

Standard operators

Standard Memory Functions

Detailed Description

Typedef Documentation

◆ allocator

◆ allocator_typed

◆ out_of_memory_handler_t

◆ unique_ptr

Function Documentation

◆ allocate_unique()

◆ get_default_resource() [1/2]

◆ get_default_resource() [2/2]

◆ get_new_handler()

◆ get_resource_typed()

◆ get_resource_typed< condition_variable >()

◆ get_resource_typed< event_flags >()

◆ get_resource_typed< memory_pool >()

◆ get_resource_typed< message_queue >()

◆ get_resource_typed< mutex >()

◆ get_resource_typed< semaphore >()

◆ get_resource_typed< thread >()

◆ get_resource_typed< timer >()

◆ init_once_default_resource()

◆ make_shared()

◆ malloc_resource()

◆ new_delete_resource()

◆ null_memory_resource()

◆ operator new()

◆ operator!=() [1/2]

◆ operator!=() [2/2]

◆ operator==() [1/2]

◆ operator==() [2/2]

◆ set_default_resource() [1/2]

◆ set_default_resource() [2/2]

◆ set_new_handler()

◆ set_resource_typed()

◆ set_resource_typed< condition_variable >()

◆ set_resource_typed< event_flags >()

◆ set_resource_typed< memory_pool >()

◆ set_resource_typed< message_queue >()

◆ set_resource_typed< mutex >()

◆ set_resource_typed< semaphore >()

◆ set_resource_typed< thread >()

◆ set_resource_typed< timer >()

Variable Documentation

◆ new_handler_

◆ nothrow