Manage thread-safe fixed-size blocks of dynamic memory.
More...
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
- The functions osMemoryPoolAlloc, osMemoryPoolFree, osMemoryPoolGetCapacity, osMemoryPoolGetBlockSize, osMemoryPoolGetCount, osMemoryPoolGetSpace can be called from Interrupt Service Routines.
-
Refer to Memory Pool Configuration for RTX5 configuration options.
| 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 |
Memory Pool ID identifies the memory pool.
- Parameters
-
| [in] | block_count | maximum number of memory blocks in memory pool. |
| [in] | block_size | memory block size in bytes. |
| [in] | attr | memory pool attributes; NULL: default values. |
- Returns
- memory pool ID for reference by other functions or NULL in case of error.
The function osMemoryPoolNew creates and initializes a memory pool object and returns the pointer to the memory pool object identifier or NULL in case of an error.
The parameter block_count specifies the maximum number of memory blocks in the pool.
The parameter block_size sets memory size in bytes.
The parameter attr specifies additional memory pool attributes. Default attributes will be used if set to NULL.
- Note
- This function cannot be called from Interrupt Service Routines.
- Parameters
-
- Returns
- name as NULL terminated string.
The function osMemoryPoolGetName returns the pointer to the name string of the memory pool identified by parameter mp_id or NULL in case of an error.
- Note
- This function cannot be called from Interrupt Service Routines.
- Parameters
-
- Returns
- address of the allocated memory block or NULL in case of no memory is available.
The blocking function osMemoryPoolAlloc allocates the memory pool parameter mp_id and returns a pointer to the address of the allocated memory or 0 in case of an error.
The parameter timeout specifies how long the system waits to allocate the memory. While the system waits, the thread that is calling this function is put into the BLOCKED state. The parameter timeout can have the following values:
- when timeout is 0, the function returns instantly.
- when timeout is set to osWaitForever the function will wait for an infinite time until the memory is allocated.
- all other values specify a time in kernel ticks for a timeout.
- Note
- May be called from Interrupt Service Routines if the parameter timeout is set to 0.
- Parameters
-
| [in] | mp_id | memory pool ID obtained by osMemoryPoolNew. |
| [in] | block | address of the allocated memory block to be returned to the memory pool. |
- Returns
- status code that indicates the execution status of the function.
The function osMemoryPoolFree frees the memory pool block specified by the parameter block in the memory pool object specified by the parameter mp_id.
Possible osStatus_t return values:
- osOK: the memory has been freed.
- osErrorParameter: parameter mp_id is NULL or invalid.
- osErrorResource: the memory pool specified by parameter mp_id is in an invalid memory pool state.
- Note
- This function may be called from Interrupt Service Routines.
- Parameters
-
- Returns
- maximum number of memory blocks.
The function osMemoryPoolGetCapacity returns the maximum number of memory blocks in the memory pool object specified by parameter mp_id or 0 in case of an error.
- Note
- This function may be called from Interrupt Service Routines.
- Parameters
-
- Returns
- memory block size in bytes.
The function osMemoryPoolGetBlockSize returns the memory block size in bytes in the memory pool object specified by parameter mp_id or 0 in case of an error.
- Note
- This function may be called from Interrupt Service Routines.
- Parameters
-
- Returns
- number of memory blocks used.
The function osMemoryPoolGetCount returns the number of memory blocks used in the memory pool object specified by parameter mp_id or 0 in case of an error.
- Note
- This function may be called from Interrupt Service Routines.
- Parameters
-
- Returns
- number of memory blocks available.
The function osMemoryPoolGetSpace returns the number of memory blocks available in the memory pool object specified by parameter mp_id or 0 in case of an error.
- Note
- This function may be called from Interrupt Service Routines.
- Parameters
-
- Returns
- status code that indicates the execution status of the function.
The function osMemoryPoolDelete deletes a memory pool object specified by parameter mp_id. It releases internal memory obtained for memory pool handling. After this call, the mp_id is no longer valid and cannot be used. The memory pool may be created again using the function osMemoryPoolNew.
Possible osStatus_t return values:
- osOK: the memory pool object has been deleted.
- osErrorParameter: parameter mp_id is NULL or invalid.
- osErrorResource: the memory pool specified by parameter mp_id is in an invalid memory pool state.
- osErrorISR: osMemoryPoolDelete cannot be called from interrupt service routines.
- Note
- This function cannot be called from Interrupt Service Routines.
