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 | allocator_traits< memory_pool_collection< Pool, BucketDist, RawAllocator > >
| Specialization of the allocator_traits for memory_pool_collection classes. 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 foonathan::memory::temporary_stack creation.

## Typedefs

using | default_allocator = implementation_defined
| The default RawAllocator that will be used as BlockAllocator in memory arenas.
using | heap_allocator = implementation_defined
| A stateless RawAllocator that allocates memory from the heap.
using | malloc_allocator = implementation_defined
| A stateless RawAllocator that allocates memory using `std::malloc()`.
using | new_allocator = implementation_defined
| 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 foonathan::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 foonathan::memory::temporary_stack_initializer. Set to `0` to disable the per-thread stack completely. foonathan::memory::get_temporary_stack() will abort the program upon call.

## Typedefs

## default_allocator

using 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 `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 = 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 malloc_allocator = implementation_defined

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

It throws out_of_memory when the allocation fails.

## new_allocator

using new_allocator = 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.

## 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.