pool.h File Reference

Provides functions and structures for maintaining dynamically allocated and freed pools of integers. More...

Go to the source code of this file.

Data Structures
struct	guac_pool
	A pool of integers. More...
struct	guac_pool_int
	Represents a single integer within a larger pool of integers. More...

Functions
guac_pool *	guac_pool_alloc (int size)
	Allocates a new guac_pool having the given minimum size.
void	guac_pool_free (guac_pool *pool)
	Frees the given guac_pool.
int	guac_pool_next_int (guac_pool *pool)
	Returns the next available integer from the given guac_pool.
int	guac_pool_next_int_below (guac_pool *pool, int limit)
	Returns the next available integer from the given guac_pool that is below the given limit.
int	guac_pool_next_int_below_or_die (guac_pool *pool, int limit)
	Returns the next available integer from the given guac_pool that is below the given limit.
void	guac_pool_free_int (guac_pool *pool, int value)
	Frees the given integer back into the given guac_pool.

Detailed Description

Provides functions and structures for maintaining dynamically allocated and freed pools of integers.

Function Documentation

guac_pool_alloc()

guac_pool * guac_pool_alloc

(

int

size

)

Allocates a new guac_pool having the given minimum size.

Parameters

size	The minimum number of integers which must have been returned by guac_pool_next_int before freed integers (previously used integers) are allowed to be returned.

Returns

A new, empty guac_pool, having the given minimum size.

guac_pool_free()

void guac_pool_free

(

guac_pool *

pool

)

Frees the given guac_pool.

Parameters

pool	The guac_pool to free.

guac_pool_free_int()

void guac_pool_free_int	(	guac_pool *	pool,
		int	value )

Frees the given integer back into the given guac_pool.

The integer given will be available for future calls to guac_pool_next_int. This operation is atomic.

Parameters

pool	The guac_pool to free the given integer into.
value	The integer which should be returned to the given pool, such that it can be received by a future call to guac_pool_next_int.

guac_pool_next_int()

int guac_pool_next_int

(

guac_pool *

pool

)

Returns the next available integer from the given guac_pool.

All integers returned are non-negative, and are returned in sequence, starting from 0. This operation is atomic.

Parameters

pool	The guac_pool to retrieve an integer from.

Returns

The next available integer, which may be either an integer not yet returned by a call to guac_pool_next_int, or an integer which was previously returned but has since been freed.

guac_pool_next_int_below()

int guac_pool_next_int_below	(	guac_pool *	pool,
		int	limit )

Returns the next available integer from the given guac_pool that is below the given limit.

If no such integer can be obtained because all such integers are already in use, -1 will be returned instead. All integers successfully returned are non-negative, and are returned in sequence, starting from 0. This operation is atomic.

Parameters

pool	The guac_pool to retrieve an integer from.
limit	The exclusive upper bound to enforce on all integers returned by this function. Integers of this value or greater will never be returned. If all other integers are already in use, -1 will be returned instead.

Returns

The next available integer, which may be either an integer not yet returned by a call to guac_pool_next_int, or an integer which was previously returned but has since been freed. If all integers are currently in use and no integer can be returned without reaching the given limit, -1 is returned.

guac_pool_next_int_below_or_die()

int guac_pool_next_int_below_or_die	(	guac_pool *	pool,
		int	limit )

Returns the next available integer from the given guac_pool that is below the given limit.

If no such integer can be obtained because all such integers are already in use, the current process will abort and this function will not return. All integers successfully returned are non-negative, and are returned in sequence, starting from 0. This operation is atomic.

Parameters

pool	The guac_pool to retrieve an integer from.
limit	The exclusive upper bound to enforce on all integers returned by this function. Integers of this value or greater will never be returned. If all other integers are already in use, the current process will abort and this function will not return.

Returns

The next available integer, which may be either an integer not yet returned by a call to guac_pool_next_int, or an integer which was previously returned but has since been freed. If all integers are currently in use and no integer can be returned without reaching the given limit, the current process will abort and this function will not return.