automatic-pool.h File Reference

Defines automatic pointers and automatic pools, objects that wrap object pools and objects managed by them. These wrappers provide basic automatic memory management. More...

#include "uevloop/utils/object-pool.h"
#include "uevloop/utils/closure.h"

Include dependency graph for automatic-pool.h:

Go to the source code of this file.

Data Structures
struct	uel_autoptr
	Automatic pointers are pointers wrapped by information of where they were issued. More...
struct	uel_autopool_t
	Automatic pools are wrappers to object pools. They manage the acquisition and release cycle from objects issued at the pool by wrapping them in automatic pointers. More...

Macros
#define	UEL_DECLARE_AUTOPOOL_BUFFERS(type, size_log2n, id)
	Declares the necessary buffers to back an automatic pool, so the programmer doesn't have to reason much about it. More...
#define	UEL_AUTOPOOL_BUFFERS(id)   (uint8_t *)&id##_buffer, id##_pool_buffer, id##_pool_queue_buffer
	Refers to a previously declared buffer set. More...
#define	UEL_AUTOPOOL_BUFFERS_IN(id, obj)
	Refers to a previously declared buffer set. More...
#define	UEL_AUTOPOOL_BUFFERS_AT(id, obj)
	Refers to a previously declared buffer set. More...

Typedefs
typedef void **	uel_autoptr_t
	Aliases uel_autoptr_t to void ** so it can be cast to pointers to other types.

Functions
void	uel_autoptr_dealloc (uel_autoptr_t autoptr)
	Deallocates an automatic pointer. More...
void	uel_autopool_init (uel_autopool_t *pool, size_t size_log2n, size_t item_size, uint8_t *object_buffer, struct uel_autoptr *autoptr_buffer, void **queue_buffer)
	Initialises an automatic pool. More...
uel_autoptr_t	uel_autopool_alloc (uel_autopool_t *pool)
	Allocates an object and wrap it in a automatic pointer. More...
bool	uel_autopool_is_empty (uel_autopool_t *pool)
	Checks if a pool is depleted. More...
void	uel_autopool_set_constructor (uel_autopool_t *pool, uel_closure_t constructor)
	Sets the constructor closure of an autopool. More...
void	uel_autopool_set_destructor (uel_autopool_t *pool, uel_closure_t destructor)
	Sets the destructor closure of an autopool. More...

Detailed Description

Defines automatic pointers and automatic pools, objects that wrap object pools and objects managed by them. These wrappers provide basic automatic memory management.

Macro Definition Documentation

UEL_AUTOPOOL_BUFFERS

#define UEL_AUTOPOOL_BUFFERS

(

id

)

(uint8_t *)&id##_buffer, 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_AUTOPOOL_BUFFERS() to the uel_autopool_init() function.

Parameters

id	The identifier used to declare the pool buffers

UEL_AUTOPOOL_BUFFERS_AT

#define UEL_AUTOPOOL_BUFFERS_AT	(		id,
			obj
	)

Value:

    (uint8_t *)&obj->id##_buffer, 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_AUTOPOOL_BUFFERS() to the uel_autopool_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_AUTOPOOL_BUFFERS_IN

#define UEL_AUTOPOOL_BUFFERS_IN	(		id,
			obj
	)

Value:

    (uint8_t *)&obj.id##_buffer, 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_AUTOPOOL_BUFFERS() to the uel_autopool_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

UEL_DECLARE_AUTOPOOL_BUFFERS

#define UEL_DECLARE_AUTOPOOL_BUFFERS	(		type,
			size_log2n,
			id
	)

Value:

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

Declares the necessary buffers to back an automatic 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 automatic pool. This will declare three 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.

Function Documentation

uel_autopool_alloc()

uel_autoptr_t uel_autopool_alloc

(

uel_autopool_t *

pool

)

Allocates an object and wrap it in a automatic pointer.

The allocated object is submited to the contructor closure set in the autopool.

See also

uel_autopool_set_constructor()

Parameters

pool	The automatic pool from where to acquire the object

Returns

An autopointer wrapping the acquired object or NULL if one could not be acquired.

uel_autopool_init()

void uel_autopool_init	(	uel_autopool_t *	pool,
		size_t	size_log2n,
		size_t	item_size,
		uint8_t *	object_buffer,
		struct uel_autoptr *	autoptr_buffer,
		void **	queue_buffer
	)

Initialises an automatic 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.
object_buffer	The buffer that contains each object in the pool. Must be 2**size_log2n * item_size long.
autoptr_buffer	The buffer that contains each autoptr object to be issued. 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_autopool_is_empty()

bool uel_autopool_is_empty

(

uel_autopool_t *

pool

)

Checks if a pool is depleted.

Parameters

pool	The pool to be verified

Returns

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

uel_autopool_set_constructor()

void uel_autopool_set_constructor	(	uel_autopool_t *	pool,
		uel_closure_t	constructor
	)

Sets the constructor closure of an autopool.

This closure is invoked when uel_autoptr_alloc() is called and takes a bare pointer to the object being alloc'ed as parameter.

See also

uel_autoptr_alloc()

Parameters

pool	The autopool onto which to attach the constructor
constructor	The constructor closure

uel_autopool_set_destructor()

void uel_autopool_set_destructor	(	uel_autopool_t *	pool,
		uel_closure_t	destructor
	)

Sets the destructor closure of an autopool.

This closure is invoked when uel_autoptr_dealloc() is called and takes a bare pointer to the object being dealloc'ed as parameter.

See also

uel_autoptr_dealloc()

Parameters

pool	The autopool onto which to attach the destructor
destructor	The destructor closure

uel_autoptr_dealloc()

void uel_autoptr_dealloc

(

uel_autoptr_t

autoptr

)

Deallocates an automatic pointer.

When called, the destructor closure defined at the autopointer's source autopool is invoked. Afterwards, the autopointer is returned to its pool.

See also

uel_autopool_set_destructor()

Warning

The object must not be used after it's dealloc'ed.