pool.h File Reference

#include "lib/bits.h"
#include "lib/allocators/allocator_policies.h"
#include "lib/allocators/dynarray.h"

Include dependency graph for pool.h:

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

Go to the source code of this file.

Classes
class	Allocators::Pool< T, Storage >
	allocator design parameters: More...
struct	Pool
	allocator design parameters: More...

Namespaces
namespace	Allocators

Functions
void	Allocators::TestPool ()
Status	pool_create (Pool *p, size_t max_size, size_t el_size)
	Ready Pool for use. More...
Status	pool_destroy (Pool *p)
	free all memory (address space + physical) that constitutes the given Pool. More...
bool	pool_contains (const Pool *p, void *el)
	indicate whether a pointer was allocated from the given pool. More...
void *	pool_alloc (Pool *p, size_t size)
	Dole out memory from the pool. More...
void	pool_free (Pool *p, void *el)
	Make a fixed-size element available for reuse in the given Pool. More...
void	pool_free_all (Pool *p)
	"free" all user allocations that ensued from the given Pool. More...
size_t	pool_committed (Pool *p)
	Return the number of bytes committed in the pool's backing array. More...

Variables
const size_t	POOL_VARIABLE_ALLOCS = ~(size_t)0u
	pass as pool_create's <el_size> param to indicate variable-sized allocs are required (see below). More...

Function Documentation

pool_alloc()

void * pool_alloc	(	Pool *	p,
		size_t	size
	)

Dole out memory from the pool.

exhausts the freelist before returning new entries to improve locality.

Parameters

p	Pool*
size	bytes to allocate; ignored if pool_create's el_size was not 0.

Returns

allocated memory, or 0 if the Pool would have to be expanded and there isn't enough memory to do so.

pool_committed()

size_t pool_committed

(

Pool *

p

)

Return the number of bytes committed in the pool's backing array.

This is roughly the number of bytes allocated in this pool plus the unused freelist entries.

Parameters

p

Pool*

Returns

number of bytes

pool_contains()

bool pool_contains	(	const Pool *	p,
		void *	el
	)

indicate whether a pointer was allocated from the given pool.

this is useful for callers that use several types of allocators.

Parameters

p	Pool*
el

Returns

bool.

pool_create()

Status pool_create	(	Pool *	p,
		size_t	max_size,
		size_t	el_size
	)

Ready Pool for use.

Parameters

p	Pool*
max_size	Max size [bytes] of the Pool; this much (rounded up to next page multiple) virtual address space is reserved. no virtual memory is actually committed until calls to pool_alloc.
el_size	Number of bytes that will be returned by each pool_alloc (whose size parameter is then ignored). Can be 0 to allow variable-sized allocations, but pool_free is then unusable.

Returns

Status

pool_destroy()

Status pool_destroy

(

Pool *

p

)

free all memory (address space + physical) that constitutes the given Pool.

future alloc and free calls on this pool will fail. continued use of the allocated memory (*) is impossible because it is marked not-present via MMU. (* no matter if in freelist or unused or "allocated" to user)

Parameters

p

Pool*

Returns

Status.

pool_free()

void pool_free	(	Pool *	p,
		void *	el
	)

Make a fixed-size element available for reuse in the given Pool.

this is not allowed if the Pool was created for variable-size elements. rationale: avoids having to pass el_size here and compare with size when allocating; also prevents fragmentation and leaking memory.

Parameters

p	Pool*
el	Element returned by pool_alloc.

pool_free_all()

void pool_free_all

(

Pool *

p

)

"free" all user allocations that ensued from the given Pool.

this resets it as if freshly pool_create-d, but doesn't release the underlying reserved virtual memory.

Parameters

p

Pool*

Variable Documentation

POOL_VARIABLE_ALLOCS

const size_t POOL_VARIABLE_ALLOCS = ~(size_t)0u

pass as pool_create's <el_size> param to indicate variable-sized allocs are required (see below).