Open Search
    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 { ... }