C++ API memory management definitions.
More...
|
| std |
| Standard std namespace.
|
|
|
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...
|
|
|
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. More...
|
|
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. More...
|
|
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 |
|
|
void * | operator new (std::size_t bytes) |
| Allocate space for a new object instance. More...
|
|
void * | operator new (std::size_t bytes, const std::nothrow_t ¬hrow) noexcept |
| Allocate space for a new object instance (nothrow). More...
|
|
void * | operator new[] (std::size_t bytes) |
| Allocate space for an array of new object instances. More...
|
|
void * | operator new[] (std::size_t bytes, const std::nothrow_t ¬hrow) noexcept |
| Allocate space for an array of new object instances (nothrow). More...
|
|
void | operator delete (void *ptr) noexcept |
| Deallocate the dynamically allocated object instance. More...
|
|
void | operator delete (void *ptr, std::size_t bytes) noexcept |
| Deallocate the dynamically allocated object instance. More...
|
|
void | operator delete (void *ptr, const std::nothrow_t ¬hrow) noexcept |
| Deallocate the dynamically allocated object instance (nothrow). More...
|
|
void | operator delete[] (void *ptr) noexcept |
| Deallocate the dynamically allocated array of object. More...
|
|
void | operator delete[] (void *ptr, std::size_t bytes) noexcept |
| Deallocate the dynamically allocated array of object. More...
|
|
void | operator delete[] (void *ptr, const std::nothrow_t ¬hrow) noexcept |
| Deallocate the dynamically allocated array of object (nothrow). More...
|
|
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
).
◆ allocator
Type of allocator used by the system objects. Must be stateless.
- Template Parameters
-
T | Type of elements to be allocated. |
Definition at line 57 of file os-types.h.
◆ allocator_typed
template<typename T , typename U = T>
Type of an allocator for objects of type T.
- Template Parameters
-
The allocator uses scheduler critical sections to be thread safe, and the default memory resource associated with the given type.
Definition at line 1065 of file os-memory.h.
◆ out_of_memory_handler_t
Type of out of memory handler.
Definition at line 142 of file os-memory.h.
◆ unique_ptr
template<typename T , typename U = T>
Type of a RTOS unique pointer to objects of type T.
- Template Parameters
-
The type is based on the standard unique pointer, but with the specific RTOS deleter.
Definition at line 1076 of file os-memory.h.
◆ 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.
This function is a factory of unique pointers. It is inspired by std::allocate_shared<>
.
Objects are allocated using the given allocator, and deallocated using a custom deleter associated to the allocator.
The returned unique pointers always have the deleter associated, so the object size is two pointers.
Standard allocator type definition.
Standard allocator traits definition.
Standard allocator type definition.
Standard allocator traits definition.
Definition at line 1686 of file os-memory.h.
◆ get_default_resource() [1/2]
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 191 of file memory_resource.
◆ get_default_resource() [2/2]
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 1125 of file os-memory.h.
◆ get_resource_typed()
Function template to get a memory resource.
- Returns
- Pointer to current memory resource.
◆ get_resource_typed< condition_variable >()
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 1155 of file os-memory.h.
◆ get_resource_typed< event_flags >()
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 1170 of file os-memory.h.
◆ get_resource_typed< memory_pool >()
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 1185 of file os-memory.h.
◆ get_resource_typed< message_queue >()
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 1200 of file os-memory.h.
◆ get_resource_typed< mutex >()
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 1215 of file os-memory.h.
◆ get_resource_typed< semaphore >()
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 1230 of file os-memory.h.
◆ get_resource_typed< thread >()
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 1140 of file os-memory.h.
◆ get_resource_typed< timer >()
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 1245 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 174 of file os.h.
◆ malloc_resource()
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 191 of file os-memory.cpp.
◆ new_delete_resource()
Get the address of a memory manager based on new/delete
.
- Parameters
- None.
- Returns
- Pointer to a memory manager object instance.
◆ null_memory_resource()
Get the address of an ineffective memory manager.
- Parameters
- None.
- Returns
- Pointer to a memory manager object instance.
◆ operator delete() [1/3]
void operator delete |
( |
void * |
ptr | ) |
|
|
noexcept |
Deallocate the dynamically allocated object instance.
- Parameters
-
- 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(os::std::size_t) or operator new(os::std::size_t,const std::nothrow_t&) 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.
- 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 325 of file new.cpp.
◆ operator delete() [2/3]
void operator delete |
( |
void * |
ptr, |
|
|
std::size_t |
bytes |
|
) |
| |
|
noexcept |
Deallocate the dynamically allocated object instance.
- 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.
- 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 376 of file new.cpp.
◆ operator delete() [3/3]
void operator delete |
( |
void * |
ptr, |
|
|
const std::nothrow_t & |
nothrow |
|
) |
| |
|
noexcept |
Deallocate the dynamically allocated object instance (nothrow).
- Parameters
-
ptr | Pointer to object. |
nothrow | |
- Returns
- Nothing.
The deallocation function (3.7.4.2) called by the implementation to render the value of ptr invalid when the constructor invoked from a nothrow placement version of the new-expression throws an exception.
- 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 416 of file new.cpp.
◆ operator delete[]() [1/3]
void operator delete[] |
( |
void * |
ptr | ) |
|
|
noexcept |
Deallocate the dynamically allocated array of object.
- Parameters
-
ptr | Pointer to array of objects. |
- 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.
- 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 455 of file new.cpp.
◆ operator delete[]() [2/3]
void operator delete[] |
( |
void * |
ptr, |
|
|
std::size_t |
bytes |
|
) |
| |
|
noexcept |
Deallocate the dynamically allocated array of object.
- 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.
- 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 487 of file new.cpp.
◆ operator delete[]() [3/3]
void operator delete[] |
( |
void * |
ptr, |
|
|
const std::nothrow_t & |
nothrow |
|
) |
| |
|
noexcept |
Deallocate the dynamically allocated array of object (nothrow).
- Parameters
-
ptr | Pointer to array of objects. |
nothrow | |
- Returns
- Nothing.
The deallocation function (3.7.4.2) called by the implementation to render the value of ptr invalid when the constructor invoked from a nothrow placement version of the array new-expression throws an exception.
If ptr is null, does nothing. Otherwise, reclaims the storage allocated by the earlier call to operator new.
- 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 517 of file new.cpp.
◆ operator new() [1/2]
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 148 of file new.cpp.
◆ operator new() [2/2]
void* operator new |
( |
std::size_t |
bytes, |
|
|
const std::nothrow_t & |
nothrow |
|
) |
| |
|
noexcept |
Allocate space for a new object instance (nothrow).
- Parameters
-
bytes | Number of bytes to allocate. |
nothrow | |
- Returns
- Pointer to allocated object.
Same as new(bytes)
, except that it is called when a C++ program prefers a null pointer result as an error indication, instead of a bad_alloc
exception.
Return a non-null pointer to suitably aligned storage (3.7.4), or else return a null pointer. This nothrow
version of operator new
returns a pointer obtained as if acquired from the (possibly replaced) ordinary version. 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 210 of file new.cpp.
◆ operator new[]() [1/2]
void* operator new[] |
( |
std::size_t |
bytes | ) |
|
Allocate space for an array of new object instances.
- Parameters
-
bytes | Number of bytes to allocate. |
- Returns
- Pointer to allocated object.
The allocation function (3.7.4.1) called by the array form of a new-expression (5.3.4) to allocate size bytes of storage suitably aligned to represent any array object of that size or smaller.
- 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 269 of file new.cpp.
◆ operator new[]() [2/2]
void* operator new[] |
( |
std::size_t |
bytes, |
|
|
const std::nothrow_t & |
nothrow |
|
) |
| |
|
noexcept |
Allocate space for an array of new object instances (nothrow).
- Parameters
-
bytes | Number of bytes to allocate. |
nothrow | |
- Returns
- Pointer to allocated object.
Same as new[](size), except that it is called by a C++ program that prefers a null pointer result as an error indication, instead of a bad_alloc
exception.
- 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 292 of file new.cpp.
◆ operator!=() [1/2]
Compare the memory_resource
instances for inequality.
- Parameters
-
lhs | First instance to compare. |
rhs | Second instance to compare. |
- Return values
-
Definition at line 1472 of file os-memory.h.
◆ operator!=() [2/2]
template<typename T1 , typename T2 , typename L , F get_resource>
◆ operator==() [1/2]
Compare the memory_resource
instances for equality.
- Parameters
-
lhs | First instance to compare. |
rhs | Second instance to compare. |
- Return values
-
Definition at line 1466 of file os-memory.h.
◆ operator==() [2/2]
template<typename T1 , typename T2 , typename L , F get_resource>
◆ set_default_resource() [1/2]
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 67 of file memory-resource.cpp.
◆ set_default_resource() [2/2]
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 208 of file os-memory.cpp.
◆ set_resource_typed()
Function template to set a memory resource.
- Parameters
-
res | Pointer to memory resource. |
- Returns
- Pointer to previous memory resource.
◆ 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 >()