xentara::utils::lockFree::Pool< Element, Allocator > Class Template Reference

A lock-free pool that manages a number of preallocator memory locations for objects. More...

#include <xentara/utils/lockFree/Pool.hpp>

Public Types
using	value_type = Element
	The element type.
using	allocator_type = Allocator
	The Allocator type.
using	size_type = typename std::allocator_traits< Allocator >::size_type
	The type used for sizes.
using	difference_type = typename std::allocator_traits< Allocator >::difference_type
	The type used for distances.
using	reference = value_type &
	A reference to an element.
using	const_reference = const value_type &
	A const reference to an element.
using	pointer = typename std::allocator_traits< Allocator >::pointer
	A pointer to an element.
using	const_pointer = typename std::allocator_traits< Allocator >::const_pointer
	A const pointer to an element.

Public Member Functions
constexpr	Pool () noexcept(noexcept(Allocator()))=default
	Constructs an empty pool with a default-constructed allocator.
constexpr	Pool (const Allocator &allocator) noexcept
	Constructs an empty pool with a specific allocator.
	Pool (size_type capacity)
	Constructor for a pool that can hold a specific number of elements.
	Pool (size_type capacity, const Allocator &allocator)
	Constructor for a pool that can hold a specific number of elements.
auto	allocate () -> pointer
	Allocates storage for an element.
auto	allocate (std::nothrow_t) noexcept -> pointer
	Allocates storage for an element if there is space left.
auto	allocateWithIndex () -> std::pair< pointer, size_type >
	Allocates storage for an element and returns a unique index for it.
auto	allocateWithIndex (std::nothrow_t) noexcept -> std::pair< pointer, size_type >
	Allocates storage for an element if there is space left, and returns a unique index for it.
auto	deallocate (pointer element) noexcept -> void
	Deallocates the storage of an element back to the pool.
auto	deallocateAt (size_type index) noexcept -> void
	Deallocates the storage of an element back to the pool using its index.
auto	deallocateAll () noexcept -> void
	Deallocates all allocated elements.
auto	reset (size_type size) -> void
	Reset the pool memory to a certain capacity.
auto	index (const_reference element) const noexcept -> size_type
	Get a unique index for an element that can be used to reference it.
auto	operator[] (size_type index) noexcept -> reference
	Get the element associated with an index.
auto	operator[] (size_type index) const noexcept -> const_reference
	Get the element associated with an index.
constexpr auto	capacity () const noexcept -> size_type
	Gets the maximum number of elements the pool can hold.
constexpr auto	max_size () const noexcept -> size_type
	Gets the maximum possible capacity.

Detailed Description

template<typename Element, typename Allocator = std::allocator<Element>>
class xentara::utils::lockFree::Pool< Element, Allocator >

A lock-free pool that manages a number of preallocator memory locations for objects.

Template Parameters

Element	the element type for which memory is allocated
Allocator	the allocator for the element type

Member Typedef Documentation

allocator_type

template<typename Element , typename Allocator = std::allocator<Element>>

using xentara::utils::lockFree::Pool< Element, Allocator >::allocator_type = Allocator

The Allocator type.

const_pointer

template<typename Element , typename Allocator = std::allocator<Element>>

using xentara::utils::lockFree::Pool< Element, Allocator >::const_pointer = typename std::allocator_traits<Allocator>::const_pointer

A const pointer to an element.

const_reference

template<typename Element , typename Allocator = std::allocator<Element>>

using xentara::utils::lockFree::Pool< Element, Allocator >::const_reference = const value_type &

A const reference to an element.

difference_type

template<typename Element , typename Allocator = std::allocator<Element>>

using xentara::utils::lockFree::Pool< Element, Allocator >::difference_type = typename std::allocator_traits<Allocator>::difference_type

The type used for distances.

pointer

template<typename Element , typename Allocator = std::allocator<Element>>

using xentara::utils::lockFree::Pool< Element, Allocator >::pointer = typename std::allocator_traits<Allocator>::pointer

A pointer to an element.

reference

template<typename Element , typename Allocator = std::allocator<Element>>

using xentara::utils::lockFree::Pool< Element, Allocator >::reference = value_type &

A reference to an element.

size_type

template<typename Element , typename Allocator = std::allocator<Element>>

using xentara::utils::lockFree::Pool< Element, Allocator >::size_type = typename std::allocator_traits<Allocator>::size_type

The type used for sizes.

value_type

template<typename Element , typename Allocator = std::allocator<Element>>

using xentara::utils::lockFree::Pool< Element, Allocator >::value_type = Element

The element type.

Constructor & Destructor Documentation

Pool() [1/4]

template<typename Element , typename Allocator = std::allocator<Element>>

constexpr xentara::utils::lockFree::Pool< Element, Allocator >::Pool ( )

constexprdefaultnoexcept

Constructs an empty pool with a default-constructed allocator.

A pool created with this constructor has a capacity of 0 and cannot hold any elements. You must make room for the elements using reset() before allocation storage for any elements.

Pool() [2/4]

template<typename Element , typename Allocator = std::allocator<Element>>

constexpr xentara::utils::lockFree::Pool< Element, Allocator >::Pool ( const Allocator &  allocator )

explicitconstexprnoexcept

Constructs an empty pool with a specific allocator.

A pool created with this constructor has a capacity of 0 and cannot hold any elements. You must make room for the elements using reset() before allocation storage for any elements.

Parameters

allocator

The allocator

Pool() [3/4]

template<typename Element , typename Allocator = std::allocator<Element>>

xentara::utils::lockFree::Pool< Element, Allocator >::Pool ( size_type  capacity )

explicit

Constructor for a pool that can hold a specific number of elements.

Creates a pool of the given size and fills it with default-inserted values.

Parameters

capacity

The number of entries to create room for

Pool() [4/4]

template<typename Element , typename Allocator = std::allocator<Element>>

xentara::utils::lockFree::Pool< Element, Allocator >::Pool ( size_type  capacity, const Allocator &  allocator  )

explicit

Constructor for a pool that can hold a specific number of elements.

Creates a pool of the given size and fills it with default-inserted values.

Parameters

capacity	The number of entries to create room for
allocator	The allocator

Member Function Documentation

allocate() [1/2]

template<typename Element , typename Allocator >

auto xentara::utils::lockFree::Pool< Element, Allocator >::allocate

(

)

-> pointer

Allocates storage for an element.

Returns

The newly allocated storage

Exceptions

std::length_error	The pool is exhausted
Rethrows	any exception thrown by the element constructor.

allocate() [2/2]

template<typename Element , typename Allocator >

auto xentara::utils::lockFree::Pool< Element, Allocator >::allocate ( std::nothrow_t  ) -> pointer

noexcept

Allocates storage for an element if there is space left.

This function will return a nullptr rather than throwing an exception if the pool is exhausted.

Returns

The newly allocated storage, or nullptr if the pool is exhausted

allocateWithIndex() [1/2]

template<typename Element , typename Allocator >

auto xentara::utils::lockFree::Pool< Element, Allocator >::allocateWithIndex

(

)

-> std::pair<pointer, size_type>

Allocates storage for an element and returns a unique index for it.

Returns

The newly allocated storage, along with a unique index that can be used to reference the element. The indices of created objects are not sequential or contiguous.

Exceptions

std::length_error

The pool is exhausted

allocateWithIndex() [2/2]

template<typename Element , typename Allocator >

auto xentara::utils::lockFree::Pool< Element, Allocator >::allocateWithIndex ( std::nothrow_t  ) -> std::pair<pointer, size_type>

noexcept

Allocates storage for an element if there is space left, and returns a unique index for it.

This function will return a nullptr rather than throwing an exception if the pool is exhausted.

Returns

The newly allocated storage, along with a unique index that can be used to reference the element. The indices of created objects are not sequential or contiguous. If the pool is exhausted, { nullptr, 0 } is returned.

capacity()

template<typename Element , typename Allocator = std::allocator<Element>>

constexpr auto xentara::utils::lockFree::Pool< Element, Allocator >::capacity ( ) const -> size_type

constexprnoexcept

Gets the maximum number of elements the pool can hold.

Returns

the capacity of the pool

deallocate()

template<typename Element , typename Allocator >

auto xentara::utils::lockFree::Pool< Element, Allocator >::deallocate ( pointer  element ) -> void

noexcept

Deallocates the storage of an element back to the pool.

Parameters

element

An element previously returned by allocate() or allocateWithIndex(). If you pass nullptr, the function does nothing.

deallocateAll()

template<typename Element , typename Allocator >

auto xentara::utils::lockFree::Pool< Element, Allocator >::deallocateAll ( ) -> void

noexcept

Deallocates all allocated elements.

Attention

This function is unsynchronized and must not be called while other threads are accessing the pool

The storage for any elements that were not deallocated is discarded without calling any destructor

deallocateAt()

template<typename Element , typename Allocator >

auto xentara::utils::lockFree::Pool< Element, Allocator >::deallocateAt ( size_type  index ) -> void

noexcept

Deallocates the storage of an element back to the pool using its index.

Parameters

index

The index of an element previously returned by allocate() or allocateWithIndex()

index()

template<typename Element , typename Allocator = std::allocator<Element>>

auto xentara::utils::lockFree::Pool< Element, Allocator >::index ( const_reference  element ) const -> size_type

noexcept

Get a unique index for an element that can be used to reference it.

Parameters

element

An element allocated using allocate()

Returns

A node index for the element. The index is unique for all currently allocated elements, and is always between between 0 and capacity() - 1.

max_size()

template<typename Element , typename Allocator = std::allocator<Element>>

constexpr auto xentara::utils::lockFree::Pool< Element, Allocator >::max_size ( ) const -> size_type

constexprnoexcept

Gets the maximum possible capacity.

Returns

The maximum capacity that can be specified

operator[]() [1/2]

template<typename Element , typename Allocator = std::allocator<Element>>

auto xentara::utils::lockFree::Pool< Element, Allocator >::operator[] ( size_type  index ) const -> const_reference

noexcept

Get the element associated with an index.

Parameters

index

An element index previously retuned by index() for an element that still exists.

Returns

A reference to the corresponding element.

operator[]() [2/2]

template<typename Element , typename Allocator = std::allocator<Element>>

auto xentara::utils::lockFree::Pool< Element, Allocator >::operator[] ( size_type  index ) -> reference

noexcept

Get the element associated with an index.

Parameters

index

An element index previously retuned by index() for an element that still exists.

Returns

A reference to the corresponding element.

reset()

template<typename Element , typename Allocator >

auto xentara::utils::lockFree::Pool< Element, Allocator >::reset

(

size_type

size

)

-> void

Reset the pool memory to a certain capacity.

Attention

This function is unsynchronized and must not be called while other threads are accessing the pool

The storage for any elements that were not deallocated is discarded without calling any destructor

Parameters

size	The new capacity of the pool