Documentation of memory

( foonathan/memory)

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

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. More...
 
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. More...
 
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. More...
 
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. More...
 
using default_mutex = no_mutex
 The default Mutex type used as default template paremeter in, e.g. More...
 

Enumerations

enum  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. More...
 
leak_handler get_leak_handler ()
 Returns the leak_handler. More...
 
invalid_pointer_handler set_invalid_pointer_handler (invalid_pointer_handler h)
 Exchanges the invalid_pointer_handler. More...
 
invalid_pointer_handler get_invalid_pointer_handler ()
 Returns the invalid_pointer_handler. More...
 
buffer_overflow_handler set_buffer_overflow_handler (buffer_overflow_handler h)
 Exchanges the buffer_overflow_handler. More...
 
buffer_overflow_handler get_buffer_overflow_handler ()
 Returns the buffer_overflow_handler. More...
 
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 bad_allocation_size thrown.

§ FOONATHAN_MEMORY_THREAD_SAFE_REFERENCE

#define FOONATHAN_MEMORY_THREAD_SAFE_REFERENCE

Whether or not the foonathan::memory::default_mutex will be std::mutex or foonathan::memory::no_mutex.

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

§ default_mutex

The default Mutex type used as default template paremeter in, e.g.

allocator_reference. If the CMake option FOONATHAN_MEMORY_THREAD_SAFE_REFERENCE is true and there is threading support, it is std::mutex, else no_mutex.

Enumerations

§ debug_magic

enum 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 foonathan::memory::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 foonathan::memory::get_leak_handler ( )

Returns the leak_handler.

Returns:
The current leak_handler. This is never nullptr.

§ set_invalid_pointer_handler()

invalid_pointer_handler foonathan::memory::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 foonathan::memory::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 foonathan::memory::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 foonathan::memory::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> foonathan::memory::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]

make_block_allocator_t<BlockOrRawAllocator, BlockAllocator> foonathan::memory::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

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

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.