Core components

## Classes

struct | allocator_is_raw_allocator< Allocator >
| Traits class that checks whether or not a standard `Allocator` can be used as RawAllocator. More...
struct | allocator_is_raw_allocator< std::allocator< T > >
| Specialization of allocator_is_raw_allocator that allows `std::allocator` again. More...
class | allocator_traits< Allocator >
| The default specialization of the allocator_traits for a RawAllocator. More...
struct | is_raw_allocator< T >
| Traits that check whether a type models concept RawAllocator. More...
class | composable_allocator_traits< Allocator >
| The default specialization of the composable_allocator_traits for a ComposableAllocator. More...
struct | is_composable_allocator< T >
| Traits that check whether a type models concept ComposableAllocator. More...
struct | allocator_info
| Contains information about an allocator. More...
class | out_of_memory
| The exception class thrown when a low level allocator runs out of memory. More...
class | out_of_fixed_memory
| A special case of out_of_memory errors thrown when a low-level allocator with a fixed size runs out of memory. More...
class | bad_allocation_size
| The exception class thrown when an allocation size is bigger than the supported maximum. More...
class | bad_node_size
| The exception class thrown when the node size exceeds the supported maximum, i.e. More...
class | bad_array_size
| The exception class thrown when the array size exceeds the supported maximum, i.e. More...
class | bad_alignment
| The exception class thrown when the alignment exceeds the supported maximum, i.e. More...
struct | memory_block
| A memory block. More...
struct | is_block_allocator< T >
| Traits that check whether a type models concept BlockAllocator. More...
class | memory_arena< BlockAllocator, Cached >
| A memory arena that manages huge memory blocks for a higher-level allocator. More...
struct | no_mutex
| A dummy `Mutex` class that does not lock anything. More...
struct | is_thread_safe_allocator< RawAllocator >
| Specifies whether or not a RawAllocator is thread safe as-is. More...

## Macros

#define | FOONATHAN_MEMORY_VERSION_MAJOR
| The major version number.
#define | FOONATHAN_MEMORY_VERSION_MINOR
| The minor version number.
#define | FOONATHAN_MEMORY_VERSION
| The total version number of the form `Mmm`.
#define | FOONATHAN_MEMORY_VERSION
| The total version number of the form `Mmm`.
#define | FOONATHAN_MEMORY_CHECK_ALLOCATION_SIZE
| Whether or not the allocation size will be checked, i.e.
#define | FOONATHAN_MEMORY_DEBUG_ASSERT
| Whether or not internal assertions in the library are enabled.
#define | FOONATHAN_MEMORY_DEBUG_FILL
| Whether or not allocated memory will be filled with special values.
#define | FOONATHAN_MEMORY_DEBUG_FENCE
| The size of the fence memory, it has no effect if FOONATHAN_MEMORY_DEBUG_FILL is `false`.
#define | FOONATHAN_MEMORY_DEBUG_LEAK_CHECK
| Whether or not leak checking is enabled.
#define | FOONATHAN_MEMORY_DEBUG_POINTER_CHECK
| Whether or not the deallocation functions will check for pointers that were never allocated by an allocator.
#define | FOONATHAN_MEMORY_DEBUG_DOUBLE_DEALLOC_CHECK
| Whether or not the deallocation functions will check for double free errors.
#define | FOONATHAN_MEMORY_NAMESPACE_PREFIX
| Whether or not everything is in namespace `foonathan::memory`.

## Typedefs

using | leak_handler = void(*)(const allocator_info &info, std::ptrdiff_t amount)
| The type of the handler called when a memory leak is detected.
using | invalid_pointer_handler = void(*)(const allocator_info &info, const void *ptr)
| The type of the handler called when an invalid pointer is passed to a deallocation function.
using | buffer_overflow_handler = void(*)(const void *memory, std::size_t size, const void *write_ptr)
| The type of the handler called when a buffer under/overflow is detected.
template<class BlockOrRawAllocator , template< typename... > class BlockAllocator = detail::default_block_wrapper>
using | make_block_allocator_t = implementation_defined
| Takes either a BlockAllocator or a RawAllocator.

## Enumerations

enum class | debug_magic : unsigned char { internal_memory , internal_freed_memory , new_memory , freed_memory , alignment_memory , fence_memory }
| The magic values that are used for debug filling. More...

## Functions

leak_handler | set_leak_handler (leak_handler h)
| Exchanges the leak_handler.
leak_handler | get_leak_handler ()
| Returns the leak_handler.
invalid_pointer_handler | set_invalid_pointer_handler (invalid_pointer_handler h)
| Exchanges the invalid_pointer_handler.
invalid_pointer_handler | get_invalid_pointer_handler ()
| Returns the invalid_pointer_handler.
buffer_overflow_handler | set_buffer_overflow_handler (buffer_overflow_handler h)
| Exchanges the buffer_overflow_handler.
buffer_overflow_handler | get_buffer_overflow_handler ()
| Returns the buffer_overflow_handler.
constexpr bool | cached_arena
constexpr bool | uncached_arena
template<class BlockOrRawAllocator , typename... Args>
make_block_allocator_t< BlockOrRawAllocator > | make_block_allocator (std::size_t block_size, Args &&... args)
template<template< class... > class BlockAllocator, class BlockOrRawAllocator , typename... Args>
make_block_allocator_t< BlockOrRawAllocator, BlockAllocator > | make_block_allocator (std::size_t block_size, Args &&... args)

## Defines

## FOONATHAN_MEMORY_VERSION_MAJOR

#define FOONATHAN_MEMORY_VERSION_MAJOR

The major version number.

## FOONATHAN_MEMORY_VERSION_MINOR

#define FOONATHAN_MEMORY_VERSION_MINOR

The minor version number.

## FOONATHAN_MEMORY_VERSION [1/2]

#define FOONATHAN_MEMORY_VERSION

The total version number of the form `Mmm`.

## FOONATHAN_MEMORY_VERSION [2/2]

#define FOONATHAN_MEMORY_VERSION

The total version number of the form `Mmm`.

## FOONATHAN_MEMORY_CHECK_ALLOCATION_SIZE

#define FOONATHAN_MEMORY_CHECK_ALLOCATION_SIZE

Whether or not the allocation size will be checked, i.e.

the foonathan::memory::bad_allocation_size thrown.

## FOONATHAN_MEMORY_DEBUG_ASSERT

#define FOONATHAN_MEMORY_DEBUG_ASSERT

Whether or not internal assertions in the library are enabled.

## FOONATHAN_MEMORY_DEBUG_FILL

#define FOONATHAN_MEMORY_DEBUG_FILL

Whether or not allocated memory will be filled with special values.

## FOONATHAN_MEMORY_DEBUG_FENCE

#define FOONATHAN_MEMORY_DEBUG_FENCE

The size of the fence memory, it has no effect if FOONATHAN_MEMORY_DEBUG_FILL is `false`.

Note
  For most allocators, the actual value doesn't matter and they use appropriate defaults to ensure alignment etc.

## FOONATHAN_MEMORY_DEBUG_LEAK_CHECK

#define FOONATHAN_MEMORY_DEBUG_LEAK_CHECK

Whether or not leak checking is enabled.

## FOONATHAN_MEMORY_DEBUG_POINTER_CHECK

#define FOONATHAN_MEMORY_DEBUG_POINTER_CHECK

Whether or not the deallocation functions will check for pointers that were never allocated by an allocator.

## FOONATHAN_MEMORY_DEBUG_DOUBLE_DEALLOC_CHECK

#define FOONATHAN_MEMORY_DEBUG_DOUBLE_DEALLOC_CHECK

Whether or not the deallocation functions will check for double free errors.

This option makes no sense if FOONATHAN_MEMORY_DEBUG_POINTER_CHECK is `false`.

## FOONATHAN_MEMORY_NAMESPACE_PREFIX

#define FOONATHAN_MEMORY_NAMESPACE_PREFIX

Whether or not everything is in namespace `foonathan::memory`.

If `false`, a namespace alias `namespace memory = foonathan::memory` is automatically inserted into each header, allowing to qualify everything with `foonathan::`.

Note
  This option breaks in combination with using `using namespace foonathan;`.

## Typedefs

## leak_handler

using leak_handler = void (*)(const allocator_info& info, std::ptrdiff_t amount)

The type of the handler called when a memory leak is detected.

Leak checking can be controlled via the option FOONATHAN_MEMORY_DEBUG_LEAK_CHECK and only affects calls through the allocator_traits, not direct calls. The handler gets the allocator_info and the amount of memory leaked. This can also be negative, meaning that more memory has been freed than allocated.

Required Behavior:
  A leak handler shall log the leak, abort the program, do nothing or anything else that seems appropriate. It must not throw any exceptions since it is called in the cleanup process.

Default Behavior:
  On a hosted implementation it logs the leak to `stderr` and returns, continuing execution. On a freestanding implementation it does nothing.

## invalid_pointer_handler

using invalid_pointer_handler = void (*)(const allocator_info& info, const void* ptr)

The type of the handler called when an invalid pointer is passed to a deallocation function.

Pointer checking can be controlled via the options FOONATHAN_MEMORY_DEBUG_POINTER_CHECK and FOONATHAN_MEMORY_DEBUG_DOUBLE_DEALLOC_CHECK. The handler gets the allocator_info and the invalid pointer.

Required Behavior:
  An invalid pointer handler shall terminate the program. It must not throw any exceptions since it might be called in the cleanup process.

Default Behavior:
  On a hosted implementation it logs the information to `stderr` and calls `std::abort()`. On a freestanding implementation it only calls `std::abort()`.

## buffer_overflow_handler

using buffer_overflow_handler = void (*)(const void* memory, std::size_t size, const void* write_ptr)

The type of the handler called when a buffer under/overflow is detected.

If FOONATHAN_MEMORY_DEBUG_FILL is `true` and FOONATHAN_MEMORY_DEBUG_FENCE has a non-zero value the allocator classes check if a write into the fence has occured upon deallocation. The handler gets the memory block belonging to the corrupted fence, its size and the exact address.

Required Behavior:
  A buffer overflow handler shall terminate the program. It must not throw any exceptions since it me be called in the cleanup process.

Default Behavior:
  On a hosted implementation it logs the information to `stderr` and calls `std::abort()`. On a freestanding implementation it only calls `std::abort()`.

## make_block_allocator_t

template<class BlockOrRawAllocator , template< typename... > class BlockAllocator = detail::default_block_wrapper>

using make_block_allocator_t = implementation_defined

Takes either a BlockAllocator or a RawAllocator.

In the first case simply aliases the type unchanged, in the second to growing_block_allocator (or the template in `BlockAllocator`) with the RawAllocator. Using this allows passing normal RawAllocators as BlockAllocators.

## Enumerations

## debug_magic

enum class debug_magic : unsigned char

strong

The magic values that are used for debug filling.

If FOONATHAN_MEMORY_DEBUG_FILL is `true`, memory will be filled to help detect use-after-free or missing initialization errors. These are the constants for the different types.

Enumerator
internal_memory | Marks internal memory used by the allocator - "allocated block".
internal_freed_memory | Marks internal memory currently not used by the allocator - "freed block".
new_memory | Marks allocated, but not yet used memory - "clean memory".
freed_memory | Marks freed memory - "dead memory".
alignment_memory | Marks buffer memory used to ensure proper alignment. This memory can also serve as debug_magic::fence_memory.
fence_memory | Marks buffer memory used to protect against overflow - "fence memory". The option FOONATHAN_MEMORY_DEBUG_FENCE controls the size of a memory fence that will be placed before or after a memory block. It helps catching buffer overflows.

## Functions

## set_leak_handler()

leak_handler set_leak_handler | ( | leak_handler | h | ) |

Exchanges the leak_handler.

Effects:
  Sets `h` as the new leak_handler in an atomic operation. A `nullptr` sets the default leak_handler.

Returns:
  The previous leak_handler. This is never `nullptr`.

## get_leak_handler()

leak_handler get_leak_handler | ( |  | ) |

Returns the leak_handler.

Returns:
  The current leak_handler. This is never `nullptr`.

## set_invalid_pointer_handler()

invalid_pointer_handler set_invalid_pointer_handler | ( | invalid_pointer_handler | h | ) |

Exchanges the invalid_pointer_handler.

Effects:
  Sets `h` as the new invalid_pointer_handler in an atomic operation. A `nullptr` sets the default invalid_pointer_handler.

Returns:
  The previous invalid_pointer_handler. This is never `nullptr`.

## get_invalid_pointer_handler()

invalid_pointer_handler get_invalid_pointer_handler | ( |  | ) |

Returns the invalid_pointer_handler.

Returns:
  The current invalid_pointer_handler. This is never `nullptr`.

## set_buffer_overflow_handler()

buffer_overflow_handler set_buffer_overflow_handler | ( | buffer_overflow_handler | h | ) |

Exchanges the buffer_overflow_handler.

Effects:
  Sets `h` as the new buffer_overflow_handler in an atomic operation. A `nullptr` sets the default buffer_overflow_handler.

Returns:
  The previous buffer_overflow_handler. This is never `nullptr`.

## get_buffer_overflow_handler()

buffer_overflow_handler get_buffer_overflow_handler | ( |  | ) |

Returns the buffer_overflow_handler.

Returns:
  The current buffer_overflow_handler. This is never `nullptr`.

## make_block_allocator() [1/2]

template<class BlockOrRawAllocator , typename... Args>

make_block_allocator_t< BlockOrRawAllocator > make_block_allocator | ( | std::size_t | block_size,
|  | Args &&... | args
| ) |  |

Helper function make a BlockAllocator.

Returns:
  A BlockAllocator of the given type created with the given arguments.

Requires:
  Same requirements as the constructor.

## make_block_allocator() [2/2]

template<template< class... > class BlockAllocator, class BlockOrRawAllocator , typename... Args>

make_block_allocator_t< BlockOrRawAllocator, BlockAllocator > make_block_allocator | ( | std::size_t | block_size,
|  | Args &&... | args
| ) |  |

Helper function make a BlockAllocator.

Returns:
  A BlockAllocator of the given type created with the given arguments.

Requires:
  Same requirements as the constructor.

## Variable Documentation

## cached_arena

constexpr bool cached_arena

constexpr

Controls the caching of memory_arena. By default, deallocated blocks are put onto a cache, so they can be reused later; this tag value enable/disable it..
This can be useful, e.g. if there will never be blocks available for deallocation. The (tiny) overhead for the cache can then be disabled. An example is memory_pool.

## uncached_arena

constexpr bool uncached_arena

constexpr

Controls the caching of memory_arena. By default, deallocated blocks are put onto a cache, so they can be reused later; this tag value enable/disable it..
This can be useful, e.g. if there will never be blocks available for deallocation. The (tiny) overhead for the cache can then be disabled. An example is memory_pool.