BaseRef< T, HANDLER > Class Template Reference

#include <baseref.h>

Inheritance diagram for BaseRef< T, HANDLER >:

Detailed Description

template<typename T, typename HANDLER>
class maxon::BaseRef< T, HANDLER >

This is a general template for references of any kind. The characteristic feature of it is that special actions are triggered whenever the reference is set, cleared, changed or destructed. For example, a reference to a reference-counted object has to increase the reference count of the pointee when the pointer is set, and to decrease the count when the reference is cleared. Another example of reference is a unique reference which simply frees the pointee when it is cleared or destructed.

BaseRef delegates the specific behaviour to static members of the template parameter HANDLER. There are several implementations available to be used as HANDLER:

  • StrongRefHandler is used for objects which have a reference counter (used by StrongRef).
  • StrongCOWRefHandler has an additional copy-on-write semantics. I.e., if the pointee is referenced more than once, a copy is made before the pointee is modified through the BaseRef (used by StrongCOWRef).
  • UniqueRefHandler uses DeleteObj to release the memory, so the object's destructor is invoked (used by UniqueRef).
  • PointerHandler lets the BaseRef behave like an ordinary C++ pointer, so nothing is done when the pointer is changed (used by Pointer).

So if you want to have a reference to an object of type MyType with reference counting and copy-on-write semantics, you could use BaseRef<const MyType, StrongCOWRefHandler> which is equivalent to StrongCOWRef<MyType>.

Template Parameters
TType of the referenced object.
HANDLERBase class for BaseRef. This implements the specific behaviour whenever a reference is changed to point to another object, see above.
Note
BaseRef is neither atomic nor thread-safe..
  • After a BaseRef is guaranteed not to change anymore multiple threads can safely read from it concurrently.
  • Reading and writing on the same BaseRef from different threads will crash (the reference to an object might have been released by a writing thread before a reading thread was able to add a reference).
  • Writing to the same BaseRef from different threads will also crash because this implies a read operation (a write has to read the old value to release the reference to the previous object).
  • If you really have to read and write from multiple threads you could use the ThreadSafeRef class.

Public Types

using ReferencedType = T
 
using ConstReferencedType = typename ConstIf< T, Bool(HANDLER::KIND &VALUEKIND::DEEP_CONSTNESS)>::type
 
using DirectlyReferencedType = T
 
using SelfType = BaseRef< T, HANDLER >
 
template<typename D >
using IsGenericBaseOf = std::true_type
 
using Handler = HANDLER
 
using RefCompareType = RefCompare< MAXON_IS_COW_KIND(HANDLER::KIND), IsInterfaceType< T >::value >
 

Public Member Functions

T * GetPointer ()
 
ConstReferencedTypeGetPointer () const
 
T * operator-> ()
 
ConstReferencedTypeoperator-> () const
 
std::conditional< std::is_void< T >::value, DeleteReturnType01, T >::typeoperator* ()
 
std::conditional< std::is_void< ConstReferencedType >::value, DeleteReturnType01, T >::typeoperator* () const
 
 operator T* ()
 
 operator ConstReferencedType * () const
 
 operator Bool () const
 
 operator Bool ()
 
const std::conditional< std::is_void< T >::value, DeleteReturnType01, T >::typeoperator[] (Int) const =delete
 
ResultRef< typename std::remove_const< T >::typeMakeWritable (Bool resetOnError=true)
 
ResultRef< typename std::remove_const< T >::typeMakeWritableDontCopy ()
 
Bool HasMultipleReferences () const
 
std::conditional< std::is_void< T >::value, DeleteReturnType01, T >::typeGetOrDefault () const
 
 BaseRef ()
 
MAXON_IMPLICIT BaseRef (std::nullptr_t)=delete
 
MAXON_IMPLICIT BaseRef (T *o)
 
template<typename PTR >
 BaseRef (ForwardResultPtr< PTR > o)
 
 BaseRef (ResultPtr< T > o, Int)
 
 BaseRef (const BaseRef &src)
 
template<typename REF , typename = typename std::enable_if<!STD_IS_REPLACEMENT(base_of, BaseRef, REF) && maxon::HasErasedBase<typename REF::ReferencedType, ReferencedType>::value>::type>
MAXON_IMPLICIT BaseRef (const REF &src)
 
template<typename REF , typename = typename std::enable_if<!STD_IS_REPLACEMENT(base_of, BaseRef, REF) && maxon::HasErasedBase<typename REF::ReferencedType, ReferencedType>::value>::type>
MAXON_IMPLICIT BaseRef (REF &src)
 
BaseRefoperator= (T *src)
 
BaseRefoperator= (std::nullptr_t src)
 
BaseRefoperator= (const BaseRef &src)
 
template<typename REF , typename = typename std::enable_if<!STD_IS_REPLACEMENT(base_of, BaseRef, REF) && maxon::HasErasedBase<typename REF::ReferencedType, ReferencedType>::value>::type>
BaseRefoperator= (const REF &src)
 
template<typename REF , typename = typename std::enable_if<!STD_IS_REPLACEMENT(base_of, BaseRef, REF) && maxon::HasErasedBase<typename REF::ReferencedType, ReferencedType>::value>::type>
BaseRefoperator= (REF &src)
 
 BaseRef (BaseRef &&src)
 
template<typename REF , typename = typename std::enable_if<!STD_IS_REPLACEMENT(const, REF) && !STD_IS_REPLACEMENT(base_of, BaseRef, REF) && maxon::HasErasedBase<typename REF::ReferencedType, ReferencedType>::value>::type>
MAXON_IMPLICIT BaseRef (REF &&src)
 
BaseRefoperator= (BaseRef &&src)
 
template<typename REF , typename = typename std::enable_if<!STD_IS_REPLACEMENT(const, REF) && !STD_IS_REPLACEMENT(base_of, BaseRef, REF) && maxon::HasErasedBase<typename REF::ReferencedType, ReferencedType>::value>::type>
BaseRefoperator= (REF &&src)
 
 ~BaseRef ()
 
Bool operator== (const BaseRef &b) const
 
Bool operator!= (const BaseRef &b) const
 
Bool operator< (const BaseRef &b) const
 
 MAXON_OPERATOR_INEQUALITY (BaseRef)
 
Bool operator== (const T *b) const
 
Bool operator!= (const T *b) const
 
Bool operator== (typename std::remove_const< T >::type *b) const
 
Bool operator!= (typename std::remove_const< T >::type *b) const
 
Bool operator== (std::nullptr_t) const
 
Bool operator!= (std::nullptr_t) const
 
HashInt GetHashCode () const
 
UniqueHash GetUniqueHashCode () const
 
std::conditional< Bool(HANDLER::KIND &VALUEKIND::COW_MASK), typename std::remove_const< T >::type, T >::typeDisconnect ()
 
void PrivateSetTarget (ResultPtr< T > src)
 
void PrivateSetPointer (T *ptr)
 

Static Public Member Functions

static void PrivateLookupFn ()
 
static std::false_type GenericVarianceCheck (const void *)
 
template<typename... ARGS>
static MAXON_ATTRIBUTE_FORCE_INLINE ResultMemT< BaseRefCreate (ARGS &&... args)
 
static const BaseRefDefaultValueRef ()
 
static std::conditional< Bool(HANDLER::KIND &VALUEKIND::UNIQUE_REFERENCE), BaseRef, const BaseRef & >::type DefaultValue ()
 

Static Public Attributes

static constexpr Bool DIRECT_REF
 

Protected Attributes

union {
   T *   _object
 
   const void *   _impl
 
}; 
 

Private Member Functions

void operator+ (Int) const
 
void operator- (Int) const
 
void operator- (const BaseRef &) const
 

Static Private Member Functions

static const BaseRefPrivateDefaultValue (std::false_type *)
 
static BaseRef PrivateDefaultValue (std::true_type *)
 

Friends

template<typename , typename >
class BaseRef
 

Member Typedef Documentation

◆ ReferencedType

using ReferencedType = T

A type alias for the type the BaseRef points to.

◆ ConstReferencedType

using ConstReferencedType = typename ConstIf<T, Bool(HANDLER::KIND & VALUEKIND::DEEP_CONSTNESS)>::type

◆ DirectlyReferencedType

◆ SelfType

using SelfType = BaseRef<T, HANDLER>

◆ IsGenericBaseOf

using IsGenericBaseOf = std::true_type

◆ Handler

using Handler = HANDLER

◆ RefCompareType

Constructor & Destructor Documentation

◆ BaseRef() [1/10]

BaseRef ( )

◆ BaseRef() [2/10]

MAXON_IMPLICIT BaseRef ( std::nullptr_t  )
delete

◆ BaseRef() [3/10]

MAXON_IMPLICIT BaseRef ( T *  o)

Constructs a BaseRef, initializing the pointer with the given argument.

Parameters
[in]oPointer with which the BaseRef is initialized, may be nullptr.

◆ BaseRef() [4/10]

BaseRef ( ForwardResultPtr< PTR >  o)
explicit

Constructs a BaseRef with a pointer forwarded from a memory allocation. The template parameter is used to avoid unnecessary conversion from ResultPtr<X> to ResultPtr<const X>.

Parameters
[in]oPointer with which the BaseRef is initialized, may be nullptr on OutOfMemory.

◆ BaseRef() [5/10]

BaseRef ( ResultPtr< T >  o,
Int   
)
explicit

Constructs a BaseRef with a pointer forwarded from a memory allocation. To prevent accidental assignment from an allocation without error handling a dummy parameter has to be passed as well.

Parameters
[in]oPointer with which the BaseRef is initialized, may be nullptr on OutOfMemory.

◆ BaseRef() [6/10]

BaseRef ( const BaseRef< T, HANDLER > &  src)

Constructs a BaseRef, initializing the pointer with the pointer of another BaseRef.

Parameters
[in]srcAnother BaseRef whose internal pointer will be used to initialize this BaseRef.

◆ BaseRef() [7/10]

MAXON_IMPLICIT BaseRef ( const REF &  src)

Constructs a BaseRef, initializing the pointer with the pointer of another reference object.

Parameters
[in]srcA reference object whose internal pointer will be used to initialize this BaseRef.

◆ BaseRef() [8/10]

MAXON_IMPLICIT BaseRef ( REF &  src)

◆ BaseRef() [9/10]

BaseRef ( BaseRef< T, HANDLER > &&  src)

Constructs a new BaseRef by moving the pointer from src to this. The pointer of src will be a nullptr afterwards.

Parameters
[in]srcAnother BaseRef for the move.

◆ BaseRef() [10/10]

MAXON_IMPLICIT BaseRef ( REF &&  src)

Constructs a new BaseRef by moving the pointer from src to this. The pointer of src will be a nullptr afterwards.

Parameters
[in]srcAnother BaseRef for the move.

◆ ~BaseRef()

~BaseRef ( )

Destructs this BaseRef, including proper release of the reference.

Member Function Documentation

◆ PrivateLookupFn()

static void PrivateLookupFn ( )
static

◆ GenericVarianceCheck()

static std::false_type GenericVarianceCheck ( const void *  )
static

◆ GetPointer() [1/2]

T* GetPointer ( )

Returns the internal pointer of the BaseRef. You can also use operator-> to access members of the pointee directly through the BaseRef.

Returns
Internal pointer.

◆ GetPointer() [2/2]

ConstReferencedType* GetPointer ( ) const

Returns the internal pointer of the BaseRef. You can also use operator-> to access members of the pointee directly through the BaseRef.

Returns
Internal pointer.

◆ operator->() [1/2]

T* operator-> ( )

Allows direct access to the members of the pointee. You have to check for a nullptr before.

Returns
Internal pointer.

◆ operator->() [2/2]

ConstReferencedType* operator-> ( ) const

Allows direct access to the members of the pointee. You have to check for a nullptr before.

Returns
Internal pointer.

◆ operator*() [1/2]

std::conditional<std::is_void<T>::value, DeleteReturnType01, T>::type& operator* ( )

Dereferences the BaseRef. This yields the pointee as a reference. You have to check for a nullptr before.

Note
Not available for T = void.
Returns
Pointee as a reference.

◆ operator*() [2/2]

std::conditional<std::is_void<ConstReferencedType>::value, DeleteReturnType01, T>::type& operator* ( ) const

Dereferences the BaseRef. This yields the pointee as a reference. You have to check for a nullptr before.

Note
Not available for T = void.
Returns
Pointee as a reference.

◆ operator T*()

operator T* ( )

User-defined conversion to T*, unpacking the internal pointer.

Returns
Internal pointer.

◆ operator ConstReferencedType *()

operator ConstReferencedType * ( ) const

User-defined conversion to T*, unpacking the internal pointer.

Returns
Internal pointer.

◆ operator Bool() [1/2]

operator Bool ( ) const
explicit

Checks if the pointer is valid (i.e., not a nullptr).

Returns
True if the internal pointer is not a nullptr.

◆ operator Bool() [2/2]

operator Bool ( )
explicit

◆ operator[]()

const std::conditional<std::is_void<T>::value, DeleteReturnType01, T>::type& operator[] ( Int  ) const
delete

Superscript operator is not available.

Note
Not available for T = void.

◆ MakeWritable()

ResultRef<typename std::remove_const<T>::type> MakeWritable ( Bool  resetOnError = true)

Makes the pointee writable. Depending on the argument for the template parameter HANDLER, this may just return the original pointer, or it may replace the pointer by a new one pointing to a copy of the original pointee, and return the new pointer. The latter is the case for copy-on-write semantics if there is more than one reference to the pointee.

Parameters
[in]resetOnErrorIf true (the default), the reference will be reset when the copy fails. If false, the reference will stay the same, but the function returns nullptr.
Returns
Internal pointer, which might be a new pointer pointing to a copy of the original pointee, or nullptr if the copy failed.

◆ MakeWritableDontCopy()

ResultRef<typename std::remove_const<T>::type> MakeWritableDontCopy ( )

Makes the pointee writable. Depending on the argument for the template parameter HANDLER, this may just return the original pointer, or it may replace the pointer by a new one and return the new pointer. The latter is the case for copy-on-write semantics if there is more than one reference to the pointee. Unlike MakeWritable this function doesn't copy the contents of the original pointee if a new object is created. This is useful when you overwrite the content in the sequel anyway.

Returns
Internal pointer, which might be a new pointer, or nullptr if the copy failed.

◆ HasMultipleReferences()

Bool HasMultipleReferences ( ) const

Returns whether the referenced object has more than this single reference. For a null reference it will return false. For an object with one strong reference it will return false. For an object with a single strong reference and weak references it will return true. For an object with two strong references it will return true.

Returns
True if there's a referenced object and it has more than this single reference, false otherwise.

◆ GetOrDefault()

std::conditional<std::is_void<T>::value, DeleteReturnType01, T>::type& GetOrDefault ( ) const
Note
Not available for T = void.

◆ Create()

static MAXON_ATTRIBUTE_FORCE_INLINE ResultMemT<BaseRef> Create ( ARGS &&...  args)
static

Creates the referenced type.

Parameters
[in]argsArguments for the construcor.
Template Parameters
ARGSParameter types.
Returns
OK on success, FAILED only for OutOfMemoryerror.

◆ operator=() [1/7]

BaseRef& operator= ( T *  src)

Lets the BaseRef point to another object. This performs the necessary operations for removing the reference to the current pointee and adding the reference to the new pointee.

Parameters
[in]srcNew pointer, may be nullptr.

◆ operator=() [2/7]

BaseRef& operator= ( std::nullptr_t  src)

Resets the internal pointer to nullptr, which includes the proper release of the reference.

◆ operator=() [3/7]

BaseRef& operator= ( const BaseRef< T, HANDLER > &  src)

Lets the BaseRef point to the object of another BaseRef. This performs the necessary operations for removing the reference to the current pointee and adding the reference to the new pointee.

Parameters
[in]srcBaseRef of which the pointer will be used.

◆ operator=() [4/7]

BaseRef& operator= ( const REF &  src)

Lets the BaseRef point to the object of another reference object. This performs the necessary operations for removing the reference to the current pointee and adding the reference to the new pointee.

Parameters
[in]srcAnother reference of which the pointer will be used.

◆ operator=() [5/7]

BaseRef& operator= ( REF &  src)

◆ operator=() [6/7]

BaseRef& operator= ( BaseRef< T, HANDLER > &&  src)

Moves the internal pointer from src to this. src will be a nullptr reference afterwards.

Parameters
[in]srcBaseRef whose internal pointer shall be moved to this BaseRef.

◆ operator=() [7/7]

BaseRef& operator= ( REF &&  src)

Moves the internal pointer from src to this. src will be a nullptr reference afterwards. Moves from BaseRef with different HANDLER as well as interface references.

Parameters
[in]srcBaseRef whose internal pointer shall be moved to this BaseRef.

◆ operator==() [1/4]

Bool operator== ( const BaseRef< T, HANDLER > &  b) const

Returns true when this and b are equal as determined by RefCompare.

Parameters
[in]bReference to compare with.
Returns
True when this and b are equal, false otherwise.

◆ operator!=() [1/4]

Bool operator!= ( const BaseRef< T, HANDLER > &  b) const

Returns true when this and b are not equal as determined by RefCompare.

Parameters
[in]bReference to compare with.
Returns
True when this and b are not equal, false otherwise.

◆ operator<()

Bool operator< ( const BaseRef< T, HANDLER > &  b) const

Returns true when this is less than b as determined by RefCompare.

Parameters
[in]bReference to compare with.
Returns
True when this is less than b, false otherwise.

◆ MAXON_OPERATOR_INEQUALITY()

MAXON_OPERATOR_INEQUALITY ( BaseRef< T, HANDLER >  )

◆ operator==() [2/4]

Bool operator== ( const T *  b) const

Returns true when this and b are equal as determined by RefCompare.

Parameters
[in]bPointer to compare with.
Returns
True when this and b are equal, false otherwise.

◆ operator!=() [2/4]

Bool operator!= ( const T *  b) const

Returns true when this and b are not equal as determined by RefCompare.

Parameters
[in]bReference to compare with.
Returns
True when this and b are not equal, false otherwise.

◆ operator==() [3/4]

Bool operator== ( typename std::remove_const< T >::type b) const

Returns true when this and b are equal as determined by RefCompare.

Parameters
[in]bPointer to compare with.
Returns
True when this and b are equal, false otherwise.

◆ operator!=() [3/4]

Bool operator!= ( typename std::remove_const< T >::type b) const

Returns true when this and b are not equal as determined by RefCompare.

Parameters
[in]bReference to compare with.
Returns
True when this and b are not equal, false otherwise.

◆ operator==() [4/4]

Bool operator== ( std::nullptr_t  ) const

Returns true when this and a null reference are equal as determined by RefCompare.

Returns
True when this and nullptr are equal, false otherwise.

◆ operator!=() [4/4]

Bool operator!= ( std::nullptr_t  ) const

Returns true when this and a null reference are not equal as determined by RefCompare.

Returns
True when this and nullptr are not equal, false otherwise.

◆ GetHashCode()

HashInt GetHashCode ( ) const

Returns the hash code of the reference. For COW references this is the hash code of the referenced object, otherwise it's the hash code of the pointer.

Returns
The reference's hash code.

◆ GetUniqueHashCode()

UniqueHash GetUniqueHashCode ( ) const

Returns the hash value of the reference. For COW references this is the hash value of the referenced object, otherwise it's the hash value of the pointer.

Returns
The reference's hash value.

◆ DefaultValueRef()

static const BaseRef& DefaultValueRef ( )
static

◆ DefaultValue()

static std::conditional<Bool(HANDLER::KIND & VALUEKIND::UNIQUE_REFERENCE), BaseRef, const BaseRef&>::type DefaultValue ( )
static

◆ Disconnect()

std::conditional<Bool(HANDLER::KIND & VALUEKIND::COW_MASK), typename std::remove_const<T>::type, T>::type* Disconnect ( )

Sets the internal pointer to nullptr and returns its previous value. This moves the ownership of the object from this BaseRef to the invoking code, so you have to take care of proper deallocation once the object isn't needed any longer.

If this BaseRef is a strong reference, the reference count must be exactly 1 before the call, otherwise a nullptr will be returned.

Returns
The pointer to the previously referenced object.

◆ PrivateSetTarget()

void PrivateSetTarget ( ResultPtr< T >  src)

Lets the BaseRef point to another freshly allocated object. This performs the necessary operations for removing the reference to the current pointee and adding the reference to the new pointee.

Parameters
[in]srcNew pointer, may be nullptr.

◆ PrivateSetPointer()

void PrivateSetPointer ( T *  ptr)

◆ operator+()

void operator+ ( Int  ) const
private

◆ operator-() [1/2]

void operator- ( Int  ) const
private

◆ operator-() [2/2]

void operator- ( const BaseRef< T, HANDLER > &  ) const
private

◆ PrivateDefaultValue() [1/2]

static const BaseRef& PrivateDefaultValue ( std::false_type *  )
staticprivate

◆ PrivateDefaultValue() [2/2]

static BaseRef PrivateDefaultValue ( std::true_type *  )
staticprivate

Friends And Related Function Documentation

◆ BaseRef

friend class BaseRef
friend

Member Data Documentation

◆ DIRECT_REF

constexpr Bool DIRECT_REF
staticconstexpr

◆ _object

T* _object

◆ _impl

const void* _impl

◆ 

union { ... }