UI_XPtr.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UI_XPtr.h (UI Library, C++)
 *
 * COMMENTS:
 */

#ifndef __UI_XPTR_H_INCLUDED__
#define __UI_XPTR_H_INCLUDED__

#include <UT/UT_Assert.h>
#include <SYS/SYS_Compiler.h>
#include <SYS/SYS_Deprecated.h>
#include <SYS/SYS_Inline.h>
#include <SYS/SYS_TypeTraits.h>
#include <stddef.h>

class UI_Look;

/// Smart pointer class for holding UI_Look instances.
/// Similar to a UT_UniquePtr, it additionally tracks whether its pointer is an
/// owner or not. 
template <typename T>
class UI_XPtr
{
public:
    using PointerType = T*;
    using ElementType = T;
    using ThisType = UI_XPtr<T>;

    SYS_FORCE_INLINE
    UI_XPtr() noexcept = default;

    /// Construct via raw pointer with ownership flag
    SYS_FORCE_INLINE
    UI_XPtr(T *ptr, bool owner) noexcept;

    /// Construct with nullptr
    UI_XPtr(std::nullptr_t) noexcept {};

    SYS_FORCE_INLINE
    ~UI_XPtr();

    template <typename U>
    SYS_FORCE_INLINE
    UI_XPtr(UI_XPtr<U> &&other) noexcept;

    template <typename U>
    SYS_FORCE_INLINE
    UI_XPtr&
    operator=(UI_XPtr<U> &&other) noexcept;

    UI_XPtr(const ThisType &other) = delete;
    UI_XPtr& operator=(const ThisType &other) = delete;

    /// Assign nullptr 
    UI_XPtr &operator=(std::nullptr_t) noexcept
    {
        reset();
        return *this;
    }

    /// Explicit bool operator to avoid releasing the pointer with the cast
    /// operator. To do this, we must have both const and non-const versions.
    /// @{
    SYS_FORCE_INLINE
    explicit operator bool() const noexcept { return myPtr != nullptr; }
    SYS_FORCE_INLINE
    explicit operator bool() noexcept { return myPtr != nullptr; }
    /// @}

    SYS_FORCE_INLINE
    bool operator==(const ThisType &other) const noexcept
        { return myPtr == other.myPtr; }

    SYS_FORCE_INLINE
    bool operator!=(const ThisType &other) const noexcept
        { return !(*this == other); }

    SYS_FORCE_INLINE
    T &operator*() const noexcept { return *myPtr; }

    SYS_FORCE_INLINE
    T *operator->() const noexcept { return myPtr; }

    SYS_FORCE_INLINE
    T *get() const noexcept { return myPtr; }

    /// Release ownership and return current value
    /// @note Unlike UT_UniquePtr, release() does not reset myPtr
    SYS_FORCE_INLINE
    T *release() noexcept { myIsOwner = false; return myPtr; }

    /// Reset pointer to nullptr or to another raw pointer value
    /// @{
    SYS_FORCE_INLINE
    void reset() noexcept;
    SYS_FORCE_INLINE
    void reset(T *ptr, bool owner) noexcept;
    /// @}

    /// Return an unowned reference to the underlying pointer
    SYS_NO_DISCARD_RESULT
    ThisType ref() const noexcept
    {
        return ThisType(myPtr, false);
    }

    /// Determine if this is an owning pointer
    SYS_FORCE_INLINE
    bool isOwner() const noexcept { return myIsOwner; }

    /// Swap with another instance
    /// @{
    SYS_FORCE_INLINE
    void swap(ThisType &b) noexcept
    {
        UI_Look* ptr = myPtr;
        myPtr = b.myPtr;
        b.myPtr = ptr;

        bool owner = myIsOwner;
        myIsOwner = b.myIsOwner;
        b.myIsOwner = owner;
    }
    SYS_FORCE_INLINE
    friend void swap(ThisType &a, ThisType &b) noexcept
    {
        a.swap(b);
    }
    /// @}

private:
    T       *myPtr = nullptr;
    bool     myIsOwner = false;
};

/// Convenience method to create an UI_LookXPtr compatible subclass instance
template <typename T, class... Args>
static inline UI_XPtr<T>
UImakeLook(Args&&... args)
{
    return UI_XPtr<T>(new T(std::forward<Args>(args)...), true);
}

/////////////////////////////////////////////////////////////////////////////
// 
// Inline Implementations
//

template <typename T>
SYS_FORCE_INLINE
UI_XPtr<T>::UI_XPtr(T *ptr, bool owner) noexcept
    : myPtr(ptr)
    , myIsOwner(owner)
{
    if constexpr (SYS_IsSame_v<T, UI_Look>)
    {
        // There should never be an owning ptr for a static look
        UT_ASSERT(!(owner && ptr->isStatic()));
    }
}

template <typename T>
SYS_FORCE_INLINE
UI_XPtr<T>::~UI_XPtr()
{
    if (myIsOwner)
        delete myPtr;
}

template <typename T>
template <typename U>
SYS_FORCE_INLINE
UI_XPtr<T>::UI_XPtr(UI_XPtr<U> &&other) noexcept
{
    // Steal ownership but do not reset 'other'
    myIsOwner = other.isOwner();
    myPtr = other.release();
}

template <typename T>
template <typename U>
SYS_FORCE_INLINE
UI_XPtr<T>&
UI_XPtr<T>::operator=(UI_XPtr<U> &&other) noexcept
{
    // If 'other' has the same underlying raw pointer as myPtr, we do NOT want
    // to free prematurely if we had ownership. This is bug in the calling
    // code. The exception we make here is if both are also non-owners because
    // then we're likely just assigning shared looks.
    //
    // If myIsOwner is true and other.isOwner() false, then this case will
    // cause us to lose ownership. In this bad situation, we will leak.
    // Since we don't know if the caller has given ownership to someone else,
    // we leak instead of potentially crashing with a double free.
    UT_ASSERT((!myIsOwner && !other.isOwner()) || myPtr != other.get());

    // Delete old pointer, ensuring that we do not delete ourselves
    if (myIsOwner && myPtr != other.get())
        delete myPtr;

    // Steal ownership but do not reset 'other'
    myIsOwner = other.isOwner();
    myPtr = other.release();

    return *this;
}

template <typename T>
SYS_FORCE_INLINE
void
UI_XPtr<T>::reset() noexcept
{
    if (myIsOwner)
        delete myPtr;
    myPtr = nullptr;
    myIsOwner = false;
}

template <typename T>
SYS_FORCE_INLINE
void
UI_XPtr<T>::reset(T *ptr, bool owner) noexcept
{
    if (myIsOwner)
        delete myPtr;
    myPtr = ptr;
    myIsOwner = owner;
}

#endif // __UI_XPTR_H_INCLUDED__