hxmemory_manager.h File Reference

Go to the source code of this file.

Classes
class	hxsystem_allocator_scope
class	hxdefault_delete
class	hxdo_not_delete
class	hxconsteval_delete
class	hxmemory_manager_stats

Typedefs
typedef int	hxsystem_allocator_t

Enumerations
enum	{ hxsystem_allocator_current = -1 , hxsystem_allocator_heap , hxsystem_allocator_permanent , hxsystem_allocator_stack_0 }

Functions
void	hxfree (void *ptr_) hxattr_noexcept hxattr_hot
	hxattr_allocator (hxfree) hxattr_noexcept hxattr_hot void *hxmalloc(size_t size_)
HX_C_END_ hxinline void *	hxmalloc (size_t size_, hxsystem_allocator_t allocator_, hxalignment_t alignment_=hxalignment)
hxinline char *	hxstring_duplicate (const char *s_)
constexpr void *	operator new (size_t, void *ptr_) noexcept
constexpr void *	operator new[] (size_t, void *ptr_) noexcept
void *	operator new (size_t size_) hxattr_nodiscard
void *	operator new[] (size_t size_) hxattr_nodiscard
void	operator delete (void *ptr_) noexcept
void	operator delete[] (void *ptr_) noexcept
template<typename T, hxsystem_allocator_t allocator_ = hxsystem_allocator_current, hxalignment_t align_ = hxalignment, typename... Args_>
T *	hxnew (Args_ &&... args_) noexcept
template<typename T>
void	hxdelete (T *t_) noexcept
void	hxmemory_manager_allocate_stacks (const size_t *sizes_, size_t stack_count_) hxattr_cold
template<size_t stack_count_>
void	hxmemory_manager_allocate_stacks (const size_t(&list_)[stack_count_])
hxmemory_manager_stats	hxmemory_manager_utilization (bool stacks_only_, bool log_) hxattr_cold

Variables
HX_C_BEGIN_ typedef unsigned int	hxalignment_t
constexpr hxalignment_t	hxalignment = static_cast<hxalignment_t>(alignof(max_align_t ))
hxattr_noexcept hxsystem_allocator_t	allocator_
hxattr_noexcept hxsystem_allocator_t hxalignment_t	alignment_

Detailed Description

Memory Manager C/C++ API.

Memory allocators are selected using an ID. These are the large system-wide allocators, not the per-container hxallocator which allocates from here. Temporary stacks are allocated at runtime with hxmemory_manager_allocate_stacks and a sophisticated streaming design can select between them using hxsystem_allocator_stack_0 + index.

General purpose memory allocators are inefficient and unsafe to use. The problem is that long running code requires a lot of extra space to make sure it doesn't fragment and unexpectedly fail to make a large allocation. (Hardware support for virtual memory can help defrag the program heap, but that requires processor support and even more expensive system call overhead.) For code that uses a lot of temporary intermediate allocations 1/3 of your memory and 1/3 of your processor time could get eaten by the heap allocator. The hxsystem_allocator_stack_0 is provided as a replacement for that use case.

There are also a category of allocations that are expected to last for the lifetime of the application. They can be allocated with 0 overhead using hxsystem_allocator_permanent.

WARNING: The current allocator ID is a thread local attribute that is managed by the hxsystem_allocator_scope RAII class. This provides a non- intrusive way to move swaths of code to different allocators.

Alignment must be a power of two. (It always is.)

HX_HARDENING_MODE == HX_HARDENING_MODE_DEBUG debug memory byte patterns:

Hex	Pattern Description
0xab	Static hxallocator instance.
0xcd	Allocated.
0xdd	Deallocated.

Global new and delete are provided when HX_USE_LIBCXX==0. This is a requirement for running as a stand alone C++ runtime. Otherwise they are not interfered with. Those default versions do not use the memory manager's current allocator because it may not be safe to do so. hxnew and hxdelete are available as recommended substitutes.

It should be possible to implement a triple buffered streaming strategy for DMA by allocating three temp stacks and selecting between them with hxsystem_allocator_stack_0 + index.

Typedef Documentation

hxsystem_allocator_t

typedef int hxsystem_allocator_t

hxsystem_allocator_t - This is extendable by the application.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
hxsystem_allocator_current	hxsystem_allocator_current - Use current allocation scope. Not a real allocator slot.
hxsystem_allocator_heap	hxsystem_allocator_heap - OS heap with alignment.
hxsystem_allocator_permanent	hxsystem_allocator_permanent - Contiguous allocations that must not be freed.
hxsystem_allocator_stack_0	hxsystem_allocator_stack_0 - Temporary stacks. Reset to previous depth at scope closure. Stack index n is hxsystem_allocator_stack_0 + n.

Function Documentation

hxattr_allocator()

hxattr_noexcept hxattr_allocator

(

hxfree

)

hxmalloc - Allocates memory of the specified size using the default memory manager.

hxstring_duplicate - Allocates a copy of a string using the specified memory manager.

hxmalloc_ext - Allocates memory of the specified size with a specific memory manager and alignment.

A C++ overload optionally provides the same arguments as hxmalloc_ext. Will not return on failure. WARNING: It is undefined behavior to compare pointers to different allocations. This is consistent with the C++ standard. Allocations of size 0 may or may not return the same pointer as previous allocations. Returns a pointer that must be released with hxfree.

• size : The size of the memory to allocate.
• allocator(C++ only): The memory manager ID to use for allocation. (Default is hxsystem_allocator_current.)

• alignment(C++ only): The alignment for the allocation. (Default is hxalignment.)

  Will not return on failure. Returns a pointer that must be released with hxfree.

• size : The size of the memory to allocate.
• allocator : The memory manager ID to use for allocation. (Default is hxsystem_allocator_current.)

• alignment : The alignment for the allocation. (Default is hxalignment.)

  Returns a pointer to the duplicated string. Returns a pointer that must be released with hxfree.

• string : Non-null string to duplicate.
• allocator : The memory manager ID to use for allocation. Defaults to hxsystem_allocator_current in C++.

hxdelete()

template<typename T>

void hxdelete ( T * t_ )

noexcept

hxdelete - Deletes an object of type T and frees its memory using the memory manager.

• t : Pointer to the object to delete.

hxfree()

void hxfree

(

void *

ptr_

)

hxfree - Frees memory previously allocated with hxmalloc or hxmalloc_ext.

Freeing null pointers is allowed.

• ptr : Pointer to the memory to free.

hxmalloc()

HX_C_END_ hxinline void * hxmalloc	(	size_t	size_,
		hxsystem_allocator_t	allocator_,
		hxalignment_t	alignment_ = hxalignment )

hxmalloc - Add hxmalloc_ext args to hxmalloc C interface.

Allocates memory with a specific memory manager and alignment. NOTE: This is not in the libhatchet namespace.

hxmemory_manager_allocate_stacks() [1/2]

void hxmemory_manager_allocate_stacks	(	const size_t *	sizes_,
		size_t	stack_count_ )

hxmemory_manager_allocate_stacks - Allocates the runtime temporary stacks.

Stack n is addressed as hxsystem_allocator_stack_0 + n. The memory manager does not allocate any temporary stacks at init. Do not call twice.

• stack_count : The number of temporary stacks to allocate. Must not exceed HX_MEMORY_MAX_STACKS.
• sizes : An array of stack_count byte budgets, one per stack.

hxmemory_manager_allocate_stacks() [2/2]

template<size_t stack_count_>

void hxmemory_manager_allocate_stacks

(

const size_t(&)

list_[stack_count_]

)

A safer hxmemory_manager_allocate_stacks.

hxmemory_manager_utilization()

hxmemory_manager_stats hxmemory_manager_utilization	(	bool	stacks_only_,
		bool	log_ )

hxmemory_manager_utilization - Returns the utilization statistics of the memory manager.

• stacks_only : Only report temporary stack utilization.
• log : Log stats when logging is enabled.

hxnew()

template<typename T, hxsystem_allocator_t allocator_ = hxsystem_allocator_current, hxalignment_t align_ = hxalignment, typename... Args_>

T * hxnew ( Args_ &&... args_ )

noexcept

hxnew<T, allocator, align>(...) - Allocates and constructs an object of type T using an optional memory allocator and alignment.

Returns a pointer to the newly constructed object. Will not return on failure.

• allocator : The memory manager ID to use for allocation. Defaults to hxsystem_allocator_current.
• align : Alignment to use when allocating new pointers. Defaults to hxalignment.

hxstring_duplicate()

hxinline char * hxstring_duplicate

(

const char *

s_

)

hxstring_duplicate - Add default args to C interface.

The allocator is hxsystem_allocator_current. Duplicates a string using the default memory manager. NOTE: This is not in the libhatchet namespace.

operator delete()

void operator delete ( void * ptr_ )

noexcept

operator delete[]()

void operator delete[] ( void * ptr_ )

noexcept

operator new() [1/2]

void * operator new

(

size_t

size_

)

operator new() [2/2]

void * operator new ( size_t , void * ptr_ )

constexprnoexcept

operator new[]() [1/2]

void * operator new[]

(

size_t

size_

)

operator new[]() [2/2]

void * operator new[] ( size_t , void * ptr_ )

constexprnoexcept

Variable Documentation

alignment_

hxattr_noexcept hxsystem_allocator_t hxalignment_t alignment_

allocator_

hxattr_noexcept hxsystem_allocator_t allocator_

hxalignment

hxalignment_t hxalignment = static_cast<hxalignment_t>(alignof(max_align_t ))

inlineconstexpr

hxalignment - The default alignment.

Allows for storing things like pointers. This alignment should work for most types.

hxalignment_t

HX_C_BEGIN_ typedef unsigned int hxalignment_t

hxalignment_t - A positive integer power of 2 for aligning allocations.