Allocator implementations

Classes
class	iteration_allocator< N, BlockOrRawAllocator >
	A stateful RawAllocator that is designed for allocations in a loop. More...
class	double_frame_allocator< BlockOrRawAllocator >
	An alias for iteration_allocator for two iterations. More...
class	allocator_traits< iteration_allocator< N, BlockAllocator > >
	Specialization of the allocator_traits for iteration_allocator. More...
class	composable_allocator_traits< iteration_allocator< N, BlockAllocator > >
	Specialization of the composable_allocator_traits for iteration_allocator classes. More...
class	joint
	Tag type that can't be created. More...
struct	joint_size
	Tag type to make the joint size more explicit. More...
class	joint_type< T >
	CRTP base class for all objects that want to use joint memory. More...
class	joint_ptr< T, RawAllocator >
	A pointer to an object where all allocations are joint. More...
class	joint_allocator
	A RawAllocator that uses the additional joint memory for its allocation. More...
struct	is_shared_allocator< joint_allocator >
	Specialization of is_shared_allocator to mark joint_allocator as shared. More...
struct	propagation_traits< joint_allocator >
	Specialization of the propagation_traits for the joint_allocator. More...
class	joint_array< T >
	A zero overhead dynamic array using joint memory. More...
class	memory_pool< PoolType, BlockOrRawAllocator >
	A stateful RawAllocator that manages nodes of fixed size. More...
class	allocator_traits< memory_pool< PoolType, ImplRawAllocator > >
	Specialization of the allocator_traits for memory_pool classes. More...
class	composable_allocator_traits< memory_pool< PoolType, BlockOrRawAllocator > >
	Specialization of the composable_allocator_traits for memory_pool classes. More...
struct	identity_buckets
	A BucketDistribution for memory_pool_collection defining that there is a bucket, i.e. More...
struct	log2_buckets
	A BucketDistribution for memory_pool_collection defining that there is a bucket, i.e. More...
class	memory_pool_collection< PoolType, BucketDistribution, BlockOrRawAllocator >
	A stateful RawAllocator that behaves as a collection of multiple memory_pool objects. More...
class	bucket_allocator< PoolType, ImplAllocator >
	An alias for memory_pool_collection using the identity_buckets policy and a PoolType defaulting to node_pool. More...
class	composable_allocator_traits< memory_pool_collection< Pool, BucketDist, RawAllocator > >
	Specialization of the composable_allocator_traits for memory_pool_collection classes. More...
struct	node_pool
	Tag type defining a memory pool optimized for nodes. More...
struct	array_pool
	Tag type defining a memory pool optimized for arrays. More...
struct	small_node_pool
	Tag type defining a memory pool optimized for small nodes. More...
class	memory_stack< BlockOrRawAllocator >
	A stateful RawAllocator that provides stack-like (LIFO) allocations. More...
class	memory_stack_raii_unwind< Stack >
	Simple utility that automatically unwinds a Stack to a previously saved location. More...
class	allocator_traits< memory_stack< BlockAllocator > >
	Specialization of the allocator_traits for memory_stack classes. More...
class	composable_allocator_traits< memory_stack< BlockAllocator > >
	Specialization of the composable_allocator_traits for memory_stack classes. More...
class	null_allocator
	A composable RawAllocator that will always fail. More...
struct	static_allocator_storage< Size >
	Storage for a static_allocator. More...
class	static_allocator
	A stateful RawAllocator that uses a fixed sized storage for the allocations. More...
class	static_block_allocator
	A BlockAllocator that allocates the blocks from a fixed size storage. More...
class	temporary_stack
	A wrapper around the memory_stack that is used by the temporary_allocator. More...
class	temporary_allocator
	A stateful RawAllocator that handles temporary allocations. More...
class	allocator_traits< temporary_allocator >
	Specialization of the allocator_traits for temporary_allocator classes. More...
class	virtual_memory_allocator
	A stateless RawAllocator that allocates memory using the virtual memory allocation functions. More...
class	virtual_block_allocator
	A BlockAllocator that reserves virtual memory and commits it part by part. More...

Macros
#define	FOONATHAN_MEMORY_TEMPORARY_STACK_MODE
	The mode of the automatic temporary_stack creation.

Typedefs
using	default_allocator
	The default RawAllocator that will be used as BlockAllocator in memory arenas.
using	heap_allocator
	A stateless RawAllocator that allocates memory from the heap.
using	malloc_allocator
	A stateless RawAllocator that allocates memory using std::malloc().
using	new_allocator
	A stateless RawAllocator that allocates memory using (nothrow) operator new.

Functions
void *	heap_alloc (std::size_t size) noexcept
	Allocates heap memory.
void	heap_dealloc (void *ptr, std::size_t size) noexcept
	Deallocates heap memory.
std::size_t	get_virtual_memory_page_size () noexcept
void *	virtual_memory_reserve (std::size_t no_pages) noexcept
	Reserves virtual memory.
void	virtual_memory_release (void *pages, std::size_t no_pages) noexcept
	Releases reserved virtual memory.
void *	virtual_memory_commit (void *memory, std::size_t no_pages) noexcept
	Commits reserved virtual memory.
void	virtual_memory_decommit (void *memory, std::size_t no_pages) noexcept
	Decommits commited virtual memory.

Variables
const std::size_t	virtual_memory_page_size
	The page size of the virtual memory.
template<typename T, class RawAllocator, typename... Args>
auto	allocate_joint (RawAllocator &alloc, joint_size additional_size, Args &&... args) -> joint_ptr< T, RawAllocator >
template<typename T, class RawAllocator, typename... Args>
auto	allocate_joint (const RawAllocator &alloc, joint_size additional_size, Args &&... args) -> joint_ptr< T, RawAllocator >
template<class RawAllocator, typename T>
auto	clone_joint (RawAllocator &alloc, const joint_type< T > &joint) -> joint_ptr< T, RawAllocator >
template<class RawAllocator, typename T>
auto	clone_joint (const RawAllocator &alloc, const joint_type< T > &joint) -> joint_ptr< T, RawAllocator >

Defines

FOONATHAN_MEMORY_TEMPORARY_STACK_MODE

#define FOONATHAN_MEMORY_TEMPORARY_STACK_MODE

The mode of the automatic temporary_stack creation.

Set to 2 to enable automatic lifetime management of the per-thread stack through nifty counter. Then all memory will be freed upon program termination automatically. Set to 1 to disable automatic lifetime managment of the per-thread stack, requires managing it through the temporary_stack_initializer. Set to 0 to disable the per-thread stack completely. get_temporary_stack() will abort the program upon call.

Typedefs

default_allocator

using default_allocator

The default RawAllocator that will be used as BlockAllocator in memory arenas.

Arena allocators like memory_stack or memory_pool allocate memory by subdividing a huge block. They get a BlockAllocator that will be used for their internal allocation, this type is the default value.

Required Behavior:

Its type can be changed via the CMake option FOONATHAN_MEMORY_DEFAULT_ALLOCATOR, but it must be one of the following: heap_allocator, new_allocator, malloc_allocator, static_allocator, virtual_memory_allocator.

Default Behavior:

The default is heap_allocator.

heap_allocator

using heap_allocator

A stateless RawAllocator that allocates memory from the heap.

It uses the two functions heap_alloc and heap_dealloc for the allocation, which default to std::malloc and std::free.

malloc_allocator

using malloc_allocator

A stateless RawAllocator that allocates memory using std::malloc().

It throws out_of_memory when the allocation fails.

new_allocator

using new_allocator

A stateless RawAllocator that allocates memory using (nothrow) operator new.

If the operator returns nullptr, it behaves like new and loops calling std::new_handler, but instead of throwing a std::bad_alloc exception, it throws out_of_memory.

Functions

heap_alloc()

void * heap_alloc ( std::size_t size )

noexcept

Allocates heap memory.

This function is used by the heap_allocator to allocate the heap memory. It is not defined on a freestanding implementation, a definition must be provided by the library user.

Required Behavior:

This function shall return a block of uninitialized memory that is aligned for max_align_t and has the given size. The size parameter will not be zero. It shall return a nullptr if no memory is available. It must be thread safe.

Default Behavior:

On a hosted implementation this function uses OS specific facilities, std::malloc is used as fallback.

heap_dealloc()

void heap_dealloc ( void * ptr, std::size_t size )

noexcept

Deallocates heap memory.

This function is used by the heap_allocator to allocate the heap memory. It is not defined on a freestanding implementation, a definition must be provided by the library user.

Required Behavior:

This function gets a pointer from a previous call to heap_alloc with the same size. It shall free the memory. The pointer will not be zero. It must be thread safe.

Default Behavior:

On a hosted implementation this function uses OS specific facilities, std::free is used as fallback.

allocate_joint() [1/2]

template<typename T, class RawAllocator, typename... Args>

auto allocate_joint	(	RawAllocator &	alloc,
		joint_size	additional_size,
		Args &&...	args ) -> joint_ptr<T, RawAllocator>

Returns:

A new joint_ptr as if created with the same arguments passed to the constructor.

clone_joint() [1/2]

template<class RawAllocator, typename T>

auto clone_joint	(	RawAllocator &	alloc,
		const joint_type< T > &	joint ) -> joint_ptr<T, RawAllocator>

Returns:

A new joint_ptr that points to a copy of joint. It will allocate as much memory as needed and forward to the copy constructor.

get_virtual_memory_page_size()

std::size_t get_virtual_memory_page_size ( )

noexcept

Returns:

the page size of the virtual memory. All virtual memory allocations must be multiple of this size. It is usually 4KiB.

virtual_memory_reserve()

void * virtual_memory_reserve ( std::size_t no_pages )

noexcept

Reserves virtual memory.

Effects:

Reserves the given number of pages. Each page is virtual_memory_page_size big.

Returns:

The address of the first reserved page, or nullptr in case of error.

Note

The memory may not be used, it must first be commited.

virtual_memory_release()

void virtual_memory_release ( void * pages, std::size_t no_pages )

noexcept

Releases reserved virtual memory.

Effects:

Returns previously reserved pages to the system.

Requires:

pages must come from a previous call to virtual_memory_reserve with the same calc_no_pages, it must not be nullptr.

virtual_memory_commit()

void * virtual_memory_commit ( void * memory, std::size_t no_pages )

noexcept

Commits reserved virtual memory.

Effects:

Marks calc_no_pages pages starting at the given address available for use.

Returns:

The beginning of the committed area, i.e. memory, or nullptr in case of error.

Requires:

The memory must be previously reserved.

virtual_memory_decommit()

void virtual_memory_decommit ( void * memory, std::size_t no_pages )

noexcept

Decommits commited virtual memory.

Effects:

Puts commited memory back in the reserved state.

Requires:

memory must come from a previous call to virtual_memory_commit with the same calc_no_pages it must not be nullptr.

allocate_joint() [2/2]

template<typename T, class RawAllocator, typename... Args>

auto allocate_joint	(	const RawAllocator &	alloc,
		joint_size	additional_size,
		Args &&...	args ) -> joint_ptr<T, RawAllocator>

Returns:

A new joint_ptr as if created with the same arguments passed to the constructor.

clone_joint() [2/2]

template<class RawAllocator, typename T>

auto clone_joint	(	const RawAllocator &	alloc,
		const joint_type< T > &	joint ) -> joint_ptr<T, RawAllocator>

Returns:

A new joint_ptr that points to a copy of joint. It will allocate as much memory as needed and forward to the copy constructor.

Variable Documentation

virtual_memory_page_size

const std::size_t virtual_memory_page_size

extern

The page size of the virtual memory.

All virtual memory allocations must be multiple of this size. It is usually 4KiB.

Deprecated

use get_virtual_memory_page_size instead.