object-pool.h File Reference

Defines object pools, arrays of pre-allocated objects for dynamic use. More...

#include "uevloop/utils/circular-queue.h"

Include dependency graph for object-pool.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	uel_objpool_t
	Pre-allocated memory bound to speciffic types suitable for providing dynamic object management in the stack. More...

Macros
#define	UEL_DECLARE_OBJPOOL_BUFFERS(type, size_log2n, id)
	Declares the necessary buffers to back an object pool, so the programmer doesn't have to reason much about it. More...
#define	UEL_OBJPOOL_BUFFERS(id)   (uint8_t *)&id##_pool_buffer, id##_pool_queue_buffer
	Refers to a previously declared buffer set. More...
#define	UEL_OBJPOOL_BUFFERS_IN(id, obj)   (uint8_t *)&obj.id##_pool_buffer, obj.id##_pool_queue_buffer
	Refers to a previously declared buffer set. More...
#define	UEL_OBJPOOL_BUFFERS_AT(id, obj)   (uint8_t *)&obj->id##_pool_buffer, obj->id##_pool_queue_buffer
	Refers to a previously declared buffer set. More...

Functions
void	uel_objpool_init (uel_objpool_t *pool, size_t size_log2n, size_t item_size, uint8_t *buffer, void **queue_buffer)
	Initialises an object pool. More...
void *	uel_objpool_acquire (uel_objpool_t *pool)
	Acquires an object from the pool. More...
bool	uel_objpool_release (uel_objpool_t *pool, void *element)
	Releases an object to the pool. More...
bool	uel_objpool_is_empty (uel_objpool_t *pool)
	Checks if a pool is depleted. More...

Detailed Description

Defines object pools, arrays of pre-allocated objects for dynamic use.

Macro Definition Documentation

UEL_DECLARE_OBJPOOL_BUFFERS

#define UEL_DECLARE_OBJPOOL_BUFFERS	(		type,
			size_log2n,
			id
	)

Value:

    type id##_pool_buffer[(1<<size_log2n)];                         \
    void *id##_pool_queue_buffer[1<<size_log2n]

Declares the necessary buffers to back an object pool, so the programmer doesn't have to reason much about it.

Use this macro as a shortcut to create the required buffers for an object pool. This will declare two buffers in the calling scope.

Parameters

type	The type of the objects the pool will contain
size_log2n	The number of elements the pool will contain in log2 form
id	A valid identifier for the pools.

UEL_OBJPOOL_BUFFERS

#define UEL_OBJPOOL_BUFFERS

(

id

)

(uint8_t *)&id##_pool_buffer, id##_pool_queue_buffer

Refers to a previously declared buffer set.

This is a convenience macro to supply the buffers generated by UEL_DECLARE_OBJPOOL_BUFFERS to the uel_objpool_init function.

Parameters

id	The identifier used to declare the pool buffers

UEL_OBJPOOL_BUFFERS_AT

#define UEL_OBJPOOL_BUFFERS_AT	(		id,
			obj
	)		(uint8_t *)&obj->id##_pool_buffer, obj->id##_pool_queue_buffer

Refers to a previously declared buffer set.

This is a convenience macro to supply the buffers generated by UEL_DECLARE_OBJPOOL_BUFFERS to the uel_objpool_init function. Use this if the buffers were defined inside an object whose address is accessible in the current scope

Parameters

id	The identifier used to declare the pool buffers
obj	The address of the object storing the pool buffers

UEL_OBJPOOL_BUFFERS_IN

#define UEL_OBJPOOL_BUFFERS_IN	(		id,
			obj
	)		(uint8_t *)&obj.id##_pool_buffer, obj.id##_pool_queue_buffer

Refers to a previously declared buffer set.

This is a convenience macro to supply the buffers generated by UEL_DECLARE_OBJPOOL_BUFFERS to the uel_objpool_init function. Use this if the buffers were defined inside a local object, accessible in the current scope.

Parameters

id	The identifier used to declare the pool buffers
obj	The object storing the pool buffers

Function Documentation

uel_objpool_acquire()

void* uel_objpool_acquire

(

uel_objpool_t *

pool

)

Acquires an object from the pool.

Parameters

pool	The pool from where to acquire the object

Returns

A pointer to the acquired object or NULL if the pool is depleted

uel_objpool_init()

void uel_objpool_init	(	uel_objpool_t *	pool,
		size_t	size_log2n,
		size_t	item_size,
		uint8_t *	buffer,
		void **	queue_buffer
	)

Initialises an object pool.

Parameters

pool	The pool to be initialised
size_log2n	The number of objects in the pool in its log2 form
item_size	The size of each object in the pool. If special alignment is required, it must be included in this value.
buffer	The buffer that contains each object in the pool. Must be 2**size_log2n * item_size long.
queue_buffer	A void pointer array that will be used as the buffer to the object pointer queue. Must be 2**size_log2n long.

uel_objpool_is_empty()

bool uel_objpool_is_empty

(

uel_objpool_t *

pool

)

Checks if a pool is depleted.

Parameters

pool	The pool to be verified

Returns

Whether the pool is empty (i.e.: All addresses have been given out)

uel_objpool_release()

bool uel_objpool_release	(	uel_objpool_t *	pool,
		void *	element
	)

Releases an object to the pool.

Parameters

pool	The pool where the object will be released to
element	The element to be returned to the pool

Returns

Whether the object could be released