CMSIS-RTOS2  Version 2.0.0
Real-Time Operating System: API and RTX Reference Implementation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Memory Pool

Manage thread-safe fixed-size blocks of dynamic memory. More...

Data Structures

struct  osMemoryPoolAttr_t
 Attributes structure for memory pool. More...
 

Typedefs

typedef void * osMemoryPoolId_t
 

Functions

osMemoryPoolId_t osMemoryPoolNew (uint32_t block_count, uint32_t block_size, const osMemoryPoolAttr_t *attr)
 Create and Initialize a Memory Pool object. More...
 
const char * osMemoryPoolGetName (osMemoryPoolId_t mp_id)
 Get name of a Memory Pool object. More...
 
void * osMemoryPoolAlloc (osMemoryPoolId_t mp_id, uint32_t timeout)
 Allocate a memory block from a Memory Pool. More...
 
osStatus_t osMemoryPoolFree (osMemoryPoolId_t mp_id, void *block)
 Return an allocated memory block back to a Memory Pool. More...
 
uint32_t osMemoryPoolGetCapacity (osMemoryPoolId_t mp_id)
 Get maximum number of memory blocks in a Memory Pool. More...
 
uint32_t osMemoryPoolGetBlockSize (osMemoryPoolId_t mp_id)
 Get memory block size in a Memory Pool. More...
 
uint32_t osMemoryPoolGetCount (osMemoryPoolId_t mp_id)
 Get number of memory blocks used in a Memory Pool. More...
 
uint32_t osMemoryPoolGetSpace (osMemoryPoolId_t mp_id)
 Get number of memory blocks available in a Memory Pool. More...
 
osStatus_t osMemoryPoolDelete (osMemoryPoolId_t mp_id)
 Delete a Memory Pool object. More...
 

Description

Memory pools are fixed-size blocks of memory that are thread-safe. They operate much faster than the dynamically allocated heap and do not suffer from fragmentation. Being thread-safe, they can be accessed from threads and ISRs alike.

Shared memory is one of the basic models to exchange information between threads. Using memory pools for exchanging data, you can share more complex objects between threads if compared to a Message Queue. Memory pool management functions are used to define and manage such fixed-sized memory pools.

Note
Refer to Memory Pool Configuration for RTX5 configuration options.

Working with Memory Pools

Follow these steps to create and use a memory pool:

  1. Declare a data structure that combines a number of elements:
    typedef struct {
    uint32_t length;
    uint32_t width;
    uint32_t height;
    uint32_t weight;
    } properties_t;
  2. Declare a memory pool of these objects as a block of memory:
    osMemoryPoolId_t object_pool_id; // Memory pool ID
  3. Then, create the memory pool in a thread:
    object_pool_id = osMemoryPoolNew(16, sizeof(properties_t), NULL);
  4. Allocate the pool within a thread and fill it with data:
    properties_t *object_data;
    object_data = (properties_t *) osPoolAlloc(object_pool_id);
    object_data->length = 100;
    object_data->width = 10;
    object_data->height = 23;
    object_data->weight = 1000;

Data Structure Documentation

struct osMemoryPoolAttr_t
Data Fields
const char * name name of the memory pool
uint32_t attr_bits attribute bits
void * cb_mem memory for control block
uint32_t cb_size size of provided memory for control block
void * mp_mem memory for data storage
uint32_t mp_size size of provided memory for data storage

Typedef Documentation

Memory Pool ID identifies the memory pool.

Function Documentation

osMemoryPoolId_t osMemoryPoolNew ( uint32_t  block_count,
uint32_t  block_size,
const osMemoryPoolAttr_t attr 
)
Parameters
[in]block_countmaximum number of memory blocks in memory pool.
[in]block_sizememory block size in bytes.
[in]attrmemory pool attributes; NULL: default values.
Returns
memory pool ID for reference by other functions or NULL in case of error.
const char * osMemoryPoolGetName ( osMemoryPoolId_t  mp_id)
Parameters
[in]mp_idmemory pool ID obtained by osMemoryPoolNew.
Returns
name as NULL terminated string.
*void * osMemoryPoolAlloc ( osMemoryPoolId_t  mp_id,
uint32_t  timeout 
)
Parameters
[in]mp_idmemory pool ID obtained by osMemoryPoolNew.
[in]timeoutTimeout Value or 0 in case of no time-out.
Returns
address of the allocated memory block or NULL in case of no memory is available.
osStatus_t osMemoryPoolFree ( osMemoryPoolId_t  mp_id,
void *  block 
)
Parameters
[in]mp_idmemory pool ID obtained by osMemoryPoolNew.
[in]blockaddress of the allocated memory block to be returned to the memory pool.
Returns
status code that indicates the execution status of the function.
uint32_t osMemoryPoolGetCapacity ( osMemoryPoolId_t  mp_id)
Parameters
[in]mp_idmemory pool ID obtained by osMemoryPoolNew.
Returns
maximum number of memory blocks.
uint32_t osMemoryPoolGetBlockSize ( osMemoryPoolId_t  mp_id)
Parameters
[in]mp_idmemory pool ID obtained by osMemoryPoolNew.
Returns
memory block size in bytes.
uint32_t osMemoryPoolGetCount ( osMemoryPoolId_t  mp_id)
Parameters
[in]mp_idmemory pool ID obtained by osMemoryPoolNew.
Returns
number of memory blocks used.
uint32_t osMemoryPoolGetSpace ( osMemoryPoolId_t  mp_id)
Parameters
[in]mp_idmemory pool ID obtained by osMemoryPoolNew.
Returns
number of memory blocks available.
osStatus_t osMemoryPoolDelete ( osMemoryPoolId_t  mp_id)
Parameters
[in]mp_idmemory pool ID obtained by osMemoryPoolNew.
Returns
status code that indicates the execution status of the function.