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

T	Type of the referenced object.
HANDLER	Base 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 ()
ConstReferencedType *	GetPointer () const
T *	operator-> ()
ConstReferencedType *	operator-> () const
std::conditional< std::is_void< T >::value, DeleteReturnType01, T >::type &	operator* ()
std::conditional< std::is_void< ConstReferencedType >::value, DeleteReturnType01, T >::type &	operator* () const
	operator T* ()
	operator ConstReferencedType * () const
	operator Bool () const
	operator Bool ()
const std::conditional< std::is_void< T >::value, DeleteReturnType01, T >::type &	operator[] (Int) const =delete
ResultRef< typename std::remove_const< T >::type >	MakeWritable (Bool resetOnError=true)
ResultRef< typename std::remove_const< T >::type >	MakeWritableDontCopy ()
Bool	HasMultipleReferences () const
std::conditional< std::is_void< T >::value, DeleteReturnType01, T >::type &	GetOrDefault () 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)
BaseRef &	operator= (T *src)
BaseRef &	operator= (std::nullptr_t src)
BaseRef &	operator= (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>
BaseRef &	operator= (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>
BaseRef &	operator= (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)
BaseRef &	operator= (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>
BaseRef &	operator= (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 >::type *	Disconnect ()
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< BaseRef >	Create (ARGS &&... args)
static const BaseRef &	DefaultValueRef ()
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 BaseRef &	PrivateDefaultValue (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

using DirectlyReferencedType = T

SelfType

using SelfType = BaseRef<T, HANDLER>

IsGenericBaseOf

using IsGenericBaseOf = std::true_type

Handler

using Handler = HANDLER

RefCompareType

using RefCompareType = RefCompare<MAXON_IS_COW_KIND(HANDLER::KIND), IsInterfaceType<T>::value>

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]

o

Pointer 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]

o

Pointer 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]

o

Pointer 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]

src

Another 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]

src

A 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]

src

Another 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]

src

Another 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]

resetOnError

If 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]

args

Arguments for the construcor.

Template Parameters

ARGS	Parameter 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]

src

New 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]

src

BaseRef 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]

src

Another 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]

src

BaseRef 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]

src

BaseRef 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]

b

Reference 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]

b

Reference 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]

b

Reference 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]

b

Pointer 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]

b

Reference 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]

b

Pointer 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]

b

Reference 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]

src

New 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 { ... }