The allocator_traits class template provides a standardized way to access allocator functionality. More...

#include <allocator_traits.hpp>

Inheritance diagram for bit::memory::allocator_traits< Allocator >:

Public Types
using	pointer = allocator_pointer_t< Allocator >

using	const_pointer = allocator_const_pointer_t< Allocator >

using	size_type = allocator_size_type_t< Allocator >

using	difference_type = allocator_difference_type_t< Allocator >

template<typename T >
using	pointer_rebind = typename detail::allocator_pointer_rebind< Allocator, T >::type
	Rebinds a pointer to the new pointer type. More...

using	default_alignment = allocator_default_alignment< Allocator >

using	max_alignment = allocator_max_alignment< Allocator >

using	can_truncate_deallocations = allocator_can_truncate_deallocations< Allocator >

using	knows_ownership = allocator_knows_ownership< Allocator >

using	uses_pretty_pointers = negation< std::is_same< void *, pointer_rebind< void > >>

Public Member Functions
size_type	recommended_allocation_size (const Allocator &alloc, size_type requested)
	Determines the recommended allocation size of `requested` bytes from the given allocator. More...

Static Public Member Functions
static void	deallocate (Allocator &alloc, pointer p, size_type size)
	Deallocates a pointer previously allocated with `allocate` or try_allocate. More...

template<typename U = Allocator, typename = std::enable_if<can_truncate_deallocations::value>>
static void	deallocate_all (Allocator &alloc)
	Deallocates all memory from the given allocator. More...

template<typename T , typename... Args>
static void	construct (Allocator &alloc, void *p, Args &&...args)
	Constructs an instance of `T` at address `p` with `args`. More...

template<typename T , typename... Args>
static detail::allocator_pointer_rebind< Allocator, T >::type	make (Allocator &alloc, Args &&...args)
	Allocates and constructs a type `T` with the arguments `args`. More...

template<typename T >
static void	destroy (Allocator &alloc, T *p)
	Destroys the instance at `p` by invoking the destructor. More...

template<typename Pointer , typename = std::enable_if_t<is_typed_pointer<Pointer>>>
static void	dispose (Allocator &alloc, const Pointer &p)
	Disposes of the given type `T`. More...

template<typename Pointer , typename = std::enable_if_t<is_typed_pointer<Pointer>>>
static void	dispose_array (Allocator &alloc, const Pointer &p, size_type n)
	Disposes of the given array of T. More...

static bool	owns (const Allocator &alloc, const_pointer p) noexcept
	Checks if the given allocator is known to own the specified pointer `p`. More...

static allocator_info	info (const Allocator &alloc) noexcept
	Gets the name of the specified allocator. More...

template<typename T >
static std::pointer_traits< pointer >::template rebind< T >	pointer_to (Allocator &alloc, T &x) noexcept
	Converts a reference to an entry into a pointer used by this allocator. More...

template<typename Pointer , typename = std::enable_if_t<is_typed_pointer<Pointer>>>
static std::pointer_traits< Pointer >::element_type *	to_raw_pointer (Allocator &alloc, const Pointer &p) noexcept
	Converts a pointer from this allocator into a reference. More...

static bool	is_unbounded (const Allocator &alloc) noexcept
	Determines if an allocator is unbounded. More...

static size_type	max_size (const Allocator &alloc) noexcept
	Gets the maximum size allocateable from this allocator. More...

static size_type	min_size (const Allocator &alloc) noexcept
	Gets the minimum size allocateable from this allocator. More...


static pointer	try_allocate (Allocator &alloc, size_type size, size_type align) noexcept
	Attempts to allocate memory of at least `size` bytes, aligned to `align` boundary. More...

static pointer	try_allocate (Allocator &alloc, const_pointer hint, size_type size, size_type align) noexcept
	Attempts to allocate memory of at least `size` bytes, aligned to `align` boundary. More...


static pointer	allocate (Allocator &alloc, size_type size, size_type align)
	Allocates memory of at least `size` bytes, aligned to `align` boundary. More...

static pointer	allocate (Allocator &alloc, const_pointer hint, size_type size, size_type align)
	Allocates memory of at least `size` bytes, aligned to `align` boundary. More...


static bool	expand (Allocator &alloc, pointer p, size_type new_size)
	Expands the memory addres located at `p` to contain `new_size` bytes. More...


template<typename T >
static std::pointer_traits< pointer >::template rebind< T >	make_array (Allocator &alloc, size_type n)
	Allocates and construct an array of type `T`. More...

template<typename T >
static std::pointer_traits< pointer >::template rebind< T >	make_array (Allocator &alloc, size_type n, const T &copy)
	Allocates and construct an array of type `T`. More...

Detailed Description

template<typename Allocator>
class bit::memory::allocator_traits< Allocator >

The allocator_traits class template provides a standardized way to access allocator functionality.

This will infer defaults for any optional values that may not be present in the allocator

Template Parameters

Allocator the allocator type. Must satisfy Allocator concept

Definition at line 81 of file allocator_traits.hpp.

Member Typedef Documentation

◆ pointer_rebind

template<typename Allocator >

template<typename T >

using bit::memory::allocator_traits< Allocator >::pointer_rebind = typename detail::allocator_pointer_rebind<Allocator,T>::type

Rebinds a pointer to the new pointer type.

Template Parameters

T	the type to rebind the pointer to

Definition at line 104 of file allocator_traits.hpp.

Member Function Documentation

◆ allocate() [1/2]

template<typename Allocator >

static pointer bit::memory::allocator_traits< Allocator >::allocate	(	Allocator &	alloc,
		size_type	size,
		size_type	align
	)

static

Allocates memory of at least size bytes, aligned to align boundary.

On failure, this function may throw or invoke the out_of_memory handler before returning nullptr

Parameters

alloc	the allocator to allocate from
hint	pointer to a nearby memory location to allocate near
size	the size of the allocation
align	the alignment of the allocation

Returns: the pointer to the allocated member

◆ allocate() [2/2]

template<typename Allocator >

static pointer bit::memory::allocator_traits< Allocator >::allocate	(	Allocator &	alloc,
		const_pointer	hint,
		size_type	size,
		size_type	align
	)

static

Allocates memory of at least size bytes, aligned to align boundary.

On failure, this function may throw or invoke the out_of_memory handler before returning nullptr

Parameters

alloc	the allocator to allocate from
hint	pointer to a nearby memory location to allocate near
size	the size of the allocation
align	the alignment of the allocation

Returns: the pointer to the allocated member

◆ construct()

template<typename Allocator >

template<typename T , typename... Args>

static void bit::memory::allocator_traits< Allocator >::construct	(	Allocator &	alloc,
		void *	p,
		Args &&...	args
	)

static

Constructs an instance of T at address p with args.

Template Parameters

T	the type to construct

Parameters

alloc	the allocator to use for construction
p	the pointer to the memory to construct at
args	the arguments to forward to `T's` constructor

Returns: pointer to teh constructed entry

◆ deallocate()

template<typename Allocator >

static void bit::memory::allocator_traits< Allocator >::deallocate	(	Allocator &	alloc,
		pointer	p,
		size_type	size
	)

static

Deallocates a pointer previously allocated with allocate or try_allocate.

Parameters

alloc	the allocator to allocate from
p	the pointer to deallocate
size	the size of the allocation

◆ deallocate_all()

template<typename Allocator >

template<typename U = Allocator, typename = std::enable_if<can_truncate_deallocations::value>>

static void bit::memory::allocator_traits< Allocator >::deallocate_all ( Allocator & alloc )

static

Deallocates all memory from the given allocator.

This is only enabled if the underlying allocator supports it

Parameters

alloc the allocator to deallocate everything from

◆ destroy()

template<typename Allocator >

template<typename T >

static void bit::memory::allocator_traits< Allocator >::destroy	(	Allocator &	alloc,
		T *	p
	)

static

Destroys the instance at p by invoking the destructor.

Parameters

alloc	the allocator to use for destruction
p	the pointer to destroy

◆ dispose()

template<typename Allocator >

template<typename Pointer , typename = std::enable_if_t<is_typed_pointer<Pointer>>>

static void bit::memory::allocator_traits< Allocator >::dispose	(	Allocator &	alloc,
		const Pointer &	p
	)

static

Disposes of the given type T.

This calls T's destructor, and then deallocates it with alloc

Note: It is implementation-defined behavior to call 'dispose' with a type that is different than the original type used in the 'make' call. For the default implementation of 'dispose', it is undefined behavior to call dispose with a type that isn't the same one provided to 'make'. An allocator's implementation of make/dispose, however, may fully support this. For example, with a malloc_allocator or new_allocator, make and dispose don't require a computation for determining the original allocation size in order to dispose of the memory.; It is undefined behavior if T's destructor throws during a call to dispose

Parameters

alloc	the allocater to use for deallocation
p	to the type to destroy

◆ dispose_array()

template<typename Allocator >

template<typename Pointer , typename = std::enable_if_t<is_typed_pointer<Pointer>>>

static void bit::memory::allocator_traits< Allocator >::dispose_array	(	Allocator &	alloc,
		const Pointer &	p,
		size_type	n
	)

static

Disposes of the given array of T.

This calls the destructor of each T, and then deallocates it with alloc

Note: It is undefined behaviour to call 'dispose_array' with a size that is different than the original size allocated with a 'make_array' call.; It is undefined behavior to call 'dispose_array' with a type different than the original type used in the 'make' call. This is a result of requiring the size of the allocation, which is inferred from the size of type T. Additionally, casting an array to a different type is usually UB anyway.; It is undefined behavior if T's destructor throws during a call to dispose

Parameters

alloc	the allocater to use for deallocation
pointer	to the type to destroy

◆ expand()

template<typename Allocator >

static bool bit::memory::allocator_traits< Allocator >::expand	(	Allocator &	alloc,
		pointer	p,
		size_type	new_size
	)

static

Expands the memory addres located at p to contain new_size bytes.

This function returns a boolean indicating whether the memory region was able to be expanded to contain the new size. If the region could not contain the new size, nothing is changed, and false is returned.

Note: The default implementation if this is not defined in Allocator is to simply do nothing and return false

Parameters

alloc	the allocator to use for expansion
p	the pointer to expand
new_size	the new size to expand to

Returns: true if the memory region was expanded, false otherwise

◆ info()

template<typename Allocator >

static allocator_info bit::memory::allocator_traits< Allocator >::info ( const Allocator & alloc )

staticnoexcept

Gets the name of the specified allocator.

Note: Not all allocators are nameable or have a name specified. For these allocators, the string returned is typeid(Allocator).name(); The lifetime of the pointer returned is unmanaged, and is NOT the responsibility of the caller to free.

Parameters

alloc the allocator to get the name of

Returns: the name of the allocator

◆ is_unbounded()

template<typename Allocator >

static bool bit::memory::allocator_traits< Allocator >::is_unbounded ( const Allocator & alloc )

staticnoexcept

Determines if an allocator is unbounded.

The default behavior is to check for if max_size() returns the largest possible value for size_type.

Parameters

alloc the allocato to check

Returns: true if alloc is unbounded

◆ make()

template<typename Allocator >

template<typename T , typename... Args>

static detail::allocator_pointer_rebind<Allocator,T>::type bit::memory::allocator_traits< Allocator >::make	(	Allocator &	alloc,
		Args &&...	args
	)

static

Allocates and constructs a type T with the arguments args.

Note: This will call the out-of-memory handler if an allocation fails

Template Parameters

T	the type to construct

Parameters

alloc	the allocator to use for construction
args	the arguments to forward to T's constructor

Returns: pointer to the constructed type

◆ make_array() [1/2]

template<typename Allocator >

template<typename T >

static std::pointer_traits<pointer>::template rebind<T> bit::memory::allocator_traits< Allocator >::make_array	(	Allocator &	alloc,
		size_type	n
	)

static

Allocates and construct an array of type T.

Note: This will call the out-of-memory handler if an allocation fails

Template Parameters

T	the type to construct

Parameters

alloc	the allocator to use for construction
n	the size of the array
copy	an instance to copy to each array entry

Returns: pointer to the constructed array

◆ make_array() [2/2]

template<typename Allocator >

template<typename T >

static std::pointer_traits<pointer>::template rebind<T> bit::memory::allocator_traits< Allocator >::make_array	(	Allocator &	alloc,
		size_type	n,
		const T &	copy
	)

static

Allocates and construct an array of type T.

Note: This will call the out-of-memory handler if an allocation fails

Template Parameters

T	the type to construct

Parameters

alloc	the allocator to use for construction
n	the size of the array
copy	an instance to copy to each array entry

Returns: pointer to the constructed array

◆ max_size()

template<typename Allocator >

static size_type bit::memory::allocator_traits< Allocator >::max_size ( const Allocator & alloc )

staticnoexcept

Gets the maximum size allocateable from this allocator.

Note: the max_size does not guarantee that the size is able to be allocated at the time the value is queried; it just means that it is the maximum size that the allocator is capable of allocating from an empty state.

Parameters

alloc the allocator to get the max size from

Returns: the amount of bytes available for the largest possible allocation

◆ min_size()

template<typename Allocator >

static size_type bit::memory::allocator_traits< Allocator >::min_size ( const Allocator & alloc )

staticnoexcept

Gets the minimum size allocateable from this allocator.

Note: The default is 1, if this function is not defined

Parameters

alloc the allocator to get the min size from

Returns: the minimum amount of bytes able to allocated

◆ owns()

template<typename Allocator >

static bool bit::memory::allocator_traits< Allocator >::owns	(	const Allocator &	alloc,
		const_pointer	p
	)

staticnoexcept

Checks if the given allocator is known to own the specified pointer p.

Note: This directly invokes alloc.owns(p) . It is undefined behavior to invoke this if Allocator::owns is not defined; branches should instead be taken by using knows_ownership

Parameters

alloc	the allocator
p	the pointer

◆ pointer_to()

template<typename Allocator >

template<typename T >

static std::pointer_traits<pointer>::template rebind<T> bit::memory::allocator_traits< Allocator >::pointer_to	(	Allocator &	alloc,
		T &	x
	)

staticnoexcept

Converts a reference to an entry into a pointer used by this allocator.

This will attempt to call Allocator::pointer_to, if it exists, or std::pointer_traits::pointer_to if it doesn't

Parameters

alloc	the allocator to use
x	the value

Returns: pointer to the entry

◆ recommended_allocation_size()

template<typename Allocator >

size_type bit::memory::allocator_traits< Allocator >::recommended_allocation_size	(	const Allocator &	alloc,
		size_type	requested
	)

Determines the recommended allocation size of requested bytes from the given allocator.

Note: This invokes alloc.recommended_allocation_size(requested) if it is defined for the specified Allocator – otherwise it defaults to rounding 'requested' up to the next aligned value

Parameters

alloc	the allocator
requested	the amount of requested bytes

Returns: the recommended amount to allocate

◆ to_raw_pointer()

template<typename Allocator >

template<typename Pointer , typename = std::enable_if_t<is_typed_pointer<Pointer>>>

static std::pointer_traits<Pointer>::element_type* bit::memory::allocator_traits< Allocator >::to_raw_pointer	(	Allocator &	alloc,
		const Pointer &	p
	)

staticnoexcept

Converts a pointer from this allocator into a reference.

This will attempt to call Allocator::to_address, if it exists, *std::pointer_traits::to_address if it doesn't, and fall back to recursively dereferencing with operator->() until it results in a pointer otherwise.

Parameters

alloc	the allocator to use
p	the pointer

Returns: reference to the entry

◆ try_allocate() [1/2]

template<typename Allocator >

static pointer bit::memory::allocator_traits< Allocator >::try_allocate	(	Allocator &	alloc,
		size_type	size,
		size_type	align
	)

staticnoexcept

Attempts to allocate memory of at least size bytes, aligned to align boundary.

On failure, this function returns nullptr

Parameters

alloc	the allocator to allocate from
hint	pointer to a nearby memory location to allocate near
size	the size of the allocation
align	the alignment of the allocation

Returns: the pointer to the allocated memory

◆ try_allocate() [2/2]

template<typename Allocator >

static pointer bit::memory::allocator_traits< Allocator >::try_allocate	(	Allocator &	alloc,
		const_pointer	hint,
		size_type	size,
		size_type	align
	)

staticnoexcept

Attempts to allocate memory of at least size bytes, aligned to align boundary.

On failure, this function returns nullptr

Parameters

alloc	the allocator to allocate from
hint	pointer to a nearby memory location to allocate near
size	the size of the allocation
align	the alignment of the allocation

Returns: the pointer to the allocated memory

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

allocator_traits.hpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

template<typename Allocator> class bit::memory::allocator_traits< Allocator >

Member Typedef Documentation

◆ pointer_rebind

Member Function Documentation

◆ allocate() [1/2]

◆ allocate() [2/2]

◆ construct()

◆ deallocate()

◆ deallocate_all()

◆ destroy()

◆ dispose()

◆ dispose_array()

◆ expand()

◆ info()

◆ is_unbounded()

◆ make()

◆ make_array() [1/2]

◆ make_array() [2/2]

◆ max_size()

◆ min_size()

◆ owns()

◆ pointer_to()

◆ recommended_allocation_size()

◆ to_raw_pointer()

◆ try_allocate() [1/2]

◆ try_allocate() [2/2]

template<typename Allocator>
class bit::memory::allocator_traits< Allocator >