Documentation of memory

( foonathan/memory)

Allocator implementations

Classes

class  joint
 Tag type that can't be created. More...
 
struct  joint_size
 Tag type to make the joint size more explicit. More...
 
class  joint_type< T >
 CRTP base class for all objects that want to use joint memory. More...
 
class  joint_ptr< T, RawAllocator, Mutex >
 A pointer to an object where all allocations are joint. More...
 
class  joint_allocator
 A RawAllocator that uses the additional joint memory for its allocation. More...
 
struct  is_shared_allocator< joint_allocator >
 Specialization of is_shared_allocator to mark joint_allocator as shared. More...
 
struct  propagation_traits< joint_allocator >
 Specialization of the propagation_traits for the joint_allocator. More...
 
class  joint_array< T >
 A zero overhead dynamic array using joint memory. More...
 
struct  node_pool
 Tag type defining a memory pool optimized for nodes. More...
 
struct  array_pool
 Tag type defining a memory pool optimized for arrays. More...
 
struct  small_node_pool
 Tag type defining a memory pool optimized for small nodes. More...
 
class  memory_stack< BlockOrRawAllocator >
 A stateful RawAllocator that provides stack-like (LIFO) allocations. More...
 
class  memory_stack_raii_unwind< Stack >
 Simple utility that automatically unwinds a Stack to a previously saved location. More...
 
class  allocator_traits< memory_stack< BlockAllocator > >
 Specialization of the allocator_traits for memory_stack classes. More...
 
class  composable_allocator_traits< memory_stack< BlockAllocator > >
 Specialization of the composable_allocator_traits for memory_stack classes. More...
 
struct  static_allocator_storage< Size >
 Storage for a static_allocator. More...
 
class  static_allocator
 A stateful RawAllocator that uses a fixed sized storage for the allocations. More...
 
class  static_block_allocator
 A BlockAllocator that allocates the blocks from a fixed size storage. More...
 
class  temporary_stack
 A wrapper around the memory_stack that is used by the temporary_allocator. More...
 
class  temporary_allocator
 A stateful RawAllocator that handles temporary allocations. More...
 
class  allocator_traits< temporary_allocator >
 Specialization of the allocator_traits for temporary_allocator classes. More...
 
class  virtual_memory_allocator
 A stateless RawAllocator that allocates memory using the virtual memory allocation functions. More...
 
class  virtual_block_allocator
 A BlockAllocator that reserves virtual memory and commits it part by part. More...
 

Macros

#define FOONATHAN_MEMORY_TEMPORARY_STACK_MODE
 The mode of the automatic temporary_stack creation. More...
 

Typedefs

using default_allocator = implementation_defined
 The default RawAllocator that will be used as BlockAllocator in memory arenas. More...
 
using heap_allocator = implementation_defined
 A stateless RawAllocator that allocates memory from the heap. More...
 
using malloc_allocator = implementation_defined
 A stateless RawAllocator that allocates memory using std::malloc(). More...
 
using new_allocator = implementation_defined
 A stateless RawAllocator that allocates memory using (nothrow) operator new. More...
 

Functions

void * heap_alloc (std::size_t size) noexcept
 Allocates heap memory. More...
 
void heap_dealloc (void *ptr, std::size_t size) noexcept
 Deallocates heap memory. More...
 
void * virtual_memory_reserve (std::size_t no_pages) noexcept
 Reserves virtual memory. More...
 
void virtual_memory_release (void *pages, std::size_t no_pages) noexcept
 Releases reserved virtual memory. More...
 
void * virtual_memory_commit (void *memory, std::size_t no_pages) noexcept
 Commits reserved virtual memory. More...
 
void virtual_memory_decommit (void *memory, std::size_t no_pages) noexcept
 Decommits commited virtual memory. More...
 

Variables

const std::size_t virtual_memory_page_size
 The page size of the virtual memory. More...
 
template<typename T , class RawAllocator , typename... Args>
auto allocate_joint (RawAllocator &alloc, joint_size additional_size, Args &&... args) -> joint_ptr< T, RawAllocator >
 
template<typename T , class RawAllocator , typename... Args>
auto allocate_joint (const RawAllocator &alloc, joint_size additional_size, Args &&... args) -> joint_ptr< T, RawAllocator >
 
template<class RawAllocator , typename T >
auto clone_joint (RawAllocator &alloc, const joint_type< T > &joint) -> joint_ptr< T, RawAllocator >
 
template<class RawAllocator , typename T >
auto clone_joint (const RawAllocator &alloc, const joint_type< T > &joint) -> joint_ptr< T, RawAllocator >
 

Defines

§ FOONATHAN_MEMORY_TEMPORARY_STACK_MODE

#define FOONATHAN_MEMORY_TEMPORARY_STACK_MODE

The mode of the automatic temporary_stack creation.

Set to 2 to enable automatic lifetime management of the per-thread stack through nifty counter. Then all memory will be freed upon program termination automatically. Set to 1 to disable automatic lifetime managment of the per-thread stack, requires managing it through the temporary_stack_initializer. Set to 0 to disable the per-thread stack completely. get_temporary_stack() will abort the program upon call.

Typedefs

§ default_allocator

using default_allocator = implementation_defined

The default RawAllocator that will be used as BlockAllocator in memory arenas.

Arena allocators like memory_stack or memory_pool allocate memory by subdividing a huge block. They get a BlockAllocator that will be used for their internal allocation, this type is the default value.

Required Behavior:
Its type can be changed via the CMake option FOONATHAN_MEMORY_DEFAULT_ALLCOATOR, but it must be one of the following: heap_allocator, new_allocator, malloc_allocator, static_allocator, virtual_memory_allocator.
Default Behavior:
The default is heap_allocator.

§ heap_allocator

using heap_allocator = implementation_defined

A stateless RawAllocator that allocates memory from the heap.

It uses the two functions heap_alloc and heap_dealloc for the allocation, which default to std::malloc and std::free.

§ malloc_allocator

using malloc_allocator = implementation_defined

A stateless RawAllocator that allocates memory using std::malloc().

It throws out_of_memory when the allocation fails.

§ new_allocator

using new_allocator = implementation_defined

A stateless RawAllocator that allocates memory using (nothrow) operator new.

If the operator returns nullptr, it behaves like new and loops calling std::new_handler, but instead of throwing a std::bad_alloc exception, it throws out_of_memory.

Functions

§ heap_alloc()

void* foonathan::memory::heap_alloc ( std::size_t  size)
noexcept

Allocates heap memory.

This function is used by the heap_allocator to allocate the heap memory. It is not defined on a freestanding implementation, a definition must be provided by the library user.

Required Behavior:
This function shall return a block of uninitialized memory that is aligned for max_align_t and has the given size. The size parameter will not be zero. It shall return a nullptr if no memory is available. It must be thread safe.
Default Behavior:
On a hosted implementation this function uses OS specific facilities, std::malloc is used as fallback.

§ heap_dealloc()

void foonathan::memory::heap_dealloc ( void *  ptr,
std::size_t  size 
)
noexcept

Deallocates heap memory.

This function is used by the heap_allocator to allocate the heap memory. It is not defined on a freestanding implementation, a definition must be provided by the library user.

Required Behavior:
This function gets a pointer from a previous call to heap_alloc with the same size. It shall free the memory. The pointer will not be zero. It must be thread safe.
Default Behavior:
On a hosted implementation this function uses OS specific facilities, std::free is used as fallback.

§ allocate_joint() [1/2]

auto allocate_joint ( RawAllocator &  alloc,
joint_size  additional_size,
Args &&...  args 
) -> joint_ptr<T, RawAllocator>
Returns:
A new joint_ptr as if created with the same arguments passed to the constructor.

§ clone_joint() [1/2]

auto foonathan::memory::clone_joint ( RawAllocator &  alloc,
const joint_type< T > &  joint 
) -> joint_ptr<T, RawAllocator>
Returns:
A new joint_ptr that points to a copy of joint. It will allocate as much memory as needed and forward to the copy constructor.

§ virtual_memory_reserve()

void* foonathan::memory::virtual_memory_reserve ( std::size_t  no_pages)
noexcept

Reserves virtual memory.

Effects:
Reserves the given number of pages. Each page is virtual_memory_page_size big.
Returns:
The address of the first reserved page, or nullptr in case of error.
Note
The memory may not be used, it must first be commited.

§ virtual_memory_release()

void foonathan::memory::virtual_memory_release ( void *  pages,
std::size_t  no_pages 
)
noexcept

Releases reserved virtual memory.

Effects:
Returns previously reserved pages to the system.
Requires:
pages must come from a previous call to virtual_memory_reserve with the same calc_no_pages, it must not be nullptr.

§ virtual_memory_commit()

void* foonathan::memory::virtual_memory_commit ( void *  memory,
std::size_t  no_pages 
)
noexcept

Commits reserved virtual memory.

Effects:
Marks calc_no_pages pages starting at the given address available for use.
Returns:
The beginning of the committed area, i.e. memory, or nullptr in case of error.
Requires:
The memory must be previously reserved.

§ virtual_memory_decommit()

void foonathan::memory::virtual_memory_decommit ( void *  memory,
std::size_t  no_pages 
)
noexcept

Decommits commited virtual memory.

Effects:
Puts commited memory back in the reserved state.
Requires:
memory must come from a previous call to virtual_memory_commit with the same calc_no_pages it must not be nullptr.

§ allocate_joint() [2/2]

auto foonathan::memory::allocate_joint ( const RawAllocator &  alloc,
joint_size  additional_size,
Args &&...  args 
) -> joint_ptr<T, RawAllocator>
Returns:
A new joint_ptr as if created with the same arguments passed to the constructor.

§ clone_joint() [2/2]

auto foonathan::memory::clone_joint ( const RawAllocator &  alloc,
const joint_type< T > &  joint 
) -> joint_ptr<T, RawAllocator>
Returns:
A new joint_ptr that points to a copy of joint. It will allocate as much memory as needed and forward to the copy constructor.

Variable Documentation

§ virtual_memory_page_size

const std::size_t virtual_memory_page_size

The page size of the virtual memory.

All virtual memory allocations must be multiple of this size. It is usually 4KiB.