Memory resource implementing the LIFO allocation/deallocation policies, using an existing arena. More...

#include <cmsis-plus/memory/lifo.h>

Inheritance diagram for os::memory::lifo:

Public Member Functions
Public Member Functions
void *	allocate (std::size_t bytes, std::size_t alignment=max_align)
	Allocate a memory block.

void	deallocate (void *addr, std::size_t bytes, std::size_t alignment=max_align) noexcept
	Deallocate the previously allocated memory block.

bool	is_equal (memory_resource const &other) const noexcept
	Compare for equality with another `memory_resource`.

void	reset (void) noexcept
	Reset the memory manager to the initial state.

bool	coalesce (void) noexcept
	Coalesce free blocks.

std::size_t	max_size (void) const noexcept
	Get the largest value that can be passed to `allocate()`.

out_of_memory_handler_t	out_of_memory_handler (out_of_memory_handler_t handler)
	Set the out of memory handler.

out_of_memory_handler_t	out_of_memory_handler (void)
	Get the out of memory handler.

std::size_t	total_bytes (void)
	Get the total size of managed memory.

std::size_t	allocated_bytes (void)
	Get the current size of all allocated chunks.

std::size_t	max_allocated_bytes (void)
	Get the maximum allocated size.

std::size_t	free_bytes (void)
	Get the current size of all free chunks.

std::size_t	allocated_chunks (void)
	Get the current number of allocated chunks.

std::size_t	free_chunks (void)
	Get the current number of free chunks.

std::size_t	allocations (void)
	Get the number of allocations.

std::size_t	deallocations (void)
	Get the number of deallocations.

void	trace_print_statistics (void)
	Print a long message with usage statistics.

Public Member Functions
const char *	name (void) const
	Get object name.

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.

Protected Member Functions
Private Member Functions
virtual void *	do_allocate (std::size_t bytes, std::size_t alignment) override
	Implementation of the memory allocator.

Private Member Functions
void	internal_construct_ (void *addr, std::size_t bytes)
	Internal function to construct the memory resource.

void	internal_reset_ (void) noexcept
	Internal function to reset the memory resource.

void *	internal_align_ (chunk_t *chunk, std::size_t bytes, std::size_t alignment)
	Internal function to align a chunk.

virtual void	do_deallocate (void *addr, std::size_t bytes, std::size_t alignment) noexcept override
	Implementation of the memory deallocator.

virtual std::size_t	do_max_size (void) const noexcept override
	Implementation of the function to get max size.

virtual void	do_reset (void) noexcept override
	Implementation of the function to reset the memory manager.

Private Member Functions
virtual bool	do_is_equal (memory_resource const &other) const noexcept
	Implementation of the equality comparator.

virtual bool	do_coalesce (void) noexcept
	Implementation of the function to coalesce free blocks.

void	internal_increase_allocated_statistics (std::size_t bytes) noexcept
	Update statistics after allocation.

void	internal_decrease_allocated_statistics (std::size_t bytes) noexcept
	Update statistics after deallocation.

Constructors & Destructor
	lifo (void *addr, std::size_t bytes)
	Construct a memory resource object instance.

	lifo (const char name, void addr, std::size_t bytes)
	Construct a named memory resource object instance.

virtual	~lifo () override
	Destruct the memory resource object instance.

	lifo ()=default
	Default constructor. Construct a memory resource object instance.

	lifo (const char *name)
	Construct a named memory resource object instance.

Detailed Description

Memory resource implementing the LIFO allocation/deallocation policies, using an existing arena.

This memory manager is a variant of first_fit_top that guarantees a deterministic, fragmentation free, allocation.

Deallocation is guaranteed to be deterministic only when deallocating the last allocated block (strict LIFO policy).

However this class does not enforce the strict LIFO policy, deallocating older block is allowed, but generally it is no longer deterministic, since a traversal of the free list is required. On the other side, with block always allocated from top to down, and the free list ordered, deallocating older block is predictable if the age of the block is known, in other words deallocating the last allocated block inserts it after the head block, deallocating the second last allocated block inserts it before the second element in the list, and generally deallocating the n-th last allocated block inserts it somewhere up to the n-th element in the free list, possibly sooner, so the behaviour is somehow deterministic.

This memory manager is ideal for one-time allocations of objects during startup, objects to be kept alive for the entire life span of the application. It is also ideal for pools of objects, that are later created and destroyed on an as-needed basis.

Definition at line 88 of file lifo.h.

Constructor & Destructor Documentation

◆ lifo() [1/4]

os::memory::lifo::lifo	(	void *	addr,
		std::size_t	bytes
	)

inline

Construct a memory resource object instance.

Parameters

[in]	addr	Begin of allocator arena.
[in]	bytes	Size of allocator arena, in bytes.

Definition at line 390 of file lifo.h.

◆ lifo() [2/4]

os::memory::lifo::lifo	(	const char *	name,
		void *	addr,
		std::size_t	bytes
	)

inline

Construct a named memory resource object instance.

Parameters

[in]	name	Pointer to name.
[in]	addr	Begin of allocator arena.
[in]	bytes	Size of allocator arena, in bytes.

Definition at line 399 of file lifo.h.

◆ lifo() [3/4]

os::memory::lifo::lifo ( )

protecteddefault

Default constructor. Construct a memory resource object instance.

◆ lifo() [4/4]

os::memory::lifo::lifo ( const char * name )

protected

Construct a named memory resource object instance.

Parameters

[in] name Pointer to name.

◆ ~lifo()

os::memory::lifo::~lifo ( )

overridevirtual

Destruct the memory resource object instance.

Definition at line 46 of file lifo.cpp.

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

bytes	Number of bytes to allocate.
alignment	Alignment 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 1294 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 1406 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 1424 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 1436 of file os-memory.h.

◆ coalesce()

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

inlinenoexceptinherited

Coalesce free blocks.

Parameters: None.

Return values

true	if the operation freed more memory.
false	if 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 1369 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

addr	Address of the block to free.
bytes	Number of bytes to deallocate (may be 0 if unknown).
alignment	Alignment 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 1316 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 1442 of file os-memory.h.

◆ do_allocate()

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

overrideprotectedvirtual

Implementation of the memory allocator.

Parameters

[in]	bytes	Number of bytes to allocate.
[in]	alignment	Alignment constraint (power of 2).

Returns: Pointer to newly allocated block, or nullptr.

The allocator is deterministic and fast, it always uses the top part of the first block (memory is allocated top-down). If this block is not large enough, the allocation fails; the free list is never traversed, since this is no longer deterministic.

Deallocating in reverse order restores the first block to its original glory. A slight reorder of deallocations is allowed, but memory is not reused until the previous adjacent block is freed, and so on recursively, increasing back the size of the first block.

With the given top-down allocation policy, recent block have always lower addresses.

Similarly, a block is reused only after all more recently allocated blocks are freed.

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

Reimplemented from os::memory::first_fit_top.

Definition at line 80 of file lifo.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

true	if the operation resulted in larger blocks.
false	if 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 471 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]	addr	Address of a previously allocated block to free.
[in]	bytes	Number of bytes to deallocate (may be 0 if unknown).
[in]	alignment	Alignment 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 236 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

other Reference to another memory_resource.

Return values

true	The `memory_resource` objects are equal.
false	The `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 423 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 393 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 94 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 1418 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 1430 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]	chunk	Pointer to chunk.
[in]	bytes	Bytes to allocate.
[in]	alignment	Power of two.

Returns: Pointer to aligned payload.

Definition at line 399 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]	addr	Begin of allocator arena.
[in]	bytes	Size 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] bytes Number of deallocated bytes.

Returns: Nothing.

Definition at line 493 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] bytes Number of allocated bytes.

Returns: Nothing.

Definition at line 477 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 74 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

other Reference to another memory_resource.

Return values

true	The `memory_resource` objects are equal.
false	The `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 1335 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 1412 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 1344 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 774 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

handler Pointer to new handler.

Returns: Pointer to old handler.

Standard compliance: Extension to standard.

Definition at line 1379 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 1394 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 1353 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 1400 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 1448 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)

staticconstexprinherited

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

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

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

Public Member Functions

Static Public Attributes

Protected Member Functions

Constructors & Destructor

Detailed Description

Constructor & Destructor Documentation

◆ lifo() [1/4]

◆ lifo() [2/4]

◆ lifo() [3/4]

◆ lifo() [4/4]

◆ ~lifo()

Member Function Documentation

◆ allocate()

◆ allocated_bytes()

◆ allocated_chunks()

◆ allocations()

◆ coalesce()

◆ deallocate()

◆ deallocations()

◆ do_allocate()

◆ do_coalesce()

◆ do_deallocate()

◆ do_is_equal()

◆ do_max_size()

◆ do_reset()

◆ free_bytes()

◆ free_chunks()

◆ internal_align_()

◆ internal_construct_()

◆ internal_decrease_allocated_statistics()

◆ internal_increase_allocated_statistics()

◆ internal_reset_()

◆ is_equal()

◆ max_allocated_bytes()

◆ max_size()

◆ name()

◆ out_of_memory_handler() [1/2]

◆ out_of_memory_handler() [2/2]

◆ reset()

◆ total_bytes()

◆ trace_print_statistics()

Member Data Documentation

◆ max_align