Pools of buffer headers

Classes
struct	MMAL_POOL_T

Typedefs
typedef struct MMAL_POOL_T	MMAL_POOL_T
typedef void *(*	mmal_pool_allocator_alloc_t) (void *context, uint32_t size)
typedef void(*	mmal_pool_allocator_free_t) (void *context, void *mem)
typedef MMAL_BOOL_T(*	MMAL_POOL_BH_CB_T) (MMAL_POOL_T *pool, MMAL_BUFFER_HEADER_T *buffer, void *userdata)

Functions
MMAL_POOL_T *	mmal_pool_create (unsigned int headers, uint32_t payload_size)
MMAL_POOL_T *	mmal_pool_create_with_allocator (unsigned int headers, uint32_t payload_size, void *allocator_context, mmal_pool_allocator_alloc_t allocator_alloc, mmal_pool_allocator_free_t allocator_free)
void	mmal_pool_destroy (MMAL_POOL_T *pool)
MMAL_STATUS_T	mmal_pool_resize (MMAL_POOL_T *pool, unsigned int headers, uint32_t payload_size)
void	mmal_pool_callback_set (MMAL_POOL_T *pool, MMAL_POOL_BH_CB_T cb, void *userdata)
void	mmal_pool_pre_release_callback_set (MMAL_POOL_T *pool, MMAL_BH_PRE_RELEASE_CB_T cb, void *userdata)

Detailed Description

A pool of buffer headers is composed of a queue (MMAL_QUEUE_T) and a user specified number of buffer headers (MMAL_BUFFER_HEADER_T).

Typedef Documentation

mmal_pool_allocator_alloc_t

typedef void*(* mmal_pool_allocator_alloc_t) (void *context, uint32_t size)

Allocator alloc prototype

Parameters

context	The context pointer passed in on pool creation.
size	The size of the allocation required, in bytes.

Returns

The pointer to the newly allocated memory, or NULL on failure.

Definition at line 56 of file mmal_pool.h.

mmal_pool_allocator_free_t

typedef void(* mmal_pool_allocator_free_t) (void *context, void *mem)

Allocator free prototype

Parameters

context	The context pointer passed in on pool creation.
mem	The pointer to the memory to be released.

Definition at line 62 of file mmal_pool.h.

MMAL_POOL_BH_CB_T

typedef MMAL_BOOL_T(* MMAL_POOL_BH_CB_T) (MMAL_POOL_T *pool, MMAL_BUFFER_HEADER_T *buffer, void *userdata)

Definition of the callback used by a pool to signal back to the user that a buffer header has been released back to the pool.

Parameters

pool	Pointer to the pool
buffer	Buffer header just released
userdata	User specific data passed in when setting the callback

Returns

True to have the buffer header put back in the pool's queue, false if the buffer header has been taken within the callback.

Definition at line 140 of file mmal_pool.h.

MMAL_POOL_T

typedef struct MMAL_POOL_T MMAL_POOL_T

Definition of a pool

Function Documentation

mmal_pool_callback_set()

void mmal_pool_callback_set	(	MMAL_POOL_T *	pool,
		MMAL_POOL_BH_CB_T	cb,
		void *	userdata
	)

Set a buffer header release callback to the pool. Each time a buffer header is released to the pool, the callback will be triggered.

Parameters

pool	Pointer to a pool
cb	Callback function
userdata	User specific data which will be passed with each callback

mmal_pool_create()

MMAL_POOL_T* mmal_pool_create	(	unsigned int	headers,
		uint32_t	payload_size
	)

Create a pool of MMAL_BUFFER_HEADER_T. After allocation, all allocated buffer headers will have been added to the queue.

It is valid to create a pool with no buffer headers, or with zero size payload buffers. The mmal_pool_resize() function can be used to increase or decrease the number of buffer headers, or the size of the payload buffers, after creation of the pool.

The payload buffers may also be allocated independently by the client, and assigned to the buffer headers, but it will be the responsibility of the client to deal with resizing and releasing the memory. It is recommended that mmal_pool_create_with_allocator() is used in this case, supplying allocator function pointers that will be used as necessary by MMAL.

Parameters

headers	Number of buffer headers to be allocated with the pool.
payload_size	Size of the payload buffer that will be allocated in each of the buffer headers.

Returns

Pointer to the newly created pool or NULL on failure.

mmal_pool_create_with_allocator()

MMAL_POOL_T* mmal_pool_create_with_allocator	(	unsigned int	headers,
		uint32_t	payload_size,
		void *	allocator_context,
		mmal_pool_allocator_alloc_t	allocator_alloc,
		mmal_pool_allocator_free_t	allocator_free
	)

Create a pool of MMAL_BUFFER_HEADER_T. After allocation, all allocated buffer headers will have been added to the queue.

It is valid to create a pool with no buffer headers, or with zero size payload buffers. The mmal_pool_resize() function can be used to increase or decrease the number of buffer headers, or the size of the payload buffers, after creation of the pool. The allocators passed during creation shall be used when resizing the payload buffers.

Parameters

headers	Number of buffer headers to be allocated with the pool.
payload_size	Size of the payload buffer that will be allocated in each of the buffer headers.
allocator_context	Pointer to the context of the allocator.
allocator_alloc	Function pointer for the alloc call of the allocator.
allocator_free	Function pointer for the free call of the allocator.

Returns

Pointer to the newly created pool or NULL on failure.

mmal_pool_destroy()

void mmal_pool_destroy

(

MMAL_POOL_T *

pool

)

Destroy a pool of MMAL_BUFFER_HEADER_T. This will also deallocate all of the memory which was allocated when creating or resizing the pool.

If payload buffers have been allocated independently by the client, they should be released prior to calling this function. If the client provided allocator functions, the allocator_free function shall be called for each payload buffer.

Parameters

pool	Pointer to a pool

mmal_pool_pre_release_callback_set()

void mmal_pool_pre_release_callback_set	(	MMAL_POOL_T *	pool,
		MMAL_BH_PRE_RELEASE_CB_T	cb,
		void *	userdata
	)

Set a pre-release callback for all buffer headers in the pool. Each time a buffer header is about to be released to the pool, the callback will be triggered.

Parameters

pool	Pointer to the pool
cb	Pre-release callback function
userdata	User-specific data passed back with each callback

mmal_pool_resize()

MMAL_STATUS_T mmal_pool_resize	(	MMAL_POOL_T *	pool,
		unsigned int	headers,
		uint32_t	payload_size
	)

Resize a pool of MMAL_BUFFER_HEADER_T. This allows modifying either the number of allocated buffers, the payload size or both at the same time.

Parameters

pool	Pointer to the pool
headers	New number of buffer headers to be allocated in the pool. It is not valid to pass zero for the number of buffers.
payload_size	Size of the payload buffer that will be allocated in each of the buffer headers. If this is set to 0, all payload buffers shall be released.

Returns

MMAL_SUCCESS or an error on failure.