µOS++ IIIe Reference  v6.3.15
“Perfekt ist nicht gut genug”
The third edition of µOS++, a POSIX inspired open source system, written in C++.
os::memory::first_fit_top_allocated< A > Class Template Reference

Memory resource implementing the first fit, top-down allocation policies, using a dynamically allocated arena. More...

#include <cmsis-plus/memory/first-fit-top.h>

Inherits os::memory::first_fit_top.

Public Types

using allocator_traits = std::allocator_traits< A >
 Standard allocator traits definition. More...
 
using allocator_type = A
 Standard allocator type definition. More...
 
using value_type = char
 Standard allocator type definition. More...
 

Public Member Functions

Constructors & Destructor
 first_fit_top_allocated (std::size_t bytes, const allocator_type &allocator=allocator_type())
 Construct a memory resource object instance. More...
 
 first_fit_top_allocated (const char *name, std::size_t bytes, const allocator_type &allocator=allocator_type())
 Construct a named memory resource object instance. More...
 
virtual ~first_fit_top_allocated ()
 Destruct the memory resource object instance. More...
 
Public Member Functions
void * allocate (std::size_t bytes, std::size_t alignment=max_align)
 Allocate a memory block. More...
 
void deallocate (void *addr, std::size_t bytes, std::size_t alignment=max_align) noexcept
 Deallocate the previously allocated memory block. More...
 
bool is_equal (memory_resource const &other) const noexcept
 Compare for equality with another memory_resource. More...
 
void reset (void) noexcept
 Reset the memory manager to the initial state. More...
 
bool coalesce (void) noexcept
 Coalesce free blocks. More...
 
std::size_t max_size (void) const noexcept
 Get the largest value that can be passed to allocate(). More...
 
out_of_memory_handler_t out_of_memory_handler (out_of_memory_handler_t handler)
 Set the out of memory handler. More...
 
out_of_memory_handler_t out_of_memory_handler (void)
 Get the out of memory handler. More...
 
std::size_t total_bytes (void)
 Get the total size of managed memory. More...
 
std::size_t allocated_bytes (void)
 Get the current size of all allocated chunks. More...
 
std::size_t max_allocated_bytes (void)
 Get the maximum allocated size. More...
 
std::size_t free_bytes (void)
 Get the current size of all free chunks. More...
 
std::size_t allocated_chunks (void)
 Get the current number of allocated chunks. More...
 
std::size_t free_chunks (void)
 Get the current number of free chunks. More...
 
std::size_t allocations (void)
 Get the number of allocations. More...
 
std::size_t deallocations (void)
 Get the number of deallocations. More...
 
void trace_print_statistics (void)
 Print a long message with usage statistics. More...
 
Public Member Functions
const char * name (void) const
 Get object name. More...
 

Static Public Attributes

static constexpr std::size_t max_align = alignof(std::max_align_t)
 The largest alignment for the platform. Also default when supplied alignment is not supported. More...
 

Protected Member Functions

Private Member Functions
void internal_construct_ (void *addr, std::size_t bytes)
 Internal function to construct the memory resource. More...
 
void internal_reset_ (void) noexcept
 Internal function to reset the memory resource. More...
 
void * internal_align_ (chunk_t *chunk, std::size_t bytes, std::size_t alignment)
 Internal function to align a chunk. More...
 
virtual void * do_allocate (std::size_t bytes, std::size_t alignment) override
 Implementation of the memory allocator. More...
 
virtual void do_deallocate (void *addr, std::size_t bytes, std::size_t alignment) noexcept override
 Implementation of the memory deallocator. More...
 
virtual std::size_t do_max_size (void) const noexcept override
 Implementation of the function to get max size. More...
 
virtual void do_reset (void) noexcept override
 Implementation of the function to reset the memory manager. More...
 
Private Member Functions
virtual bool do_is_equal (memory_resource const &other) const noexcept
 Implementation of the equality comparator. More...
 
virtual bool do_coalesce (void) noexcept
 Implementation of the function to coalesce free blocks. More...
 
void internal_increase_allocated_statistics (std::size_t bytes) noexcept
 Update statistics after allocation. More...
 
void internal_decrease_allocated_statistics (std::size_t bytes) noexcept
 Update statistics after deallocation. More...
 

Detailed Description

template<typename A = os::rtos::memory::allocator<char>>
class os::memory::first_fit_top_allocated< A >

Memory resource implementing the first fit, top-down allocation policies, using a dynamically allocated arena.

This class template is a convenience class that allocates an array of chars to be used as the allocation arena.

The common use case it to define dynamically allocated memory managers.

Definition at line 374 of file first-fit-top.h.

Types

◆ allocator_traits

template<typename A = os::rtos::memory::allocator<char>>
using os::memory::first_fit_top_allocated< A >::allocator_traits = std::allocator_traits<A>

Standard allocator traits definition.

Definition at line 391 of file first-fit-top.h.

◆ allocator_type

template<typename A = os::rtos::memory::allocator<char>>
using os::memory::first_fit_top_allocated< A >::allocator_type = A

Standard allocator type definition.

Definition at line 386 of file first-fit-top.h.

◆ value_type

template<typename A = os::rtos::memory::allocator<char>>
using os::memory::first_fit_top_allocated< A >::value_type = char

Standard allocator type definition.

Definition at line 381 of file first-fit-top.h.

Constructor & Destructor Documentation

◆ first_fit_top_allocated() [1/2]

template<typename A >
os::memory::first_fit_top_allocated< A >::first_fit_top_allocated ( std::size_t  bytes,
const allocator_type allocator = allocator_type () 
)
inline

Construct a memory resource object instance.

Parameters
[in]bytesThe size of the allocation arena.
[in]allocatorReference to allocator. Default a local temporary instance.

Definition at line 546 of file first-fit-top.h.

◆ first_fit_top_allocated() [2/2]

template<typename A >
os::memory::first_fit_top_allocated< A >::first_fit_top_allocated ( const char *  name,
std::size_t  bytes,
const allocator_type allocator = allocator_type () 
)

Construct a named memory resource object instance.

Parameters
[in]namePointer to name.
[in]bytesThe size of the allocation arena.
[in]allocatorReference to allocator. Default a local temporary instance.

Definition at line 554 of file first-fit-top.h.

◆ ~first_fit_top_allocated()

template<typename A >
os::memory::first_fit_top_allocated< A >::~first_fit_top_allocated ( )
virtual

Destruct the memory resource object instance.

Definition at line 575 of file first-fit-top.h.

Member Function Documentation

◆ allocate()

void * os::rtos::memory::memory_resource::allocate ( std::size_t  bytes,
std::size_t  alignment = max_align 
)
inlineinherited

Allocate a memory block.

Parameters
bytesNumber of bytes to allocate.
alignmentAlignment constraint (power of 2).
Returns
Pointer to newly allocated block, or nullptr.

Allocate storage with a size of at least bytes bytes. The returned storage is aligned to the specified alignment if such alignment is supported, and to alignof(std::max_align_t) otherwise.

If the storage of the requested size and alignment cannot be obtained:

  • if the out of memory handler is not set, return nullptr;
  • if the out of memory handler is set, call it and retry.

Equivalent to return do_allocate(bytes, alignment);.

Exceptions
The code itself throws nothing, but if the out of memory handler is set, it may throw a bad_alloc() exception.
See also
do_allocate();

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

◆ allocated_bytes()

std::size_t os::rtos::memory::memory_resource::allocated_bytes ( void  )
inlineinherited

Get the current size of all allocated chunks.

Parameters
None.
Returns
Number of bytes.

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

◆ allocated_chunks()

std::size_t os::rtos::memory::memory_resource::allocated_chunks ( void  )
inlineinherited

Get the current number of allocated chunks.

Parameters
None.
Returns
Number of chunks.

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

◆ allocations()

std::size_t os::rtos::memory::memory_resource::allocations ( void  )
inlineinherited

Get the number of allocations.

Parameters
None.
Returns
Number of allocations.

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

◆ coalesce()

bool os::rtos::memory::memory_resource::coalesce ( void  )
inlinenoexceptinherited

Coalesce free blocks.

Parameters
None.
Return values
trueif the operation freed more memory.
falseif the operation was ineffective.

In case the memory manager does not coalesce during deallocation, traverse the list of free blocks and coalesce.

Return true if the operation was successful and at least one larger block resulted.

See also
do_coalesce();

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

◆ deallocate()

void os::rtos::memory::memory_resource::deallocate ( void *  addr,
std::size_t  bytes,
std::size_t  alignment = max_align 
)
inlinenoexceptinherited

Deallocate the previously allocated memory block.

Parameters
addrAddress of the block to free.
bytesNumber of bytes to deallocate (may be 0 if unknown).
alignmentAlignment constraint (power of 2).
Returns
Nothing.

Deallocate the storage pointed to by addr. The address shall have been returned by a prior call to allocate() on a memory_resource that compares equal to *this, and the storage it points to shall not yet have been deallocated.

Equivalent to return do_deallocate(p, bytes, alignment);.

Exceptions
Throws nothing.
See also
do_deallocate();

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

◆ deallocations()

std::size_t os::rtos::memory::memory_resource::deallocations ( void  )
inlineinherited

Get the number of deallocations.

Parameters
None.
Returns
Number of deallocations

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

◆ do_allocate()

void * os::memory::first_fit_top::do_allocate ( std::size_t  bytes,
std::size_t  alignment 
)
overrideprotectedvirtualinherited

Implementation of the memory allocator.

Parameters
[in]bytesNumber of bytes to allocate.
[in]alignmentAlignment constraint (power of 2).
Returns
Pointer to newly allocated block, or nullptr.

The allocator tries to be fast and grasps the first block large enough, possibly splitting large blocks and increasing fragmentation. If the block is only slightly larger (the remaining space is not large enough for a minimum chunk) the block is not split, but left partly unused.

When large blocks are split, the top sub-block is returned; in other words, memory is allocated top-down. This speeds up deallocation for blocks allocated recently.

Exceptions
Throws nothing by itself, but the out of memory handler may throw bad_alloc().

Implements os::rtos::memory::memory_resource.

Reimplemented in os::memory::lifo.

Definition at line 130 of file first-fit-top.cpp.

◆ do_coalesce()

bool os::rtos::memory::memory_resource::do_coalesce ( void  )
protectedvirtualnoexceptinherited

Implementation of the function to coalesce free blocks.

Parameters
None.
Return values
trueif the operation resulted in larger blocks.
falseif the operation was ineffective.

The default implementation of this virtual function returns false, meaning the operation was ineffective.

Override this function to perform the action.

Standard compliance
Extension to standard.

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

◆ do_deallocate()

void os::memory::first_fit_top::do_deallocate ( void *  addr,
std::size_t  bytes,
std::size_t  alignment 
)
overrideprotectedvirtualnoexceptinherited

Implementation of the memory deallocator.

Parameters
[in]addrAddress of a previously allocated block to free.
[in]bytesNumber of bytes to deallocate (may be 0 if unknown).
[in]alignmentAlignment constraint (power of 2).
Returns
Nothing.

Deallocation is not guaranteed to be deterministic, but if done in strict reverse allocation order, it becomes deterministic, otherwise a traversal of the free list is required, the older the block, the more nodes to traverse (the free list is kept in ascending addresses order).

If the block is already in the free list, issue a trace message, but otherwise ignore the condition.

Exceptions
Throws nothing.

Implements os::rtos::memory::memory_resource.

Definition at line 243 of file first-fit-top.cpp.

◆ do_is_equal()

bool os::rtos::memory::memory_resource::do_is_equal ( memory_resource const &  other) const
protectedvirtualnoexceptinherited

Implementation of the equality comparator.

Parameters
otherReference to another memory_resource.
Return values
trueThe memory_resource objects are equal.
falseThe memory_resource objects are not equal.

Compares *this for equality with other. Two memory_resources compare equal if and only if memory allocated from one memory_resource can be deallocated from the other and vice versa.

The most-derived type of other may not match the most derived type of *this. A derived class implementation therefore must typically check whether the most derived types of *this and other match using dynamic_cast, and immediately return false if the cast fails.

Exceptions
Throws nothing.

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

◆ do_max_size()

std::size_t os::memory::first_fit_top::do_max_size ( void  ) const
overrideprotectedvirtualnoexceptinherited

Implementation of the function to get max size.

Parameters
None.
Returns
Integer with size in bytes, or 0 if unknown.

Reimplemented from os::rtos::memory::memory_resource.

Definition at line 403 of file first-fit-top.cpp.

◆ do_reset()

void os::memory::first_fit_top::do_reset ( void  )
overrideprotectedvirtualnoexceptinherited

Implementation of the function to reset the memory manager.

Parameters
None.
Returns
Nothing.

Reimplemented from os::rtos::memory::memory_resource.

Definition at line 100 of file first-fit-top.cpp.

◆ free_bytes()

std::size_t os::rtos::memory::memory_resource::free_bytes ( void  )
inlineinherited

Get the current size of all free chunks.

Parameters
None.
Returns
Number of bytes.

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

◆ free_chunks()

std::size_t os::rtos::memory::memory_resource::free_chunks ( void  )
inlineinherited

Get the current number of free chunks.

Parameters
None.
Returns
Number of chunks.

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

◆ internal_align_()

void * os::memory::first_fit_top::internal_align_ ( chunk_t *  chunk,
std::size_t  bytes,
std::size_t  alignment 
)
protectedinherited

Internal function to align a chunk.

Parameters
[in]chunkPointer to chunk.
[in]bytesBytes to allocate.
[in]alignmentPower of two.
Returns
Pointer to aligned payload.

Definition at line 412 of file first-fit-top.cpp.

◆ internal_construct_()

void os::memory::first_fit_top::internal_construct_ ( void *  addr,
std::size_t  bytes 
)
protectedinherited

Internal function to construct the memory resource.

Parameters
[in]addrBegin of allocator arena.
[in]bytesSize of allocator arena, in bytes.
Returns
Nothing.

Definition at line 52 of file first-fit-top.cpp.

◆ internal_decrease_allocated_statistics()

void os::rtos::memory::memory_resource::internal_decrease_allocated_statistics ( std::size_t  bytes)
protectednoexceptinherited

Update statistics after deallocation.

Parameters
[in]bytesNumber of deallocated bytes.
Returns
Nothing.

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

◆ internal_increase_allocated_statistics()

void os::rtos::memory::memory_resource::internal_increase_allocated_statistics ( std::size_t  bytes)
protectednoexceptinherited

Update statistics after allocation.

Parameters
[in]bytesNumber of allocated bytes.
Returns
Nothing.

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

◆ internal_reset_()

void os::memory::first_fit_top::internal_reset_ ( void  )
protectednoexceptinherited

Internal function to reset the memory resource.

Parameters
None.

Definition at line 77 of file first-fit-top.cpp.

◆ is_equal()

bool os::rtos::memory::memory_resource::is_equal ( memory_resource const &  other) const
inlinenoexceptinherited

Compare for equality with another memory_resource.

Parameters
otherReference to another memory_resource.
Return values
trueThe memory_resource objects are equal.
falseThe memory_resource objects are not equal.

Compare *this for equality with other. Two memory_resources compare equal if and only if memory allocated from one memory_resource can be deallocated from the other and vice versa.

Exceptions
Throws nothing.
See also
do_is_equal();

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

◆ max_allocated_bytes()

std::size_t os::rtos::memory::memory_resource::max_allocated_bytes ( void  )
inlineinherited

Get the maximum allocated size.

Parameters
None.
Returns
Number of bytes.

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

◆ max_size()

std::size_t os::rtos::memory::memory_resource::max_size ( void  ) const
inlinenoexceptinherited

Get the largest value that can be passed to allocate().

Parameters
None.
Returns
Number of bytes or 0 if unknown.
See also
do_max_size();

Definition at line 1337 of file os-memory.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 760 of file os-decls.h.

◆ out_of_memory_handler() [1/2]

out_of_memory_handler_t os::rtos::memory::memory_resource::out_of_memory_handler ( out_of_memory_handler_t  handler)
inlineinherited

Set the out of memory handler.

Parameters
handlerPointer to new handler.
Returns
Pointer to old handler.
Standard compliance
Extension to standard.

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

◆ out_of_memory_handler() [2/2]

out_of_memory_handler_t os::rtos::memory::memory_resource::out_of_memory_handler ( void  )
inlineinherited

Get the out of memory handler.

Parameters
None.
Returns
Pointer to existing handler.
Standard compliance
Extension to standard.

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

◆ reset()

void os::rtos::memory::memory_resource::reset ( void  )
inlinenoexceptinherited

Reset the memory manager to the initial state.

Parameters
None.
Returns
Nothing.
See also
do_reset();

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

◆ total_bytes()

std::size_t os::rtos::memory::memory_resource::total_bytes ( void  )
inlineinherited

Get the total size of managed memory.

Returns
Number of bytes.

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

◆ trace_print_statistics()

void os::rtos::memory::memory_resource::trace_print_statistics ( void  )
inlineinherited

Print a long message with usage statistics.

Parameters
None.
Returns
Nothing.

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

Member Data Documentation

◆ max_align

constexpr std::size_t os::rtos::memory::memory_resource::max_align = alignof(std::max_align_t)
staticinherited

The largest alignment for the platform. Also default when supplied alignment is not supported.

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


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