#include <baseref.h>
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 & | GetOrNull () 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 & | NullValueRef () |
| static std::conditional< Bool(HANDLER::KIND &VALUEKIND::UNIQUE_REFERENCE), BaseRef, const BaseRef & >::type | NullValue () |
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 & | PrivateNullValue (std::false_type *) |
| static BaseRef | PrivateNullValue (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
◆ 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]
|
delete |
◆ BaseRef() [3/10]
| MAXON_IMPLICIT BaseRef | ( | T * | o | ) |
◆ BaseRef() [4/10]
|
explicit |
◆ BaseRef() [5/10]
◆ BaseRef() [6/10]
◆ BaseRef() [7/10]
| MAXON_IMPLICIT BaseRef | ( | const REF & | src | ) |
◆ BaseRef() [8/10]
| MAXON_IMPLICIT BaseRef | ( | REF & | src | ) |
◆ BaseRef() [9/10]
◆ BaseRef() [10/10]
| MAXON_IMPLICIT BaseRef | ( | REF && | src | ) |
◆ ~BaseRef()
Member Function Documentation
◆ PrivateLookupFn()
|
static |
◆ GenericVarianceCheck()
|
static |
◆ GetPointer() [1/2]
| T* GetPointer | ( | ) |
◆ GetPointer() [2/2]
| ConstReferencedType* GetPointer | ( | ) | const |
◆ 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]
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]
|
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]
|
explicit |
◆ operator[]()
|
delete |
Superscript operator is not available.
- Note
- Not available for T = void.
◆ MakeWritable()
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()
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.
◆ GetOrNull()
- Note
- Not available for T = void.
◆ Create()
|
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]
◆ 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]
◆ operator=() [7/7]
| BaseRef& operator= | ( | REF && | src | ) |
◆ operator==() [1/4]
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]
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<()
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]
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]
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.
◆ NullValueRef()
|
static |
◆ NullValue()
|
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+()
|
private |
◆ operator-() [1/2]
|
private |
◆ operator-() [2/2]
|
private |
◆ PrivateNullValue() [1/2]
|
staticprivate |
◆ PrivateNullValue() [2/2]
|
staticprivate |
Friends And Related Function Documentation
◆ BaseRef
|
friend |
Member Data Documentation
◆ DIRECT_REF
|
staticconstexpr |
◆ _object
| T* _object |
◆ _impl
| const void* _impl |
◆
| union { ... } |