#include <default_allocator.h>

Public Member Functions
void *	allocate (size_t i_size, size_t i_alignment, size_t i_alignment_offset=0)

void *	try_allocate (size_t i_size, size_t i_alignment, size_t i_alignment_offset=0) noexcept

void	deallocate (void *i_block, size_t i_size, size_t i_alignment, size_t i_alignment_offset=0) noexcept

void *	allocate_page ()

void *	try_allocate_page (progress_guarantee i_progress_guarantee) noexcept

void *	allocate_page_zeroed ()

void *	try_allocate_page_zeroed (progress_guarantee i_progress_guarantee) noexcept

void	deallocate_page (void *i_page) noexcept

void	deallocate_page_zeroed (void *i_page) noexcept

void	pin_page (void *i_page) noexcept

void	unpin_page (void *i_address) noexcept

bool	try_pin_page (progress_guarantee i_progress_guarantee, void *i_address) noexcept

void	unpin_page (progress_guarantee i_progress_guarantee, void *i_address) noexcept

uintptr_t	get_pin_count (const void *i_address) noexcept

bool	operator== (const basic_default_allocator &) const noexcept

bool	operator!= (const basic_default_allocator &) const noexcept

Static Public Member Functions
static void	reserve_lockfree_page_memory (size_t i_size, size_t *o_reserved_size=nullptr)

static bool	try_reserve_lockfree_page_memory (progress_guarantee i_progress_guarantee, size_t i_size, size_t *o_reserved_size=nullptr) noexcept

Static Public Attributes
static constexpr size_t	page_size = PageAllocator::page_size

static constexpr size_t	page_alignment = PageAllocator::page_alignment

Detailed Description

template<size_t PAGE_CAPACITY_AND_ALIGNMENT = default_page_capacity>
class density::basic_default_allocator< PAGE_CAPACITY_AND_ALIGNMENT >

Class template providing paged and legacy memory allocation. It meets the requirements of UntypedAllocator and PagedAllocator.

basic_default_allocator is stateless, so instances are interchangeable: blocks and pages can be deallocated by any instance of basic_default_allocator.

Member Function Documentation

void* allocate	(	size_t	i_size,
		size_t	i_alignment,
		size_t	i_alignment_offset = `0`
	)

inline

Allocates a legacy memory block with the specified size and alignment.

Parameters

i_size	size of the requested memory block, in bytes
i_alignment	alignment of the requested memory block, in bytes
i_alignment_offset	offset of the block to be aligned, in bytes. The alignment is guaranteed only i_alignment_offset bytes from the beginning of the block.

Returns: address of the new memory block, always != nullptr

Precondition

The behavior is undefined if either:

i_alignment is zero or it is not an integer power of 2
i_size is not a multiple of i_alignment
i_alignment_offset is greater than i_size

Progress guarantee: the same of the built-in operator new, usually blocking
Throws: std::bad_alloc on failure

The content of the newly allocated block is undefined.

void* try_allocate	(	size_t	i_size,
		size_t	i_alignment,
		size_t	i_alignment_offset = `0`
	)

inlinenoexcept

Tries to allocates a legacy memory block with the specified size and alignment.

Parameters

i_size	size of the requested memory block, in bytes
i_alignment	alignment of the requested memory block, in bytes
i_alignment_offset	offset of the block to be aligned, in bytes. The alignment is guaranteed only i_alignment_offset bytes from the beginning of the block.

Returns: address of the new memory block, or nullptr in case of failure

Precondition

The behavior is undefined if either:

i_alignment is zero or it is not an integer power of 2
i_size is not a multiple of i_alignment
i_alignment_offset is greater than i_size

Progress guarantee: the same of the built-in operator new, usually blocking
Throws: nothing

The content of the newly allocated block is undefined.

void deallocate	(	void *	i_block,
		size_t	i_size,
		size_t	i_alignment,
		size_t	i_alignment_offset = `0`
	)

inlinenoexcept

Deallocates a legacy memory block. After the call any access to the memory block results in undefined behavior.

Parameters

i_block	block to deallocate, or nullptr.
i_size	size of the block to deallocate, in bytes.
i_alignment	alignment of the memory block.
i_alignment_offset	offset of the alignment

Precondition

The behavior is undefined if either:

i_block is not a memory block allocated by the function allocate
i_size, i_alignment and i_alignment_offset are not the same specified when the block was allocated

Progress guarantee: the same of the built-in operator delete, usually blocking
Throws: nothing

If i_block is nullptr, the call has no effect.

void* allocate_page ( )

inline

Allocates a memory page.

Returns: address of the new memory page, always != nullptr

Progress guarantee: blocking
Throws: std::bad_alloc on failure.

The content of the newly allocated page is undefined.

void* try_allocate_page ( progress_guarantee i_progress_guarantee )

inlinenoexcept

Tries to allocates a memory page.

Returns: address of the new memory page, or nullptr if the allocation fails

Progress guarantee: specified by the argument
Throws: nothing

The content of the newly allocated page is undefined.

void* allocate_page_zeroed ( )

inline

Allocates a memory page.

Returns: address of the new memory page, always != nullptr

Progress guarantee: blocking
Throws: std::bad_alloc on failure.

The content of the newly allocated page is zeroed.

void* try_allocate_page_zeroed ( progress_guarantee i_progress_guarantee )

inlinenoexcept

Tries to allocates a memory page.

Returns: address of the new memory page, or nullptr if the allocation fails

Progress guarantee: specified by the argument
Throws: nothing

The content of the newly allocated page is zeroed.

void deallocate_page ( void * i_page )

inlinenoexcept

Deallocates a memory page. If the page is still pinned by some threads, it is not altered or recycled by the allocator until it is unpinned.

Parameters

i_page pointer to a byte within the page to deallocate. Can't be nullptr.

Precondition

The behavior is undefined if either:

i_page is not a page allocated by allocate_page, try_allocate_page, allocate_page_zeroed or try_allocate_page_zeroed

Progress guarantee: wait free
Throws: nothing

void deallocate_page_zeroed ( void * i_page )

inlinenoexcept

Deallocates a memory page. If the page is still pinned by some threads, it is not altered or recycled by the allocator until it is unpinned. If the page is not pinned, it must be zeroed. Otherwise it must be zeroed when the last pin is removed.

Parameters

i_page pointer to a byte within the page to deallocate. Can't be nullptr.

Precondition

The behavior is undefined if either:

i_page is not a page allocated by allocate_page, try_allocate_page, allocate_page_zeroed or try_allocate_page_zeroed
when the last pin is removed the page is not completely zeroed

Progress guarantee: wait free
Throws: nothing

static void reserve_lockfree_page_memory	(	size_t	i_size,
		size_t *	o_reserved_size = `nullptr`
	)

inlinestatic

Reserves the specified memory size from the system for lock-free page allocation.

Parameters

i_size	the space (in bytes) that the internal page allocator should reserve for page allocation.
o_reserved_size	pointer to a size_t that receives the actual space (in bytes) that the allocator has allocated from the system, always greater or equal to i_size. This parameter can be null, in which case the actual reserved size is not returned.

The internal page allocator requests memory regions from the system and uses them to allocate pages with a lock-free algorithm. Regions are returned to the system only during the destruction of global objects.
This function ensures that the sum of the capacity available in the all the regions is at least the specified size. If a new region is necessary in order to reach the specified capacity, but the allocation from the system fails, this function throw a std::bad_alloc.
Note: some of this space may be already allocated as pages.

Progress guarantee: blocking
Throws: std::bad_alloc on failure.

static bool try_reserve_lockfree_page_memory	(	progress_guarantee	i_progress_guarantee,
		size_t	i_size,
		size_t *	o_reserved_size = `nullptr`
	)

inlinestaticnoexcept

Tries to reserve the specified memory size from the system for lock-free page allocation.

Parameters

i_progress_guarantee	minimum progress guarantee of this call. If it is not progress_blocking, no region is allocated
i_size	the space (in bytes) that the internal page allocator should reserve for page allocation.
o_reserved_size	pointer to a size_t that receives the actual space (in bytes) that the allocator has allocated from the system, always greater or equal to i_size. This parameter can be null, in which case the actual reserved size is not returned

Returns: whether the requested size is less than or equal to the actual reserved space

The internal page allocator requests memory regions from the system and uses them to allocate pages. Regions are returned to the system only during the destruction of global objects.
This function verifies that the sum of memory available in the regions is at least the specified size. Note: some of this space may be already allocated as pages.

Progress guarantee: specified by the argument
Throws: nothing.

void pin_page ( void * i_page )

inlinenoexcept

Pins the page containing the specified address, incrementing an internal page_specific ref-count.

Parameters

i_page pointer to a byte within the page to deallocate. Can't be nullptr.

If the page has been already deallocated no undefined behavior occurs: the caller should detect this case and unpin the page immediately. Using a deallocated-then-pinned page in any other way other than unpinning (including accessing its content) causes undefined behavior.
If the page is still allocated then the pin ensures that, while the page is pinned:

the content of the page is not altered by the allocator
the page is not returned by a call to allocate_page, try_allocate_page, allocate_page_zeroed or try_allocate_page_zeroed.
if the page gets deallocated with a call to allocate_page_zeroed or try_allocate_page_zeroed, the memory may be still not zeroed.

Every call to pin_page should be matched by a call to unpin_page by the same thread. A thread may pin the same page multiple times, provided that it unpins the page the same number of times.

Precondition

The behavior is undefined if either:

the page containing i_page was never returned by allocate_page, try_allocate_page, allocate_page_zeroed or try_allocate_page_zeroed

Progress guarantee: lock-free
Throws: nothing.

void unpin_page ( void * i_address )

inlinenoexcept

Removes a pin from the page, decrementing the internal ref-count.

Precondition

The behavior is undefined if either:

the page containing i_page was never returned by allocate_page, try_allocate_page, allocate_page_zeroed or try_allocate_page_zeroed
the page was not previously pinned by this thread

Progress guarantee: lock-free
Throws: nothing.

bool try_pin_page	(	progress_guarantee	i_progress_guarantee,
		void *	i_address
	)

inlinenoexcept

Tries to pin the page containing the specified address, incrementing an internal page_specific ref-count, If the implementation can't complete the action with the specified progress guarantee, the call has no visible effects, and the return value is false. Otherwise the return value is true.

Progress guarantee: specified by the argument
Throws: nothing.

void unpin_page	(	progress_guarantee	i_progress_guarantee,
		void *	i_address
	)

inlinenoexcept

Removes a pin from the page, decrementing the internal ref-count.

Precondition

The behavior is undefined if either:

the page containing i_page was never returned by allocate_page, try_allocate_page, allocate_page_zeroed or try_allocate_page_zeroed
the page was not previously pinned by this thread

Progress guarantee: specified by the argument
Throws: nothing.

uintptr_t get_pin_count ( const void * i_address )

inlinenoexcept

Returns the number of times the specified page has been pinned by any thread. This function is useful only for diagnostic or debugging.

Precondition

The behavior is undefined if either:

the page containing i_page was never returned by allocate_page, try_allocate_page, allocate_page_zeroed or try_allocate_page_zeroed

Progress guarantee: wait-free
Throws: nothing.

bool operator== ( const basic_default_allocator< PAGE_CAPACITY_AND_ALIGNMENT > & ) const

inlinenoexcept

Returns whether the right-side allocator can be used to deallocate block and pages allocated by this allocator.

Returns: always true.

bool operator!= ( const basic_default_allocator< PAGE_CAPACITY_AND_ALIGNMENT > & ) const

inlinenoexcept

Returns whether the right-side allocator cannot be used to deallocate block and pages allocated by this allocator.

Returns: always false.

Member Data Documentation

constexpr size_t page_size = PageAllocator::page_size

static

Usable size (in bytes) of memory pages.

constexpr size_t page_alignment = PageAllocator::page_alignment

static

Alignment (in bytes) of memory pages.

The documentation for this class was generated from the following file:

C:/projects/density/include/density/default_allocator.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

template<size_t PAGE_CAPACITY_AND_ALIGNMENT = default_page_capacity> class density::basic_default_allocator< PAGE_CAPACITY_AND_ALIGNMENT >

Member Function Documentation

Member Data Documentation

template<size_t PAGE_CAPACITY_AND_ALIGNMENT = default_page_capacity>
class density::basic_default_allocator< PAGE_CAPACITY_AND_ALIGNMENT >