Documentation of memory

( foonathan/memory)

std_allocator< T, RawAllocator, Mutex > Class Template Reference

Detailed Description

template<typename T, class RawAllocator, class Mutex = default_mutex>
class foonathan::memory::std_allocator< T, RawAllocator, Mutex >

Wraps a RawAllocator and makes it a "normal" Allocator.

It allows using a RawAllocator anywhere a Allocator is required. It stores the allocator as allocator_reference to allow required copying of a Allocator, synchronization is done via a Mutex which defaults to default_mutex.

Typedefs

using value_type = T
 
using pointer = T *
 
using const_pointer = const T *
 
using reference = T &
 
using const_reference = const T &
 
using size_type = std::size_t
 
using difference_type = std::ptrdiff_t
 
using propagate_on_container_swap = typename prop_traits::propagate_on_container_swap
 
using propagate_on_container_move_assignment = typename prop_traits::propagate_on_container_move_assignment
 
using propagate_on_container_copy_assignment = typename prop_traits::propagate_on_container_copy_assignment
 
using allocator_type = typename alloc_reference::allocator_type
 
using mutex = Mutex
 

Member Functions

 std_allocator () noexcept
 
template<class RawAlloc >
 std_allocator (RawAlloc &alloc,) noexcept
 
template<class RawAlloc >
 std_allocator (const RawAlloc &alloc,) noexcept
 
 std_allocator (const alloc_reference &alloc) noexcept
 
template<class StoragePolicy , class OtherMut >
 std_allocator (const allocator_storage< StoragePolicy, OtherMut > &)=delete
 
std_allocator< T, RawAllocator, Mutex > select_on_container_copy_construction () const
 
pointer allocate (size_type n, void *=nullptr)
 
void deallocate (pointer p, size_type n) noexcept
 
template<typename U , typename... Args>
void construct (U *p, Args &&... args)
 
template<typename U >
void destroy (U *p) noexcept
 
size_type max_size () const noexcept
 
template<typename U >
 std_allocator (const std_allocator< U, RawAllocator, Mutex > &alloc) noexcept
 
template<typename U >
 std_allocator (std_allocator< U, RawAllocator, Mutex > &alloc) noexcept
 
auto get_allocator () noexcept -> decltype(std::declval< alloc_reference >().get_allocator())
 
auto get_allocator () const noexcept -> decltype(std::declval< const alloc_reference >().get_allocator())
 
auto lock () noexcept -> decltype(std::declval< alloc_reference >().lock())
 
auto lock () const noexcept -> decltype(std::declval< const alloc_reference >().lock())
 

Related Functions

template<typename T , typename U , class Impl , class Mut >
bool operator== (const std_allocator< T, Impl, Mut > &lhs, const std_allocator< U, Impl, Mut > &rhs) noexcept
 
template<typename T , typename U , class Impl , class Mut >
bool operator!= (const std_allocator< T, Impl, Mut > &lhs, const std_allocator< U, Impl, Mut > &rhs) noexcept
 
template<typename T , class RawAllocator >
auto make_std_allocator (RawAllocator &&allocator) noexcept -> std_allocator< T, typename std::decay< RawAllocator >::type >
 
template<typename T , class Mutex , class RawAllocator >
auto make_std_allocator (RawAllocator &&allocator) noexcept -> std_allocator< T, typename std::decay< RawAllocator >::type, Mutex >
 

Constructors

§ std_allocator() [1/7]

std_allocator ( )
noexcept
Effects:
Default constructs it by storing a default constructed, stateless RawAllocator inside the reference.
Requires:
The RawAllocator type is stateless, otherwise the body of this function will not compile.

§ std_allocator() [2/7]

std_allocator ( RawAlloc &  alloc)
noexcept
Effects:
Creates it from a reference to a RawAllocator. It will store an allocator_reference to it.
Requires:
The expression allocator_reference<RawAllocator, Mutex>(alloc) is well-formed, that is either RawAlloc is the same as RawAllocator or RawAllocator is the tag type any_allocator. If the requirement is not fulfilled this function does not participate in overload resolution.
Note
The caller has to ensure that the lifetime of the RawAllocator is at least as long as the lifetime of this std_allocator object.

§ std_allocator() [3/7]

std_allocator ( const RawAlloc &  alloc)
noexcept
Effects:
Creates it from a stateless, temporary RawAllocator object. It will not store a reference but create it on the fly.
Requires:
The RawAllocator is stateless and the expression allocator_reference<RawAllocator, Mutex>(alloc) is well-formed as above, otherwise this function does not participate in overload resolution.

§ std_allocator() [4/7]

std_allocator ( const alloc_reference alloc)
noexcept
Effects:
Creates it from another allocator_reference using the same allocator type and mutex.

§ std_allocator() [5/7]

std_allocator ( const allocator_storage< StoragePolicy, OtherMut > &  )
delete

Implicit conversion from any other allocator_storage is forbidden to prevent accidentally wrapping another allocator_storage inside a allocator_reference.

§ std_allocator() [6/7]

std_allocator ( const std_allocator< U, RawAllocator, Mutex > &  alloc)
noexcept
Effects:
Creates it from another std_allocator allocating a different type. This is required by the Allcoator concept and simply takes the same allocator_reference.

§ std_allocator() [7/7]

std_allocator ( std_allocator< U, RawAllocator, Mutex > &  alloc)
noexcept
Effects:
Creates it from another std_allocator allocating a different type. This is required by the Allcoator concept and simply takes the same allocator_reference.

Member Functions

§ select_on_container_copy_construction()

std_allocator<T, RawAllocator, Mutex> select_on_container_copy_construction ( ) const
Returns:
A copy of the allocator. This is required by the Allocator concept and forwards to the propagation_traits.

§ allocate()

pointer allocate ( size_type  n,
void *  = nullptr 
)
Effects:
Allocates memory using the underlying RawAllocator. If n is 1, it will call allocate_node(sizeof(T), alignof(T)), otherwise allocate_array(n, sizeof(T), alignof(T)).
Returns:
A pointer to a memory block suitable for n objects of type T.
Throws:
Anything thrown by the RawAllocator.

§ deallocate()

void deallocate ( pointer  p,
size_type  n 
)
noexcept
Effects:
Deallcoates memory using the underlying RawAllocator. It will forward to the deallocation function in the same way as in allocate().
Requires:
The pointer must come from a previous call to allocate() with the same n on this object or any copy of it.

§ construct()

void construct ( U *  p,
Args &&...  args 
)
Effects:
Creates an object of type U at given address using the passed arguments.

§ destroy()

void destroy ( U *  p)
noexcept
Effects:
Calls the destructor for an object of type U at given address.

§ max_size()

size_type max_size ( ) const
noexcept
Returns:
The maximum size for an allocation which is max_array_size() / sizeof(value_type). This is only an upper bound, not the exact maximum.

§ get_allocator() [1/2]

auto get_allocator ( ) -> decltype(std::declval<alloc_reference>().get_allocator())
noexcept
Effects:
Returns a reference to the referenced allocator.
Returns:
For stateful allocators: A (const) reference to the stored allocator. For stateless allocators: A temporary constructed allocator.
Note
This does not lock the Mutex.

§ get_allocator() [2/2]

auto get_allocator ( ) const -> decltype(std::declval<const alloc_reference>().get_allocator())
noexcept
Effects:
Returns a reference to the referenced allocator.
Returns:
For stateful allocators: A (const) reference to the stored allocator. For stateless allocators: A temporary constructed allocator.
Note
This does not lock the Mutex.

§ lock() [1/2]

auto lock ( ) -> decltype(std::declval<alloc_reference>().lock())
noexcept
Returns:
A proxy object that acts like a pointer to the stored allocator. It cannot be reassigned to point to another allocator object and only moving is supported, which is destructive. As long as the proxy object lives and is not moved from, the Mutex will be kept locked.
Requires:
The result of get_allocator() must not be a temporary, otherwise the body of this function will not compile.

§ lock() [2/2]

auto lock ( ) const -> decltype(std::declval<const alloc_reference>().lock())
noexcept
Returns:
A proxy object that acts like a pointer to the stored allocator. It cannot be reassigned to point to another allocator object and only moving is supported, which is destructive. As long as the proxy object lives and is not moved from, the Mutex will be kept locked.
Requires:
The result of get_allocator() must not be a temporary, otherwise the body of this function will not compile.

Related Functions

§ operator==()

bool operator== ( const std_allocator< T, Impl, Mut > &  lhs,
const std_allocator< U, Impl, Mut > &  rhs 
)
related
Effects:
Compares two std_allocator object, they are equal if either stateless or reference the same allocator.
Returns:
The result of the comparision for equality.

§ operator!=()

bool operator!= ( const std_allocator< T, Impl, Mut > &  lhs,
const std_allocator< U, Impl, Mut > &  rhs 
)
related
Effects:
Compares two std_allocator object, they are equal if either stateless or reference the same allocator.
Returns:
The result of the comparision for inequality.

§ make_std_allocator() [1/2]

auto make_std_allocator ( RawAllocator &&  allocator) -> std_allocator<T, typename std::decay<RawAllocator>::type>
related
Returns:
A new std_allocator for a given type using a certain allocator object.

§ make_std_allocator() [2/2]

auto make_std_allocator ( RawAllocator &&  allocator) -> std_allocator<T, typename std::decay<RawAllocator>::type, Mutex>
related
Returns:
A new std_allocator for a given type and Mutex using a certain allocator object.