Synchronised memory pool, using the default RTOS allocator. More...

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

Inheritance diagram for os::rtos::memory_pool:

Classes
class	arena
	Storage for a memory pool. More...

class	attributes
	Memory pool attributes. More...

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.

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 (std::size_t blocks, std::size_t block_size_bytes, const attributes &attr=initializer, const allocator_type &allocator=allocator_type())
	Construct a memory pool object instance.

	memory_pool (const char *name, std::size_t blocks, std::size_t block_size_bytes, const attributes &attr=initializer, const allocator_type &allocator=allocator_type())
	Construct a named memory pool object instance.

virtual	~memory_pool ()
	Destruct the memory pool object instance.

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

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

void *	try_alloc (void)
	Try to allocate a memory block.

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

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 attributes	initializer
	Default memory pool initialiser.

static constexpr memory_pool::size_t	max_size = static_cast<memory_pool::size_t> (0 - 1)
	Maximum pool size.

Detailed Description

Manage a pool of same size blocks. Fast and deterministic allocation and deallocation behaviour, suitable for use even in ISRs.

Example

// Define the type of one pool block.
typedef struct {
  uint32_t length;
  uint32_t width;
  uint32_t height;
  uint32_t weight;
} properties_t;
 
// Define the pool size.
constexpr uint32_t pool_size = 10;
 
// Construct the pool object instance.
memory_pool mp { pool_size, sizeof(properties_t) };
 
void
func(void)
{
  // Do something
 
  void* buf;
 
  // Get one block from pool.
  buf = mp.alloc();
 
  // ... use the buffer
 
  // Free the buffer.
  mp.free(buf);
 
  // Do something else.
}

Note: There is no equivalent of calloc(); to initialise to zero a memory block, use:
block = mp.alloc();

memset (block, 0, mp.block_size ());

POSIX compatibility: No POSIX similar functionality identified. Current functionality inspired by ARM CMSIS, with extensions.

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

Member Typedef Documentation

◆ allocator_type

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

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

Constructor & Destructor Documentation

◆ memory_pool() [1/2]

os::rtos::memory_pool::memory_pool	(	std::size_t	blocks,
		std::size_t	block_size_bytes,
		const attributes &	attr = `initializer`,
		const allocator_type &	allocator = `allocator_type ()`
	)

Parameters

[in]	blocks	The maximum number of items in the pool.
[in]	block_size_bytes	The size of an item, in bytes.
[in]	attr	Reference to attributes.
[in]	allocator	Reference to allocator. Default a local temporary instance.

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.

If the attributes define a storage area (via mp_pool_address and mp_pool_size_bytes), that storage is used, otherwise the storage is dynamically allocated using the RTOS specific allocator (rtos::memory::allocator).

If the attr attributes are modified after the memory_pool creation, the memory_pool attributes shall not be affected.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 231 of file os-mempool.cpp.

        : memory_pool{ nullptr, blocks, block_size_bytes, attr, allocator }
    {
    }

◆ memory_pool() [2/2]

os::rtos::memory_pool::memory_pool	(	const char *	name,
		std::size_t	blocks,
		std::size_t	block_size_bytes,
		const attributes &	attr = `initializer`,
		const allocator_type &	allocator = `allocator_type ()`
	)

Parameters

[in]	name	Pointer to name.
[in]	blocks	The maximum number of items in the pool.
[in]	block_size_bytes	The size of an item, in bytes.
[in]	attr	Reference to attributes.
[in]	allocator	Reference to allocator. Default a local temporary instance.

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.

If the attributes define a storage area (via mp_pool_address and mp_pool_size_bytes), that storage is used, otherwise the storage is dynamically allocated using the RTOS specific allocator (rtos::memory::allocator).

If the attr attributes are modified after the memory_pool creation, the memory_pool attributes shall not be affected.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 266 of file os-mempool.cpp.

        : object_named_system{ name }
    {
#if defined(OS_TRACE_RTOS_MEMPOOL)
      trace::printf ("%s() @%p %s %u %u\n", __func__, this, this->name (),
                     blocks, block_size_bytes);
#endif
 
      if (attr.mp_pool_address != nullptr)
        {
          // Do not use any allocator at all.
          internal_construct_ (blocks, block_size_bytes, attr, nullptr, 0);
        }
      else
        {
          allocator_ = &allocator;
 
          // If no user storage was provided via attributes,
          // allocate it dynamically via the allocator.
          allocated_pool_size_elements_
              = (compute_allocated_size_bytes<
                     typename allocator_type::value_type> (blocks,
                                                           block_size_bytes)
                 + sizeof (typename allocator_type::value_type) - 1)
                / sizeof (typename allocator_type::value_type);
 
          allocated_pool_addr_
              = const_cast<allocator_type&> (allocator).allocate (
                  allocated_pool_size_elements_);
 
          internal_construct_ (
              blocks, block_size_bytes, attr, allocated_pool_addr_,
              allocated_pool_size_elements_
                  * sizeof (typename allocator_type::value_type));
        }
    }

References compute_allocated_size_bytes(), os::rtos::memory_pool::attributes::mp_pool_address, and os::trace::printf().

◆ ~memory_pool()

os::rtos::memory_pool::~memory_pool ( )

virtual

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.

If the storage for the memory pool was dynamically allocated, it is deallocated using the same allocator.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 400 of file os-mempool.cpp.

    {
#if defined(OS_TRACE_RTOS_MEMPOOL)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      // There must be no threads waiting for this pool.
      assert (list_.empty ());
 
      typedef typename std::allocator_traits<allocator_type>::pointer pointer;
 
      if (allocated_pool_addr_ != nullptr)
        {
          static_cast<allocator_type*> (const_cast<void*> (allocator_))
              ->deallocate (static_cast<pointer> (allocated_pool_addr_),
                            allocated_pool_size_elements_);
        }
    }

References os::rtos::memory::allocator_stateless_default_resource< T >::deallocate(), os::rtos::internal::object_named::name(), and os::trace::printf().

Member Function Documentation

◆ alloc()

void * os::rtos::memory_pool::alloc ( void )

Parameters: None.

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

The alloc() function shall allocate a fixed size memory block from the memory pool.

If the memory pool is empty, alloc() shall block until a block is freed or until alloc() is cancelled/interrupted. If more than one thread is waiting to allocate a block, when a block is freed and the Priority Scheduling option is supported, then the thread of highest priority that has been waiting the longest shall be selected to allocate the block. Otherwise, it is unspecified which waiting thread allocates the block.

This function uses a critical section to protect against simultaneous access from other threads or interrupts.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 510 of file os-mempool.cpp.

    {
#if defined(OS_TRACE_RTOS_MEMPOOL)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_throw (!interrupts::in_handler_mode (), EPERM);
      // Don't call this from critical regions.
      os_assert_throw (!scheduler::locked (), EPERM);
 
      void* p;
 
      // Extra test before entering the loop, with its inherent weight.
      // Trade size for speed.
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        p = internal_try_first_ ();
        if (p != nullptr)
          {
#if defined(OS_TRACE_RTOS_MEMPOOL)
            trace::printf ("%s()=%p @%p %s\n", __func__, p, this, name ());
#endif
            return p;
          }
        // ----- Exit critical section ----------------------------------------
      }
 
      thread& crt_thread = this_thread::thread ();
 
      // Prepare a list node pointing to the current thread.
      // Do not worry for being on stack, it is temporarily linked to the
      // list and guaranteed to be removed before this function returns.
      internal::waiting_thread_node node{ crt_thread };
 
      for (;;)
        {
          {
            // ----- Enter critical section -----------------------------------
            interrupts::critical_section ics;
 
            p = internal_try_first_ ();
            if (p != nullptr)
              {
#if defined(OS_TRACE_RTOS_MEMPOOL)
                trace::printf ("%s()=%p @%p %s\n", __func__, p, this, name ());
#endif
                return p;
              }
 
            // Add this thread to the memory pool waiting list.
            scheduler::internal_link_node (list_, node);
            // state::suspended set in above link().
            // ----- Exit critical section ------------------------------------
          }
 
          port::scheduler::reschedule ();
 
          // Remove the thread from the memory pool waiting list,
          // if not already removed by free().
          scheduler::internal_unlink_node (node);
 
          if (this_thread::thread ().interrupted ())
            {
#if defined(OS_TRACE_RTOS_MEMPOOL)
              trace::printf ("%s() INTR @%p %s\n", __func__, this, name ());
#endif
              return nullptr;
            }
        }
 
      /* NOTREACHED */
    }

References os::rtos::interrupts::in_handler_mode(), os::rtos::scheduler::locked(), os::rtos::internal::object_named::name(), os_assert_throw, os::trace::printf(), os::rtos::port::scheduler::reschedule(), and os::rtos::this_thread::thread().

Referenced by os::rtos::memory_pool_typed< T, Allocator >::alloc(), and os::rtos::memory_pool_inclusive< T, N >::alloc().

◆ block_size()

std::size_t os::rtos::memory_pool::block_size ( void ) const

inline

Parameters: None.

Returns: The block size, in bytes.

Note: Can be invoked from Interrupt Service Routines.

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

    {
      return block_size_bytes_;
    }

◆ capacity()

std::size_t os::rtos::memory_pool::capacity ( void ) const

inline

Parameters: None.

Returns: The max number of blocks in the pool.

Note: Can be invoked from Interrupt Service Routines.

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

    {
      return blocks_;
    }

Referenced by full().

◆ 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
	)

inlineconstexpr

Parameters

blocks	Number of blocks.
block_size_bytes	Size of block.

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

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

      {
        // Align each block
        return (blocks
                * ((block_size_bytes + (sizeof (T) - 1)) & ~(sizeof (T) - 1)));
      }

Referenced by memory_pool(), and os::rtos::memory_pool_allocated< Allocator >::memory_pool_allocated().

◆ count()

std::size_t os::rtos::memory_pool::count ( void ) const

inline

Parameters: None.

Returns: The number of blocks used from the queue.

Note: Can be invoked from Interrupt Service Routines.

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

    {
      return count_;
    }

Referenced by empty(), and full().

◆ empty()

bool os::rtos::memory_pool::empty ( void ) const

inline

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 941 of file os-mempool.h.

    {
      return (count () == 0);
    }

References count().

◆ free()

result_t os::rtos::memory_pool::free ( void * 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 781 of file os-mempool.cpp.

    {
#if defined(OS_TRACE_RTOS_MEMPOOL)
      trace::printf ("%s(%p) @%p %s\n", __func__, block, this, name ());
#endif
 
      // Don't call this from high priority interrupts.
      assert (port::interrupts::is_priority_valid ());
 
      // Validate pointer.
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
#endif
      if ((block < pool_addr_)
          || (block >= (static_cast<char*> (pool_addr_)
                        + blocks_ * block_size_bytes_)))
        {
#if defined(OS_TRACE_RTOS_MEMPOOL)
          trace::printf ("%s(%p) EINVAL @%p %s\n", __func__, block, this,
                         name ());
#endif
          return EINVAL;
        }
#pragma GCC diagnostic pop
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        // Perform a push_front() on the single linked LIFO list,
        // i.e. add the block to the beginning of the list.
 
        // Link previous list to this block; may be null, but it does
        // not matter.
        *(static_cast<void**> (block)) = first_;
 
        // Now this block is the first one.
        first_ = block;
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wdeprecated-volatile"
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wvolatile"
#endif
        --count_;
#pragma GCC diagnostic pop
 
        // ----- Exit critical section ----------------------------------------
      }
 
      // Wake-up one thread, if any.
      list_.resume_one ();
 
      return result::ok;
    }

References os::rtos::internal::object_named::name(), os::rtos::result::ok, and os::trace::printf().

Referenced by os::rtos::memory_pool_typed< T, Allocator >::free(), and os::rtos::memory_pool_inclusive< T, N >::free().

◆ full()

bool os::rtos::memory_pool::full ( void ) const

inline

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 950 of file os-mempool.h.

    {
      return (count () == capacity ());
    }

References capacity(), and count().

◆ name()

const char * os::rtos::internal::object_named::name ( void ) const

inlineinherited

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 753 of file os-decls.h.

      {
        return name_;
      }

◆ operator delete()

void os::rtos::internal::object_named_system::operator delete	(	void *	ptr,
		std::size_t	bytes
	)

inlinestaticinherited

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 120 of file os-inlines.h.

      {
        assert (!interrupts::in_handler_mode ());
 
        rtos::memory::allocator<char> ().deallocate (static_cast<char*> (ptr),
                                                     bytes);
      }

References os::rtos::memory::allocator_stateless_default_resource< T >::deallocate(), and os::rtos::interrupts::in_handler_mode().

◆ operator delete[]()

void os::rtos::internal::object_named_system::operator delete[]	(	void *	ptr,
		std::size_t	bytes
	)

inlinestaticinherited

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 141 of file os-inlines.h.

      {
        // Forward array deallocation to single element deallocation.
        operator delete (ptr, bytes);
      }

◆ operator new() [1/2]

void * os::rtos::internal::object_named_system::operator new ( std::size_t bytes )

inlinestaticinherited

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 43 of file os-inlines.h.

      {
        assert (!interrupts::in_handler_mode ());
 
        return rtos::memory::allocator<char> ().allocate (bytes);
      }

References os::rtos::memory::allocator_stateless_default_resource< T >::allocate(), and os::rtos::interrupts::in_handler_mode().

◆ operator new() [2/2]

void * os::rtos::internal::object_named_system::operator new	(	std::size_t	bytes,
		void *	ptr
	)

inlinestaticinherited

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 80 of file os-inlines.h.

      {
        return ptr;
      }

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

void * os::rtos::internal::object_named_system::operator new[] ( std::size_t bytes )

inlinestaticinherited

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 61 of file os-inlines.h.

      {
        // Forward array allocation to single element allocation.
        return operator new (bytes);
      }

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

void * os::rtos::internal::object_named_system::operator new[]	(	std::size_t	bytes,
		void *	ptr
	)

inlinestaticinherited

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 97 of file os-inlines.h.

      {
        // Forward array allocation to single element allocation.
        return operator new (bytes, ptr);
      }

◆ operator==()

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

inline

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 905 of file os-mempool.h.

    {
      return this == &rhs;
    }

◆ pool()

void * os::rtos::memory_pool::pool ( void )

inline

Parameters: None.

Returns: Pointer to storage.

Note: Can be invoked from Interrupt Service Routines.

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

    {
      return pool_addr_;
    }

◆ reset()

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

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 846 of file os-mempool.cpp.

    {
#if defined(OS_TRACE_RTOS_MEMPOOL)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        internal_init_ ();
        // ----- Exit critical section ----------------------------------------
      }
 
      // Wake-up all threads, if any.
      // Need not be inside the critical section,
      // the list is protected by inner `resume_one()`.
      list_.resume_all ();
 
      return result::ok;
    }

References os::rtos::interrupts::in_handler_mode(), os::rtos::internal::object_named::name(), os::rtos::result::ok, os_assert_err, and os::trace::printf().

◆ timed_alloc()

void * os::rtos::memory_pool::timed_alloc ( clock::duration_t timeout )

Parameters

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

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

The timed_alloc() function shall allocate a fixed size memory block from the memory pool.

If the memory pool is empty, timed_alloc() shall block until a block is freed or until timed_alloc() is cancelled/interrupted. If more than one thread is waiting to allocate a block, when a block is freed and the Priority Scheduling option is supported, then the thread of highest priority that has been waiting the longest shall be selected to allocate the block. Otherwise, it is unspecified which waiting thread allocates the block.

The timed_alloc() function shall allocate any of the available blocks, regardless of their age and the order they were freed. However, if no blocks are available, the wait for such a block shall be terminated when the specified timeout expires.

The timeout shall expire after the number of time units (that is when the value of that clock equals or exceeds (now()+duration). The resolution of the timeout shall be the resolution of the clock on which it is based.

Under no circumstance shall the operation fail with a timeout if a block can be allocated from the memory pool immediately. The validity of the timeout need not be checked if the block can be allocated immediately.

The clock used for timeouts can be specified via the clock attribute. By default, the clock derived from the scheduler timer is used, and the durations are expressed in ticks.

This function uses a critical section to protect against simultaneous access from other threads or interrupts.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 669 of file os-mempool.cpp.

    {
#if defined(OS_TRACE_RTOS_MEMPOOL)
#pragma GCC diagnostic push
#if defined(__clang__)
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wuseless-cast"
#endif
      trace::printf ("%s(%u) @%p %s\n", __func__,
                     static_cast<unsigned int> (timeout), this, name ());
#pragma GCC diagnostic pop
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_throw (!interrupts::in_handler_mode (), EPERM);
      // Don't call this from critical regions.
      os_assert_throw (!scheduler::locked (), EPERM);
 
      void* p;
 
      // Extra test before entering the loop, with its inherent weight.
      // Trade size for speed.
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        p = internal_try_first_ ();
        if (p != nullptr)
          {
#if defined(OS_TRACE_RTOS_MEMPOOL)
            trace::printf ("%s()=%p @%p %s\n", __func__, p, this, name ());
#endif
            return p;
          }
        // ----- Exit critical section ----------------------------------------
      }
 
      thread& crt_thread = this_thread::thread ();
 
      // Prepare a list node pointing to the current thread.
      // Do not worry for being on stack, it is temporarily linked to the
      // list and guaranteed to be removed before this function returns.
      internal::waiting_thread_node node{ crt_thread };
 
      internal::clock_timestamps_list& clock_list = clock_->steady_list ();
      clock::timestamp_t timeout_timestamp = clock_->steady_now () + timeout;
 
      // Prepare a timeout node pointing to the current thread.
      internal::timeout_thread_node timeout_node{ timeout_timestamp,
                                                  crt_thread };
 
      for (;;)
        {
          {
            // ----- Enter critical section -----------------------------------
            interrupts::critical_section ics;
 
            p = internal_try_first_ ();
            if (p != nullptr)
              {
#if defined(OS_TRACE_RTOS_MEMPOOL)
                trace::printf ("%s()=%p @%p %s\n", __func__, p, this, name ());
#endif
                return p;
              }
 
            // Add this thread to the memory pool waiting list,
            // and the clock timeout list.
            scheduler::internal_link_node (list_, node, clock_list,
                                           timeout_node);
            // state::suspended set in above link().
            // ----- Exit critical section ------------------------------------
          }
 
          port::scheduler::reschedule ();
 
          // Remove the thread from the memory pool waiting list,
          // if not already removed by free() and from the clock
          // timeout list, if not already removed by the timer.
          scheduler::internal_unlink_node (node, timeout_node);
 
          if (this_thread::thread ().interrupted ())
            {
#if defined(OS_TRACE_RTOS_MEMPOOL)
              trace::printf ("%s() INTR @%p %s\n", __func__, this, name ());
#endif
              return nullptr;
            }
 
          if (clock_->steady_now () >= timeout_timestamp)
            {
#if defined(OS_TRACE_RTOS_MEMPOOL)
              trace::printf ("%s() TMO @%p %s\n", __func__, this, name ());
#endif
              return nullptr;
            }
        }
 
      /* NOTREACHED */
    }

References os::rtos::interrupts::in_handler_mode(), os::rtos::scheduler::locked(), os::rtos::internal::object_named::name(), os_assert_throw, os::trace::printf(), os::rtos::port::scheduler::reschedule(), and os::rtos::this_thread::thread().

Referenced by os::rtos::memory_pool_typed< T, Allocator >::timed_alloc(), and os::rtos::memory_pool_inclusive< T, N >::timed_alloc().

◆ try_alloc()

void * os::rtos::memory_pool::try_alloc ( void )

Parameters: None.

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

Try to allocate a fixed size memory block from the memory pool, if available, return it, otherwise return nullptr.

The timed_alloc() function shall try to allocate a fixed size memory block from the memory pool.

If the memory pool is empty, timed_alloc() shall immediately return 'nullptr'.

This function uses a critical section to protect against simultaneous access from other threads or interrupts.

Note: Can be invoked from Interrupt Service Routines.

Definition at line 604 of file os-mempool.cpp.

    {
#if defined(OS_TRACE_RTOS_MEMPOOL)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      // Don't call this from high priority interrupts.
      assert (port::interrupts::is_priority_valid ());
 
      void* p;
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        p = internal_try_first_ ();
        // ----- Exit critical section ----------------------------------------
      }
 
#if defined(OS_TRACE_RTOS_MEMPOOL)
      trace::printf ("%s()=%p @%p %s\n", __func__, p, this, name ());
#endif
      return p;
    }

References os::rtos::internal::object_named::name(), and os::trace::printf().

Referenced by os::rtos::memory_pool_typed< T, Allocator >::try_alloc(), and os::rtos::memory_pool_inclusive< T, N >::try_alloc().

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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ allocator_type

Constructor & Destructor Documentation

◆ memory_pool() [1/2]

◆ memory_pool() [2/2]

◆ ~memory_pool()

Member Function Documentation

◆ alloc()

◆ block_size()

◆ capacity()

◆ compute_allocated_size_bytes()

◆ count()

◆ empty()

◆ free()

◆ 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()