memory_arena< BlockAllocator, Cached > Class Template Reference
Core components

## Detailed Description

template<class BlockAllocator, bool Cached>
class foonathan::memory::memory_arena< BlockAllocator, Cached >

A memory arena that manages huge memory blocks for a higher-level allocator.

Some allocators like memory_stack work on huge memory blocks, this class manages them fro those allocators. It uses a BlockAllocator for the allocation of those blocks. The memory blocks in use are put onto a stack like structure, deallocation will pop from the top, so it is only possible to deallocate the last allocated block of the arena. By default, blocks are not really deallocated but stored in a cache. This can be disabled with the second template parameter, passing it uncached_arena (or `false`) disables it, cached_arena (or `true`) enables it explicitly.

## Typedefs

using | allocator_type = BlockAllocator
using | is_cached = std::integral_constant< bool, Cached >

## Static Functions

static constexpr std::size_t | min_block_size (std::size_t byte_size) noexcept

## Member Functions

template<typename... Args>
| memory_arena (std::size_t block_size, Args &&... args)
| ~memory_arena () noexcept
memory_block | allocate_block ()
memory_block | current_block () const noexcept
void | deallocate_block () noexcept
bool | owns (const void *ptr) const noexcept
void | shrink_to_fit () noexcept
std::size_t | capacity () const noexcept
std::size_t | cache_size () const noexcept
std::size_t | size () const noexcept
std::size_t | next_block_size () const noexcept
allocator_type & | get_allocator () noexcept
| memory_arena (memory_arena &&other) noexcept
memory_arena & | operator= (memory_arena &&other) noexcept

## Constructors

## memory_arena() [1/2]

template<class BlockAllocator , bool Cached>
template<typename... Args>

memory_arena | ( | std::size_t | block_size,
|  | Args &&... | args
| ) |  |

explicit

Effects:
  Creates it by giving it the size and other arguments for the BlockAllocator. It forwards these arguments to its constructor.

Requires:
  `block_size` must be greater than `min_block_size(0)` and other requirements depending on the BlockAllocator.

Throws:
  Anything thrown by the constructor of the `BlockAllocator`.

## ~memory_arena()

template<class BlockAllocator , bool Cached>

~memory_arena | ( |  | ) |

noexcept

Effects:
  Deallocates all memory blocks that where requested back to the BlockAllocator.

## memory_arena() [2/2]

template<class BlockAllocator , bool Cached>

memory_arena | ( | memory_arena< BlockAllocator, Cached > && | other | ) |

noexcept

Effects:
  Moves the arena. The new arena takes ownership over all the memory blocks from the other arena object, which is empty after that. This does not invalidate any memory blocks.

## Member Functions

## min_block_size()

template<class BlockAllocator , bool Cached>

static constexpr std::size_t min_block_size | ( | std::size_t | byte_size | ) |

static constexpr noexcept

Returns:
  The minimum block size required for an arena containing the given amount of memory. If an arena is created with the result of `min_block_size(n)`, the resulting capacity will be exactly `n`.

Requires:
  `byte_size` must be a positive number.

## operator=()

template<class BlockAllocator , bool Cached>

memory_arena & operator= | ( | memory_arena< BlockAllocator, Cached > && | other | ) |

noexcept

Effects:
  Moves the arena. The new arena takes ownership over all the memory blocks from the other arena object, which is empty after that. This does not invalidate any memory blocks.

## allocate_block()

template<class BlockAllocator , bool Cached>

memory_block allocate_block | ( |  | ) |

Effects:
  Allocates a new memory block. It first uses a cache of previously deallocated blocks, if caching is enabled, if it is empty, allocates a new one.

Returns:
  The new memory_block.

Throws:
  Anything thrown by the BlockAllocator allocation function.

## current_block()

template<class BlockAllocator , bool Cached>

memory_block current_block | ( |  | ) | const

noexcept

Returns:
  The current memory block. This is the memory block that will be deallocated by the next call to deallocate_block().

## deallocate_block()

template<class BlockAllocator , bool Cached>

void deallocate_block | ( |  | ) |

noexcept

Effects:
  Deallocates the current memory block. The current memory block is the block on top of the stack of blocks. If caching is enabled, it does not really deallocate it but puts it onto a cache for later use, use shrink_to_fit() to purge that cache.

## owns()

template<class BlockAllocator , bool Cached>

bool owns | ( | const void * | ptr | ) | const

noexcept

Returns:
  If `ptr` is in memory owned by the arena.

## shrink_to_fit()

template<class BlockAllocator , bool Cached>

void shrink_to_fit | ( |  | ) |

noexcept

Effects:
  Purges the cache of unused memory blocks by returning them. The memory blocks will be deallocated in reversed order of allocation. Does nothing if caching is disabled.

## capacity()

template<class BlockAllocator , bool Cached>

std::size_t capacity | ( |  | ) | const

noexcept

Returns:
  The capacity of the arena, i.e. how many blocks are used and cached.

## cache_size()

template<class BlockAllocator , bool Cached>

std::size_t cache_size | ( |  | ) | const

noexcept

Returns:
  The size of the cache, i.e. how many blocks can be allocated without allocation.

## size()

template<class BlockAllocator , bool Cached>

std::size_t size | ( |  | ) | const

noexcept

Returns:
  The size of the arena, i.e. how many blocks are in use. It is always smaller or equal to the capacity().

## next_block_size()

template<class BlockAllocator , bool Cached>

std::size_t next_block_size | ( |  | ) | const

noexcept

Returns:
  The size of the next memory block, i.e. of the next call to allocate_block(). If there are blocks in the cache, returns size of the next one. Otherwise forwards to the BlockAllocator and subtracts an implementation offset.

## get_allocator()

template<class BlockAllocator , bool Cached>

allocator_type & get_allocator | ( |  | ) |

noexcept

Returns:
  A reference of the BlockAllocator object.

Requires:
  It is undefined behavior to move this allocator out into another object.