core/include/mem_pool.h File Reference

Memory pool. More...

Data Structures

struct  os_mem_pool_s
 Memory pool structure. More...

Defines

#define os_mem_pool_available(m)   DOC_HIDDEN
 Gets number of free items in the pool.
#define os_mem_pool_itemsize(m)   ((m)->itemsize);
 Gets the size of pool item.

Functions

os_result_t os_mem_pool_create (os_mem_pool_t *m, unsigned char log2itemsize, unsigned short capacity)
 Creates memory pool.
os_result_t os_mem_pool_destroy (os_mem_pool_t *m)
 Destroys memory pool.
os_result_t os_mem_pool_alloc (os_mem_pool_t *m, void **item)
 Allocates memory item.
os_result_t os_mem_pool_free (os_mem_pool_t *m, void *item)
 Deallocates memory item.

Detailed Description

Memory pool.

Author:
Piotr Romaniuk, (c) ELESOFTROM
Version:
1.1 Nov 8, 2013

This is implementation of memory pool. The pool is a kind of partition with items of constant size. It works more efficiently than heap allocator. Both operations: allocation and deallocation are simpler and more reliable when memory pool is used. The memory pool has an advantage over heap, the pool has no risk of fragmentation and lack of memory in one continuous part. The cost for this feature is additional memory usage - the items are always the same size. This extra memory consumption can be decreased by matching size of the item to used elements or by creation a set of pools, each one with different size.

Note:
Memory pool function are protected from concurrent access, and can be used in ISR and during disabled preemption.

Define Documentation

#define os_mem_pool_available (   m)    DOC_HIDDEN

Gets number of free items in the pool.

Parameters:
[in]mpointer to memory pool structure
Returns:
number of free items in the pool.
#define os_mem_pool_itemsize (   m)    ((m)->itemsize);

Gets the size of pool item.

Parameters:
[in]mpointer to memory pool structure
Returns:
number of free items

Function Documentation

os_result_t os_mem_pool_alloc ( os_mem_pool_t *  m,
void **  item 
)

Allocates memory item.

The function is thread safe and can be called from ISR.
Allocated memory can be set to zeros or marked with zeros at the beginning (this is selected by config.h)

Parameters:
[in]mpointer to pool structure
[out]itempointer to variable where pointer to allocated item will be stored
Returns:
OS_STATUS_OK when memory has been allocated,
OS_ERROR_NO_MEMORY when memory pool has no free items
os_result_t os_mem_pool_create ( os_mem_pool_t *  m,
unsigned char  log2itemsize,
unsigned short  capacity 
)

Creates memory pool.

This is not thread-safe (use before scheduler is run or before any use of the pool).

Parameters:
[out]mpointer to empty structure that will describe the pool
[in]log2itemsizeitem size must be power of 2, e.g. 1, 2, 4, 8, 16 etc.
[in]capacitynumber of items in the memory pool
Returns:
OS_STATUS_OK when pool has been successfuly created
OS_ERROR_NO_MEMORY when failed due to insuficient memory
os_result_t os_mem_pool_destroy ( os_mem_pool_t *  m)

Destroys memory pool.

The function is thread safe.

Parameters:
[in]m- pointer to pool structure
Returns:
OS_STATUS_OK when pool has been successfully destroyed,
OS_ERROR when there is any element that is still in use or memory pool data pointers are invalid
os_result_t os_mem_pool_free ( os_mem_pool_t *  m,
void *  item 
)

Deallocates memory item.

The function is thread safe and can be called from ISR.

Note:
The pointer must be valid address of this item in the pool and be allocated in the pool, otherwise it throws os_bug(OS_BUG_INVALID_PTR) or OS_BUG_DBL_FREE exceptions.
Memory of deleted item can be filled or marked with CFG_MEM_POOL_POISON_FILL.
Parameters:
[in]mpointer to pool structure
[in]itempointer to memory that need to be deallocated - returned to the pool.
Returns:
OS_STATUS_OK when memory has been returned to pool