Allocator implementations

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

Macros
#define	WPI_MEMORY_TEMPORARY_STACK_MODE   2
	The mode of the automatic wpi::memory::temporary_stack creation.

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

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

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

Detailed Description

Macro Definition Documentation

WPI_MEMORY_TEMPORARY_STACK_MODE

#define WPI_MEMORY_TEMPORARY_STACK_MODE   2

The mode of the automatic wpi::memory::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 wpi::memory::temporary_stack_initializer. Set to 0 to disable the per-thread stack completely. wpi::memory::get_temporary_stack() will abort the program upon call.

Typedef Documentation

default_allocator

using wpi::memory::default_allocator = implementation_defined

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 WPI_MEMORY_DEFAULT_ALLCOATOR, 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 wpi::memory::heap_allocator

Initial value:

 
             implementation_defined

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 wpi::memory::malloc_allocator

Initial value:

 
             implementation_defined

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

It throws out_of_memory when the allocation fails.

new_allocator

using wpi::memory::new_allocator

Initial value:

 
             implementation_defined

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.

Function Documentation

allocate_joint() [1/2]

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

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

allocate_joint() [2/2]

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

auto wpi::memory::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 wpi::memory::clone_joint	(	const RawAllocator &	alloc,
		const joint_type< T > &	joint ) -> joint_ptr<T, RawAllocator>

clone_joint() [2/2]

template<class RawAllocator , typename T >

auto wpi::memory::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 wpi::memory::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.

heap_alloc()

void * wpi::memory::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 wpi::memory::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.

virtual_memory_commit()

void * wpi::memory::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 wpi::memory::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.

virtual_memory_release()

void wpi::memory::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_reserve()

void * wpi::memory::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.

Variable Documentation

virtual_memory_page_size

const std::size_t wpi::memory::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.