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)
constexpr std::size_t	operator""_KiB (unsigned long long value) noexcept
	Syntax sugar to express sizes with unit prefixes.
constexpr std::size_t	operator""_KB (unsigned long long value) noexcept
	Syntax sugar to express sizes with unit prefixes.
constexpr std::size_t	operator""_MiB (unsigned long long value) noexcept
	Syntax sugar to express sizes with unit prefixes.
constexpr std::size_t	operator""_MB (unsigned long long value) noexcept
	Syntax sugar to express sizes with unit prefixes.
constexpr std::size_t	operator""_GiB (unsigned long long value) noexcept
	Syntax sugar to express sizes with unit prefixes.
constexpr std::size_t	operator""_GB (unsigned long long value) noexcept
	Syntax sugar to express sizes with unit prefixes.

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

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]

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.

operator""_KiB()

constexpr std::size_t operator""_KiB ( unsigned long long  value )

constexprnoexcept

Syntax sugar to express sizes with unit prefixes.

Returns:

The number of bytes value is in the given unit.

make_block_allocator() [2/2]

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.

operator""_KB()

constexpr std::size_t operator""_KB ( unsigned long long  value )

constexprnoexcept

Syntax sugar to express sizes with unit prefixes.

Returns:

The number of bytes value is in the given unit.

operator""_MiB()

constexpr std::size_t operator""_MiB ( unsigned long long  value )

constexprnoexcept

Syntax sugar to express sizes with unit prefixes.

Returns:

The number of bytes value is in the given unit.

operator""_MB()

constexpr std::size_t operator""_MB ( unsigned long long  value )

constexprnoexcept

Syntax sugar to express sizes with unit prefixes.

Returns:

The number of bytes value is in the given unit.

operator""_GiB()

constexpr std::size_t operator""_GiB ( unsigned long long  value )

constexprnoexcept

Syntax sugar to express sizes with unit prefixes.

Returns:

The number of bytes value is in the given unit.

operator""_GB()

constexpr std::size_t operator""_GB ( unsigned long long  value )

constexprnoexcept

Syntax sugar to express sizes with unit prefixes.

Returns:

The number of bytes value is in the given unit.

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.