Core components

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

Macros
#define	WPI_MEMORY_VERSION_MAJOR   1
	The major version number.
#define	WPI_MEMORY_VERSION_MINOR   1
	The minor version number.
#define	WPI_MEMORY_VERSION    (WPI_MEMORY_VERSION_MAJOR * 100 + WPI_MEMORY_VERSION_MINOR)
	The total version number of the form Mmm.
#define	WPI_MEMORY_VERSION    (WPI_MEMORY_VERSION_MAJOR * 100 + WPI_MEMORY_VERSION_MINOR)
	The total version number of the form Mmm.
#define	WPI_MEMORY_CHECK_ALLOCATION_SIZE   1
	Whether or not the allocation size will be checked, i.e.
#define	WPI_MEMORY_DEBUG_ASSERT   1
	Whether or not internal assertions in the library are enabled.
#define	WPI_MEMORY_DEBUG_FILL   1
	Whether or not allocated memory will be filled with special values.
#define	WPI_MEMORY_DEBUG_FENCE   1
	The size of the fence memory, it has no effect if WPI_MEMORY_DEBUG_FILL is false.
#define	WPI_MEMORY_DEBUG_LEAK_CHECK   1
	Whether or not leak checking is enabled.
#define	WPI_MEMORY_DEBUG_POINTER_CHECK   1
	Whether or not the deallocation functions will check for pointers that were never allocated by an allocator.
#define	WPI_MEMORY_DEBUG_DOUBLE_DEALLOC_CHECK   1
	Whether or not the deallocation functions will check for double free errors.
#define	WPI_MEMORY_NAMESPACE_PREFIX   1
	Whether or not everything is in namespace wpi::memory.

Typedefs
template<class BlockOrRawAllocator , template< typename... > class BlockAllocator = detail::default_block_wrapper>
using	wpi::memory::make_block_allocator_t
	Takes either a BlockAllocator or a RawAllocator.
using	wpi::memory::leak_handler = void (*)(const allocator_info& info, std::ptrdiff_t amount)
	The type of the handler called when a memory leak is detected.
using	wpi::memory::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	wpi::memory::buffer_overflow_handler
	The type of the handler called when a buffer under/overflow is detected.

Enumerations
enum class	wpi::memory::debug_magic : unsigned char {   wpi::memory::debug_magic::internal_memory = 0xAB , wpi::memory::debug_magic::internal_freed_memory = 0xFB , wpi::memory::debug_magic::new_memory = 0xCD , wpi::memory::debug_magic::freed_memory = 0xDD ,   wpi::memory::debug_magic::alignment_memory = 0xED , wpi::memory::debug_magic::fence_memory = 0xFD }
	The magic values that are used for debug filling. More...

Functions
leak_handler	wpi::memory::set_leak_handler (leak_handler h)
	Exchanges the leak_handler.
leak_handler	wpi::memory::get_leak_handler ()
	Returns the leak_handler.
invalid_pointer_handler	wpi::memory::set_invalid_pointer_handler (invalid_pointer_handler h)
	Exchanges the invalid_pointer_handler.
invalid_pointer_handler	wpi::memory::get_invalid_pointer_handler ()
	Returns the invalid_pointer_handler.
buffer_overflow_handler	wpi::memory::set_buffer_overflow_handler (buffer_overflow_handler h)
	Exchanges the buffer_overflow_handler.
buffer_overflow_handler	wpi::memory::get_buffer_overflow_handler ()
	Returns the buffer_overflow_handler.
constexpr bool	wpi::memory::cached_arena = true
constexpr bool	wpi::memory::uncached_arena = false
template<class BlockOrRawAllocator , typename... Args>
make_block_allocator_t< BlockOrRawAllocator >	wpi::memory::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 >	wpi::memory::make_block_allocator (std::size_t block_size, Args &&... args)
constexpr std::size_t	wpi::memory::literals::operator""_KiB (unsigned long long value) noexcept
	Syntax sugar to express sizes with unit prefixes.
constexpr std::size_t	wpi::memory::literals::operator""_KB (unsigned long long value) noexcept
constexpr std::size_t	wpi::memory::literals::operator""_MiB (unsigned long long value) noexcept
constexpr std::size_t	wpi::memory::literals::operator""_MB (unsigned long long value) noexcept
constexpr std::size_t	wpi::memory::literals::operator""_GiB (unsigned long long value) noexcept
constexpr std::size_t	wpi::memory::literals::operator""_GB (unsigned long long value) noexcept

Detailed Description

Macro Definition Documentation

WPI_MEMORY_CHECK_ALLOCATION_SIZE

#define WPI_MEMORY_CHECK_ALLOCATION_SIZE   1

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

the wpi::memory::bad_allocation_size thrown.

WPI_MEMORY_DEBUG_ASSERT

#define WPI_MEMORY_DEBUG_ASSERT   1

Whether or not internal assertions in the library are enabled.

WPI_MEMORY_DEBUG_DOUBLE_DEALLOC_CHECK

#define WPI_MEMORY_DEBUG_DOUBLE_DEALLOC_CHECK   1

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

This option makes no sense if WPI_MEMORY_DEBUG_POINTER_CHECK is false.

WPI_MEMORY_DEBUG_FENCE

#define WPI_MEMORY_DEBUG_FENCE   1

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

Note

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

WPI_MEMORY_DEBUG_FILL

#define WPI_MEMORY_DEBUG_FILL   1

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

WPI_MEMORY_DEBUG_LEAK_CHECK

#define WPI_MEMORY_DEBUG_LEAK_CHECK   1

Whether or not leak checking is enabled.

WPI_MEMORY_DEBUG_POINTER_CHECK

#define WPI_MEMORY_DEBUG_POINTER_CHECK   1

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

WPI_MEMORY_NAMESPACE_PREFIX

#define WPI_MEMORY_NAMESPACE_PREFIX   1

Whether or not everything is in namespace wpi::memory.

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

Note

This option breaks in combination with using using namespace wpi;.

WPI_MEMORY_VERSION [1/2]

#define WPI_MEMORY_VERSION    (WPI_MEMORY_VERSION_MAJOR * 100 + WPI_MEMORY_VERSION_MINOR)

The total version number of the form Mmm.

WPI_MEMORY_VERSION [2/2]

#define WPI_MEMORY_VERSION    (WPI_MEMORY_VERSION_MAJOR * 100 + WPI_MEMORY_VERSION_MINOR)

The total version number of the form Mmm.

WPI_MEMORY_VERSION_MAJOR

#define WPI_MEMORY_VERSION_MAJOR   1

The major version number.

WPI_MEMORY_VERSION_MINOR

#define WPI_MEMORY_VERSION_MINOR   1

The minor version number.

Typedef Documentation

buffer_overflow_handler

using wpi::memory::buffer_overflow_handler

Initial value:

 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 WPI_MEMORY_DEBUG_FILL is true and WPI_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().

invalid_pointer_handler

using wpi::memory::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 WPI_MEMORY_DEBUG_POINTER_CHECK and WPI_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().

leak_handler

using wpi::memory::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 WPI_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.

make_block_allocator_t

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

using wpi::memory::make_block_allocator_t

Initial value:

 
 
 
 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.

Enumeration Type Documentation

debug_magic

enum class wpi::memory::debug_magic : unsigned char

strong

The magic values that are used for debug filling.

If WPI_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 WPI_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.

Function Documentation

get_buffer_overflow_handler()

buffer_overflow_handler wpi::memory::get_buffer_overflow_handler

(

)

Returns the buffer_overflow_handler.

Returns:

The current buffer_overflow_handler. This is never nullptr.

get_invalid_pointer_handler()

invalid_pointer_handler wpi::memory::get_invalid_pointer_handler

(

)

Returns the invalid_pointer_handler.

Returns:

The current invalid_pointer_handler. This is never nullptr.

get_leak_handler()

leak_handler wpi::memory::get_leak_handler

(

)

Returns the leak_handler.

Returns:

The current leak_handler. This is never nullptr.

make_block_allocator() [1/2]

template<class BlockOrRawAllocator , typename... Args>

make_block_allocator_t< BlockOrRawAllocator > wpi::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]

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

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

operator""_GB()

std::size_t wpi::memory::literals::operator""_GB ( unsigned long long value )

constexprnoexcept

operator""_GiB()

std::size_t wpi::memory::literals::operator""_GiB ( unsigned long long value )

constexprnoexcept

operator""_KB()

std::size_t wpi::memory::literals::operator""_KB ( unsigned long long value )

constexprnoexcept

operator""_KiB()

std::size_t wpi::memory::literals::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.

operator""_MB()

std::size_t wpi::memory::literals::operator""_MB ( unsigned long long value )

constexprnoexcept

operator""_MiB()

std::size_t wpi::memory::literals::operator""_MiB ( unsigned long long value )

constexprnoexcept

set_buffer_overflow_handler()

buffer_overflow_handler wpi::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.

set_invalid_pointer_handler()

invalid_pointer_handler wpi::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.

set_leak_handler()

leak_handler wpi::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.

Variable Documentation

cached_arena

bool wpi::memory::cached_arena = true

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

bool wpi::memory::uncached_arena = false

constexpr