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.0 Feb 4, 2011

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]

m

pointer 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]

m

pointer 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]	m	pointer to pool structure
[out]	item	pointer 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]	m	pointer to empty structure that will describe the pool
[in]	log2itemsize	item size must be power of 2, e.g. 1, 2, 4, 8, 16 etc.
[in]	capacity	number 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]	m	pointer to pool structure
[in]	item	pointer to memory that need to be deallocated - returned to the pool.

Returns:

OS_STATUS_OK when memory has been returned to pool