Description:

template<typename T, typename TAllocator = HeapAllocator>
class alib::containers::SharedVal< T, TAllocator >

This templated class is an alternative for C++ standard library type std::shared_ptr with important restrictions:

Instead of managing a pointer, a value is managed.
It is not possible to store derived types within this type, which is a common use case with std::shared_ptr, especially in consideration with dynamic (virtual) types.
This implies that no abstract types can be stored.
This implementation misses the coexistence of sibling type std::weak_ptr and corresponding functionality.
This implementation misses an equivalent to method owner_before and corresponding comparison operators.
This implementation misses dedicated array support (at least as of today).

The advantages are:

The type has a footprint of only sizeof(void*), where the standard's type has a size of two pointers.
An internal second pointer-dereferencing is avoided when accessing the shared value.
The type performs only one allocation. (Common implementations of the standard's type perform two allocations.)
The type supports storing references to ALib {lang;Allocator;allocators} which are used for allocation and freeing of memory. Allocators can be of "heavy" weight and are never copied by value.

Note that despite being named SharedVal, which is in contrast to sibling type SharedPtr, the type still behaves like a pointer. It can be nulled, value nullptr can be assigned, and member access is performed with the operator->. And of course the object is destructed, and the memory is freed in case the last copy of an instance is nulled or gets out of scope. A different naming proposal could have been SharedStaticPtr to indicate that no dynamic conversions and abstract types are applicable.

See also

Class SharedPtr which allows storing derived, dynamic types.
Class TSharedMonoVal of module ALib Monomem, which incorporates an own embedded instance of class TMonoAllocator. This allocator can be used for further monotonic allocations by the contained type or other code entities that receive the shared pointer.

Template Parameters

T	The custom type that is shared with this pointer.
TAllocator	The allocator that is used to allocate an instance of T together with a reference counter and optionally a reference to such allocator if passed with construction.

Definition at line 54 of file sharedval.inl.

Inner Type Index:
struct	FieldMembersNoTA
	Fields if TAllocator is default-constructible (e.g., HeapAllocator). More...

struct	FieldMembersWithAllocator
	Fields if TAllocator is not default-constructible (not HeapAllocator). More...

Public Type Index:
using	AllocatorType = TAllocator
	Exposes the allocator as given with template parameter TAllocator.

using	StoredType = T
	Exposes the stored type specified with template parameter T.

Public Static Method Index:
static constexpr size_t	SizeOfAllocation ()

Public Method Index:
	SharedVal () noexcept
	Default Constructor. Leaves this object nulled.

	SharedVal (const SharedVal &other) noexcept

	SharedVal (SharedVal &&other) noexcept

	SharedVal (std::nullptr_t) noexcept

template<typename... TArgs, typename TRequires = TAllocator> requires (!std::default_initializable<TRequires>)
	SharedVal (TAllocator &allocator, TArgs &&... args)

template<typename... TArgs, typename TRequires = TAllocator> requires ( std::default_initializable<TRequires> && (sizeof...(TArgs) > 0) && ( sizeof...(TArgs) != 1 \|\| !std::same_as<std::decay_t<std::tuple_element_t<0, std::tuple<TArgs...>>>, SharedVal> ) && std::is_constructible_v<T, TArgs...> )
	SharedVal (TArgs &&... args)

	~SharedVal ()

T *	Get () const

AllocatorType &	GetAllocator () const

bool	IsNulled () const noexcept

	operator bool () const noexcept

bool	operator!= (std::nullptr_t) const noexcept

T &	operator* () const

T *	operator-> () const

SharedVal &	operator= (const SharedVal &other) noexcept

SharedVal &	operator= (SharedVal &&other) noexcept

void	operator= (std::nullptr_t)
	Assignment of `nullptr`. Same as SetNulled.

bool	operator== (std::nullptr_t) const noexcept

void	SetNulled ()

bool	Unique () const noexcept

unsigned int	UseCount () const noexcept

Protected Type Index:
using	FieldMembers

Protected Field Index:
FieldMembers *	members
	The stored data.

Protected Method Index:
T *	getP () const noexcept

T &	getR () const noexcept

Type Definition Details:

◆ AllocatorType

template<typename T, typename TAllocator = HeapAllocator>

using alib::containers::SharedVal< T, TAllocator >::AllocatorType = TAllocator

Exposes the allocator as given with template parameter TAllocator.

Definition at line 135 of file sharedval.inl.

◆ FieldMembers

template<typename T, typename TAllocator = HeapAllocator>

using alib::containers::SharedVal< T, TAllocator >::FieldMembers

protected

Initial value:

 std::conditional_t< std::is_default_constructible<TAllocator>::value,
                                             FieldMembersNoTA,
                                             FieldMembersWithAllocator>

The type of the stored data. Note that we cannot use helper AllocatorMember, because type T could be derived from the same base class and this would break EBO rules, that force the compiler to give two distinguishable members, inherited or not, a different address.

Definition at line 113 of file sharedval.inl.

◆ StoredType

template<typename T, typename TAllocator = HeapAllocator>

using alib::containers::SharedVal< T, TAllocator >::StoredType = T

Exposes the stored type specified with template parameter T.

Definition at line 138 of file sharedval.inl.

Field Details:

◆ members

template<typename T, typename TAllocator = HeapAllocator>

FieldMembers* alib::containers::SharedVal< T, TAllocator >::members

protected

The stored data.

Definition at line 118 of file sharedval.inl.

Constructor(s) / Destructor Details:

◆ SharedVal() [1/6]

template<typename T, typename TAllocator = HeapAllocator>

alib::containers::SharedVal< T, TAllocator >::SharedVal ( )

inlinenoexcept

Default Constructor. Leaves this object nulled.

Definition at line 141 of file sharedval.inl.

◆ SharedVal() [2/6]

template<typename T, typename TAllocator = HeapAllocator>

alib::containers::SharedVal< T, TAllocator >::SharedVal ( std::nullptr_t )

inlinenoexcept

Constructs an empty instance from std::nullptr. This constructor is necessary to allow assignment of std::nullptr to values of this type, which clears the automatic pointer.

Definition at line 146 of file sharedval.inl.

◆ SharedVal() [3/6]

template<typename T, typename TAllocator = HeapAllocator>

alib::containers::SharedVal< T, TAllocator >::SharedVal ( const SharedVal< T, TAllocator > & other )

inlinenoexcept

Copy Constructor. Increases the reference counter of the shared pointer (in case given other is not nulled).

Parameters

other The object to copy.

Definition at line 151 of file sharedval.inl.

◆ SharedVal() [4/6]

template<typename T, typename TAllocator = HeapAllocator>

alib::containers::SharedVal< T, TAllocator >::SharedVal ( SharedVal< T, TAllocator > && other )

inlinenoexcept

Move Constructor. Does not increase the reference counter, instead nulls the other.

Parameters

other The object to copy.

Definition at line 157 of file sharedval.inl.

◆ SharedVal() [5/6]

template<typename T, typename TAllocator = HeapAllocator>

template<typename... TArgs, typename TRequires = TAllocator>
requires (!std::default_initializable<TRequires>)

alib::containers::SharedVal< T, TAllocator >::SharedVal	(	TAllocator &	allocator,
		TArgs &&...	args )

inline

Constructor taking an allocator along with the construction parameters for the instance of T. The allocator is used allocate the needed memory (one allocation) and the reference to it is internally stored, to be able to free the memory later.

Note: This constructor is accepted by the compiler only if template type TAllocator is not default-constructible.

Template Parameters

TArgs	The argument types used for constructing T.
TRequires	Defaulted template parameter. Must not be specified.

Parameters

allocator	The allocator used to allocate and free needed storage.
args	The arguments for constructing T.

Definition at line 216 of file sharedval.inl.

◆ SharedVal() [6/6]

template<typename T, typename TAllocator = HeapAllocator>

template<typename... TArgs, typename TRequires = TAllocator>
requires ( std::default_initializable<TRequires> && (sizeof...(TArgs) > 0) && ( sizeof...(TArgs) != 1 || !std::same_as<std::decay_t<std::tuple_element_t<0, std::tuple<TArgs...>>>, SharedVal> ) && std::is_constructible_v<T, TArgs...> )

alib::containers::SharedVal< T, TAllocator >::SharedVal ( TArgs &&... args )

inline

Constructor missing the allocator instance. To be used only with allocators that are default-constructible (like HeapAllocator is).

Note

This constructor is accepted by the compiler only if

TAllocator is default-constructible, and
the variadic argument list is not empty (here default construction is chosen), and
the variadic arguments would not match to the copy or move constructor, and
the variadic arguments are constructing type T.

If this was not done, this constructor was chosen for copy constructors of this type. In this case, the compilation of this constructor would fail when initializing field member.

Template Parameters

TArgs	The argument types used for constructing T.
TRequires	Defaulted template parameter. Must not be specified.

Parameters

args	The arguments for constructing T.

Definition at line 246 of file sharedval.inl.

◆ ~SharedVal()

template<typename T, typename TAllocator = HeapAllocator>

alib::containers::SharedVal< T, TAllocator >::~SharedVal ( )

inline

Destructor. If this is the last copy, the destructor of T is invoked and the memory is freed to TAllocator.

Definition at line 251 of file sharedval.inl.

Method Details:

◆ Get()

template<typename T, typename TAllocator = HeapAllocator>

T * alib::containers::SharedVal< T, TAllocator >::Get ( ) const

inline

Returns a non-constant pointer to the stored object of type T.

Returns: A pointer to T.

Definition at line 308 of file sharedval.inl.

◆ GetAllocator()

template<typename T, typename TAllocator = HeapAllocator>

AllocatorType & alib::containers::SharedVal< T, TAllocator >::GetAllocator ( ) const

inline

Returns: The allocator given with construction that will be used to free the memory that had been allocated, at the moment the use counter becomes 0.

Definition at line 264 of file sharedval.inl.

◆ getP()

template<typename T, typename TAllocator = HeapAllocator>

T * alib::containers::SharedVal< T, TAllocator >::getP ( ) const

inlineprotectednoexcept

Internal shortcut to receive the custom member.

Returns: The pointer to the contained type, or nullptr in case this is empty.

Definition at line 122 of file sharedval.inl.

◆ getR()

template<typename T, typename TAllocator = HeapAllocator>

T & alib::containers::SharedVal< T, TAllocator >::getR ( ) const

inlineprotectednoexcept

Internal shortcut to receive a reference to the custom member. Asserts in debug-compilations.

Returns: A reference the contained type.

Definition at line 128 of file sharedval.inl.

◆ IsNulled()

template<typename T, typename TAllocator = HeapAllocator>

bool alib::containers::SharedVal< T, TAllocator >::IsNulled ( ) const

inlinenoexcept

Returns true if this is an empty instance.

Returns: true if UseCount is 0, false otherwise.

Definition at line 290 of file sharedval.inl.

◆ operator bool()

template<typename T, typename TAllocator = HeapAllocator>

alib::containers::SharedVal< T, TAllocator >::operator bool ( ) const

inlinenoexcept

Returns: true if this instance is not nulled, false otherwise.

Definition at line 304 of file sharedval.inl.

◆ operator!=()

template<typename T, typename TAllocator = HeapAllocator>

bool alib::containers::SharedVal< T, TAllocator >::operator!= ( std::nullptr_t ) const

inlinenoexcept

Comparison with nullptr.

Returns: false if UseCount is greater than 0, false otherwise.

Definition at line 301 of file sharedval.inl.

◆ operator*()

template<typename T, typename TAllocator = HeapAllocator>

T & alib::containers::SharedVal< T, TAllocator >::operator* ( ) const

inline

Overloaded operator to access members of custom type T

Returns: A pointer to T.

Definition at line 316 of file sharedval.inl.

◆ operator->()

template<typename T, typename TAllocator = HeapAllocator>

T * alib::containers::SharedVal< T, TAllocator >::operator-> ( ) const

inline

Overloaded operator to access members of custom type T

Returns: A pointer to T.

Definition at line 312 of file sharedval.inl.

◆ operator=() [1/3]

template<typename T, typename TAllocator = HeapAllocator>

SharedVal & alib::containers::SharedVal< T, TAllocator >::operator= ( const SharedVal< T, TAllocator > & other )

inlinenoexcept

Copy Assignment Operator. Cares for self-assignment and assignment of a shared pointer with the same content. Otherwise, the reference counter of the current object is decreased, disposed if necessary, and then the object in other is copied to this object.

Parameters

other The object to copy into this one.

Returns: A reference to this.

Definition at line 166 of file sharedval.inl.

◆ operator=() [2/3]

template<typename T, typename TAllocator = HeapAllocator>

SharedVal & alib::containers::SharedVal< T, TAllocator >::operator= ( SharedVal< T, TAllocator > && other )

inlinenoexcept

Move Assignment Operator. Cares for self-assignment. Otherwise, the object in other is copied to this.

Parameters

other The object to move into this one.

Returns: A reference to this.

Definition at line 187 of file sharedval.inl.

◆ operator=() [3/3]

template<typename T, typename TAllocator = HeapAllocator>

void alib::containers::SharedVal< T, TAllocator >::operator= ( std::nullptr_t )

inline

Assignment of nullptr. Same as SetNulled.

Definition at line 293 of file sharedval.inl.

◆ operator==()

template<typename T, typename TAllocator = HeapAllocator>

bool alib::containers::SharedVal< T, TAllocator >::operator== ( std::nullptr_t ) const

inlinenoexcept

Comparison with nullptr.

Returns: true if UseCount is greater than 0, false otherwise.

Definition at line 297 of file sharedval.inl.

◆ SetNulled()

template<typename T, typename TAllocator = HeapAllocator>

void alib::containers::SharedVal< T, TAllocator >::SetNulled ( )

inline

Sets this object to nulled state, as if default constructed or nullptr was assigned. If no shared copy exists, all data is destructed and memory is freed.
As an alternative to this method, nullptr can be assigned.

Definition at line 286 of file sharedval.inl.

◆ SizeOfAllocation()

template<typename T, typename TAllocator = HeapAllocator>

constexpr size_t alib::containers::SharedVal< T, TAllocator >::SizeOfAllocation ( )

inlinestaticconstexpr

Returns: The size of the memory that is allocated for the T as well as for the reference counter and the allocator member. (To whom it may concern.)

Definition at line 260 of file sharedval.inl.

◆ Unique()

template<typename T, typename TAllocator = HeapAllocator>

bool alib::containers::SharedVal< T, TAllocator >::Unique ( ) const

inlinenoexcept

Returns true if the UseCount is 1.

Returns: true if this instance is set but not shared.

Definition at line 280 of file sharedval.inl.

◆ UseCount()

template<typename T, typename TAllocator = HeapAllocator>

unsigned int alib::containers::SharedVal< T, TAllocator >::UseCount ( ) const

inlinenoexcept

Returns the number of shared usages. In a multithreaded environment, the value returned is approximate.

Returns: The number of shared usages. If this instance was default-constructed, moved, method SetNulled was called, or nullptr was assigned, then 0 is returned.

Definition at line 275 of file sharedval.inl.

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

sharedval.inl

Description:

Inner Type Index:

Public Type Index:

Public Static Method Index:

Public Method Index:

Protected Type Index:

Protected Field Index:

Protected Method Index:

Type Definition Details:

◆ AllocatorType

◆ FieldMembers

◆ StoredType

Field Details:

◆ members

Constructor(s) / Destructor Details:

◆ SharedVal() [1/6]

◆ SharedVal() [2/6]

◆ SharedVal() [3/6]

◆ SharedVal() [4/6]

◆ SharedVal() [5/6]

◆ SharedVal() [6/6]

◆ ~SharedVal()

Method Details:

◆ Get()

◆ GetAllocator()

◆ getP()

◆ getR()

◆ IsNulled()

◆ operator bool()

◆ operator!=()

◆ operator*()

◆ operator->()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ operator==()

◆ SetNulled()

◆ SizeOfAllocation()

◆ Unique()

◆ UseCount()