Memory pools

C API memory pool definitions. More...

Classes
struct	os_mempool_attr_s
	Memory pool attributes. More...
struct	os_mempool_s
	Memory pool object storage. More...

Typedefs
typedef struct os_mempool_attr_s	os_mempool_attr_t
	Memory pool attributes.
typedef struct os_mempool_s	os_mempool_t
	Memory pool object storage.

Memory Pool Attributes Functions
void	os_mempool_attr_init (os_mempool_attr_t *attr)
	Initialise the memory pool attributes.

Memory Pool Creation Functions
void	os_mempool_construct (os_mempool_t *mempool, const char *name, size_t blocks, size_t block_size_bytes, const os_mempool_attr_t *attr)
	Construct a statically allocated memory pool object instance.
void	os_mempool_destruct (os_mempool_t *mempool)
	Destruct the statically allocated memory pool object instance.
os_mempool_t *	os_mempool_new (const char *name, size_t blocks, size_t block_size_bytes, const os_mempool_attr_t *attr)
	Allocate a memory pool object instance and construct it.
void	os_mempool_delete (os_mempool_t *mempool)
	Destruct the memory pool object instance and deallocate it.

Memory Pool Functions
const char *	os_mempool_get_name (os_mempool_t *mempool)
	Get the memory pool name.
void *	os_mempool_alloc (os_mempool_t *mempool)
	Allocate a memory block.
void *	os_mempool_try_alloc (os_mempool_t *mempool)
	Try to allocate a memory block.
void *	os_mempool_timed_alloc (os_mempool_t *mempool, os_clock_duration_t timeout)
	Allocate a memory block with timeout.
os_result_t	os_mempool_free (os_mempool_t *mempool, void *block)
	Free the memory block.
size_t	os_mempool_get_capacity (os_mempool_t *mempool)
	Get memory pool capacity.
size_t	os_mempool_get_count (os_mempool_t *mempool)
	Get blocks count.
size_t	os_mempool_get_block_size (os_mempool_t *mempool)
	Get block size.
bool	os_mempool_is_empty (os_mempool_t *mempool)
	Check if the memory pool is empty.
bool	os_mempool_is_full (os_mempool_t *mempool)
	Check if the memory pool is full.
os_result_t	os_mempool_reset (os_mempool_t *mempool)
	Reset the memory pool.
void *	os_mempool_get_pool (os_mempool_t *mempool)
	Get the pool storage address.

Compatibility Macros
#define	os_mempool_create   os_mempool_construct
#define	os_mempool_destroy   os_mempool_destruct

Detailed Description

For the complete definition, see

RTOS C++ API

Examples

typedef struct my_blk_s
{
  int i;
  const char* s;
} my_blk_t;
 
int
os_main (int argc, char* argv[])
{
  my_blk_t* blk;
 
    {
      // Simple pool, dynamically allocated.
      os_mempool_t p1;
      os_mempool_construct (&p1, "p1", 3, sizeof(my_blk_t), NULL);
 
      blk = os_mempool_alloc (&p1);
      os_mempool_free (&p1, blk);
 
      blk = os_mempool_try_alloc (&p1);
      os_mempool_free (&p1, blk);
 
      blk = os_mempool_timed_alloc (&p1, 1);
      os_mempool_free (&p1, blk);
 
      os_mempool_destruct (&p1);
    }
 
    {
      // Static pool.
      static char pool[1000];
 
      os_mempool_attr_t ap2;
      os_mempool_attr_init (&ap2);
      ap2.mp_pool_address = pool;
      ap2.mp_pool_size_bytes = sizeof(pool);
      ap2.clock = os_clock_get_rtclock ();
 
      os_mempool_t p2;
      os_mempool_construct (&p2, "p2", 3, sizeof(my_blk_t), &ap2);
 
      blk = os_mempool_alloc (&p2);
 
      os_mempool_free (&p2, blk);
 
      os_mempool_reset (&p2);
 
      os_mempool_destruct (&p2);
    }
}

Macro Definition Documentation

os_mempool_create

#define os_mempool_create   os_mempool_construct

Definition at line 2133 of file os-c-api.h.

os_mempool_destroy

#define os_mempool_destroy   os_mempool_destruct

Definition at line 2134 of file os-c-api.h.

Typedef Documentation

os_mempool_attr_t

typedef struct os_mempool_attr_s os_mempool_attr_t

Initialise this structure with os_mempool_attr_init() and then set any of the individual members directly.

See also

os::rtos::memory_pool::attributes

os_mempool_t

typedef struct os_mempool_s os_mempool_t

This C structure has the same size as the C++ os::rtos::memory_pool object and must be initialised with os_mempool_create().

Later on a pointer to it can be used both in C and C++ to refer to the memory pool object instance.

The members of this structure are hidden and should not be used directly, but only through specific functions.

See also

os::rtos::memory_pool

Function Documentation

os_mempool_alloc()

void * os_mempool_alloc

(

os_mempool_t *

mempool

)

Parameters

[in]

mempool

Pointer to memory pool object instance.

Returns

Pointer to memory block, or NULL if interrupted.

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool::alloc()

Definition at line 2576 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  return (reinterpret_cast<memory_pool&> (*mempool)).alloc ();
}

os_mempool_attr_init()

void os_mempool_attr_init

(

os_mempool_attr_t *

attr

)

Parameters

[in]

attr

Pointer to memory pool attributes object instance.

Returns

Nothing.

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool::attributes

Definition at line 2469 of file os-c-wrapper.cpp.

{
  assert (attr != nullptr);
  new (attr) memory_pool::attributes ();
}

os_mempool_construct()

void os_mempool_construct	(	os_mempool_t *	mempool,
		const char *	name,
		size_t	blocks,
		size_t	block_size_bytes,
		const os_mempool_attr_t *	attr
	)

Parameters

[in]	mempool	Pointer to memory pool object instance storage.
[in]	name	Pointer to name (may be NULL).
[in]	blocks	The maximum number of items in the pool.
[in]	block_size_bytes	The size of an item, in bytes.
[in]	attr	Pointer to attributes (may be NULL).

Returns

Nothing.

Note

Must be paired with os_mempool_destruct().

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool

Definition at line 2484 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  if (attr == nullptr)
    {
      attr = (const os_mempool_attr_t*)&memory_pool::initializer;
    }
  new (mempool) memory_pool (name, blocks, block_size_bytes,
                             (const memory_pool::attributes&)*attr);
}

References os::rtos::memory_pool::initializer.

os_mempool_delete()

void os_mempool_delete

(

os_mempool_t *

mempool

)

Parameters

[in]

mempool

Pointer to dynamically allocated memory pool object instance.

Returns

Nothing.

Destruct the memory pool and deallocate the dynamically allocated space using the RTOS system allocator.

Note

Equivalent of C++ delete ptr_mempool.

Must be paired with os_mempool_new().

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool

Definition at line 2550 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  delete reinterpret_cast<memory_pool*> (mempool);
}

os_mempool_destruct()

void os_mempool_destruct

(

os_mempool_t *

mempool

)

Parameters

[in]

mempool

Pointer to memory pool object instance.

Returns

Nothing.

Note

Must be paired with os_mempool_construct().

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool

Definition at line 2505 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  (reinterpret_cast<memory_pool&> (*mempool)).~memory_pool ();
}

os_mempool_free()

os_result_t os_mempool_free	(	os_mempool_t *	mempool,
		void *	block
	)

Parameters

[in]	mempool	Pointer to memory pool object instance.
[in]	block	Pointer to memory block to free.

Return values

os_ok	The memory block was released.
EINVAL	The block does not belong to the memory pool.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool::free()

Definition at line 2615 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  return (os_result_t)(reinterpret_cast<memory_pool&> (*mempool)).free (block);
}

References free().

os_mempool_get_block_size()

size_t os_mempool_get_block_size

(

os_mempool_t *

mempool

)

Parameters

[in]

mempool

Pointer to memory pool object instance.

Returns

The block size, in bytes.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool::block_size()

Definition at line 2654 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  return (reinterpret_cast<memory_pool&> (*mempool)).block_size ();
}

os_mempool_get_capacity()

size_t os_mempool_get_capacity

(

os_mempool_t *

mempool

)

Parameters

[in]

mempool

Pointer to memory pool object instance.

Returns

The max number of blocks in the pool.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool::capacity()

Definition at line 2628 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  return (reinterpret_cast<memory_pool&> (*mempool)).capacity ();
}

os_mempool_get_count()

size_t os_mempool_get_count

(

os_mempool_t *

mempool

)

Parameters

[in]

mempool

Pointer to memory pool object instance.

Returns

The number of blocks used from the queue.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool::count()

Definition at line 2641 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  return (reinterpret_cast<memory_pool&> (*mempool)).count ();
}

os_mempool_get_name()

const char * os_mempool_get_name

(

os_mempool_t *

mempool

)

Parameters

[in]

mempool

Pointer to memory pool object instance.

Returns

Null terminated string.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool::name()

Definition at line 2563 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  return (reinterpret_cast<memory_pool&> (*mempool)).name ();
}

os_mempool_get_pool()

void * os_mempool_get_pool

(

os_mempool_t *

mempool

)

Parameters

[in]

mempool

Pointer to memory pool object instance.

Returns

Pointer to storage.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool::pool()

Definition at line 2706 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  return (void*)(reinterpret_cast<memory_pool&> (*mempool)).pool ();
}

os_mempool_is_empty()

bool os_mempool_is_empty

(

os_mempool_t *

mempool

)

Parameters

[in]

mempool

Pointer to memory pool object instance.

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.

For the complete definition, see

os::rtos::memory_pool::empty()

Definition at line 2667 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  return (reinterpret_cast<memory_pool&> (*mempool)).empty ();
}

os_mempool_is_full()

bool os_mempool_is_full

(

os_mempool_t *

mempool

)

Parameters

[in]

mempool

Pointer to memory pool object instance.

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.

For the complete definition, see

os::rtos::memory_pool::full()

Definition at line 2680 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  return (reinterpret_cast<memory_pool&> (*mempool)).full ();
}

os_mempool_new()

os_mempool_t * os_mempool_new	(	const char *	name,
		size_t	blocks,
		size_t	block_size_bytes,
		const os_mempool_attr_t *	attr
	)

Parameters

[in]	name	Pointer to name (may be NULL).
[in]	blocks	The maximum number of items in the pool.
[in]	block_size_bytes	The size of an item, in bytes.
[in]	attr	Pointer to attributes (may be NULL).

Returns

Pointer to new memory pool object instance.

Dynamically allocate the memory pool object instance using the RTOS system allocator and construct it.

Note

Equivalent of C++ new memory_pool(...).

Must be paired with os_mempool_delete().

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool

Definition at line 2525 of file os-c-wrapper.cpp.

{
  if (attr == nullptr)
    {
      attr = (const os_mempool_attr_t*)&memory_pool::initializer;
    }
  return reinterpret_cast<os_mempool_t*> (new memory_pool (
      name, blocks, block_size_bytes, (const memory_pool::attributes&)*attr));
}

References os::rtos::memory_pool::initializer.

os_mempool_reset()

os_result_t os_mempool_reset

(

os_mempool_t *

mempool

)

Parameters

[in]

mempool

Pointer to memory pool object instance.

Return values

os_ok	The memory pool was reset.
EPERM	Cannot be invoked from an Interrupt Service Routines.

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool::reset()

Definition at line 2693 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  return (os_result_t)(reinterpret_cast<memory_pool&> (*mempool)).reset ();
}

os_mempool_timed_alloc()

void * os_mempool_timed_alloc	(	os_mempool_t *	mempool,
		os_clock_duration_t	timeout
	)

Parameters

[in]	mempool	Pointer to memory pool object instance.
[in]	timeout	Timeout to wait, in clock units (ticks or seconds).

Returns

Pointer to memory block, or NULL if timeout.

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool::timed_alloc()

Definition at line 2602 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  return (reinterpret_cast<memory_pool&> (*mempool)).timed_alloc (timeout);
}

os_mempool_try_alloc()

void * os_mempool_try_alloc

(

os_mempool_t *

mempool

)

Parameters

[in]

mempool

Pointer to memory pool object instance.

Returns

Pointer to memory block, or NULL if no memory available.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::memory_pool::try_alloc()

Definition at line 2589 of file os-c-wrapper.cpp.

{
  assert (mempool != nullptr);
  return (reinterpret_cast<memory_pool&> (*mempool)).try_alloc ();
}