Memory Pools

Classes
struct	os_memblock
struct	os_mempool
struct	os_mempool_info

Macros
#define	OS_MEMPOOL_F_EXT   0x01
#define	OS_MEMPOOL_BYTES(n, blksize)    (sizeof (os_membuf_t) * OS_MEMPOOL_SIZE((n), (blksize)))

Typedefs
typedef os_error_t	os_mempool_put_fn(struct os_mempool_ext *ome, void *data, void *arg)

Functions
struct os_mempool *	os_mempool_info_get_next (struct os_mempool *, struct os_mempool_info *)
os_error_t	os_mempool_init (struct os_mempool *mp, uint16_t blocks, uint32_t block_size, void *membuf, const char *name)
os_error_t	os_mempool_ext_init (struct os_mempool_ext *mpe, uint16_t blocks, uint32_t block_size, void *membuf, const char *name)
os_error_t	os_mempool_unregister (struct os_mempool *mp)
os_error_t	os_mempool_clear (struct os_mempool *mp)
os_error_t	os_mempool_ext_clear (struct os_mempool_ext *mpe)
bool	os_mempool_is_sane (const struct os_mempool *mp)
int	os_memblock_from (const struct os_mempool *mp, const void *block_addr)
void *	os_memblock_get (struct os_mempool *mp)
os_error_t	os_memblock_put_from_cb (struct os_mempool *mp, void *block_addr)
os_error_t	os_memblock_put (struct os_mempool *mp, void *block_addr)

Detailed Description

Macro Definition Documentation

OS_MEMPOOL_BYTES

#define OS_MEMPOOL_BYTES	(		n,
			blksize
	)		(sizeof (os_membuf_t) * OS_MEMPOOL_SIZE((n), (blksize)))

Calculates the number of bytes required to initialize a memory pool.

OS_MEMPOOL_F_EXT

#define OS_MEMPOOL_F_EXT   0x01

Indicates an extended mempool. Address can be safely cast to (struct os_mempool_ext *).

Typedef Documentation

os_mempool_put_fn

typedef os_error_t os_mempool_put_fn(struct os_mempool_ext *ome, void *data, void *arg)

Block put callback function. If configured, this callback gets executed whenever a block is freed to the corresponding extended mempool. Note: The os_memblock_put() function calls this callback instead of freeing the block itself. Therefore, it is the callback's responsibility to free the block via a call to os_memblock_put_from_cb().

Parameters

ome	The extended mempool that a block is being freed back to.
data	The block being freed.
arg	Optional argument configured along with the callback.

Returns

Indicates whether the block was successfully freed. A non-zero value should only be returned if the block was not successfully released back to its pool.

Function Documentation

os_memblock_from()

int os_memblock_from	(	const struct os_mempool *	mp,
		const void *	block_addr
	)

Checks if a memory block was allocated from the specified mempool.

Parameters

mp	The mempool to check as parent.
block_addr	The memory block to check as child.

Returns

0 if the block does not belong to the mempool; 1 if the block does belong to the mempool.

os_memblock_get()

void * os_memblock_get

(

struct os_mempool *

mp

)

Get a memory block from a memory pool

Parameters

mp	Pointer to the memory pool

Returns

void* Pointer to block if available; NULL otherwise

os_memblock_put()

os_error_t os_memblock_put	(	struct os_mempool *	mp,
		void *	block_addr
	)

Puts the memory block back into the pool

Parameters

mp	Pointer to memory pool
block_addr	Pointer to memory block

Returns

os_error_t

os_memblock_put_from_cb()

os_error_t os_memblock_put_from_cb	(	struct os_mempool *	mp,
		void *	block_addr
	)

Puts the memory block back into the pool, ignoring the put callback, if any. This function should only be called from a put callback to free a block without causing infinite recursion.

Parameters

mp	Pointer to memory pool
block_addr	Pointer to memory block

Returns

os_error_t

os_mempool_clear()

os_error_t os_mempool_clear

(

struct os_mempool *

mp

)

Clears a memory pool.

Parameters

mp	The mempool to clear.

Returns

os_error_t

os_mempool_ext_clear()

os_error_t os_mempool_ext_clear

(

struct os_mempool_ext *

mpe

)

Clears an extended memory pool.

Parameters

mpe	The extended memory pool to clear.

Returns

os_error_t

os_mempool_ext_init()

os_error_t os_mempool_ext_init	(	struct os_mempool_ext *	mpe,
		uint16_t	blocks,
		uint32_t	block_size,
		void *	membuf,
		const char *	name
	)

Initializes an extended memory pool. Extended attributes (e.g., callbacks) are not specified when this function is called; they are assigned manually after initialization.

Parameters

mpe	The extended memory pool to initialize.
blocks	The number of blocks in the pool.
block_size	The size of each block, in bytes.
membuf	Pointer to memory to contain blocks.
name	Name of the pool.

Returns

os_error_t

os_mempool_info_get_next()

struct os_mempool * os_mempool_info_get_next	(	struct os_mempool *	mp,
		struct os_mempool_info *	omi
	)

Get information about the next system memory pool.

Parameters

mempool	The current memory pool, or NULL if starting iteration.
info	A pointer to the structure to return memory pool information into.

Returns

The next memory pool in the list to get information about, or NULL when at the last memory pool.

os_mempool_init()

os_error_t os_mempool_init	(	struct os_mempool *	mp,
		uint16_t	blocks,
		uint32_t	block_size,
		void *	membuf,
		const char *	name
	)

Initialize a memory pool.

Parameters

mp	Pointer to a pointer to a mempool
blocks	The number of blocks in the pool
blocks_size	The size of the block, in bytes.
membuf	Pointer to memory to contain blocks.
name	Name of the pool.

Returns

os_error_t

os_mempool_is_sane()

bool os_mempool_is_sane

(

const struct os_mempool *

mp

)

Performs an integrity check of the specified mempool. This function attempts to detect memory corruption in the specified memory pool.

Parameters

mp	The mempool to check.

Returns

true if the memory pool passes the integrity check; false if the memory pool is corrupt.

os_mempool_unregister()

os_error_t os_mempool_unregister

(

struct os_mempool *

mp

)

Removes the specified mempool from the list of initialized mempools.

Parameters

mp	The mempool to unregister.

Returns

0 on success; OS_INVALID_PARM if the mempool is not registered.