UT_COWValue.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:        UT_COWValue.h
 *
 * COMMENTS:
 *
 *
 */

#ifndef __UT_COWVALUE_H__
#define __UT_COWVALUE_H__

#include "UT_API.h"

#include "UT_ArraySet.h"
#include "UT_Assert.h"
#include "UT_Tracing.h"

#include <SYS/SYS_AtomicInt.h>
#include <SYS/SYS_TypeDecorate.h>

#include <stddef.h>

/// Implements a generic copy on write mechanism for types. There is
/// always a valid object stored within a COWValue -- moving from it resets it
/// to a default-constructed T, not a nullptr.
template <typename T>
class UT_COWValue
{
public:
    UT_COWValue() : myConstRep(Rep::getStaticEmpty()) {}
    UT_COWValue(T &&data) : myRep(new Rep(std::move(data))) {}
    template <typename... Args>
    UT_COWValue(std::in_place_t, Args &&...args)
        : myRep(new Rep(std::in_place, std::forward<Args>(args)...))
    {
    }

    UT_COWValue &operator=(const UT_COWValue &other)
    {
        utZoneScopedN("cow handle copy assign");
        // UTdebugPrint("copy assign cow handle");
        if (this != &other)
        {
            UT_COWValue(other).swap(*this);
        }
        return *this;
    }

    UT_COWValue(const UT_COWValue &other)
    {
        other.safeIncRef();

        myConstRep = other.myConstRep;
    }

    UT_COWValue &operator=(UT_COWValue &&other) noexcept
    {
        // UTdebugPrint("move cow handle");
        if (this != &other)
        {
            safeDecRef();
            myConstRep = std::exchange(
                    other.myConstRep, Rep::getStaticEmpty());
        }
        return *this;
    }

    UT_COWValue(UT_COWValue &&other) noexcept
        : myConstRep(
                std::exchange(other.myConstRep, Rep::getStaticEmpty()))
    {
    }

    ~UT_COWValue() { safeDecRef(); }

    /// Returns true if the data referenced by this UT_COWValue is not
    /// shared (i.e. whether accessing it will not create a copy).
    bool isUnique() const { return myConstRep->isUnique(); }
    /// Returns true if this UT_COWValue is referencing the global
    /// default-constructed version of T.
    bool isImmortal() const { return myConstRep->isImmortal(); }
    /// Return the number of UT_COWValues sharing data with us, including us.
    /// May return a negative number to indicate an unknown quantity.
    exint refCount() const { return myConstRep->refCount(); }

    /// Ensure the data referenced by this UT_COWValue is only referenced by
    /// it.
    void makeUnique()
    {
        // Check if we have multiple objects referencing this handle
        if (!isUnique())
        {
            utZoneScopedN("cow handle deep copy");
            // UTdebugPrint("cow handle deep copy");
            *this = UT_COWValue(std::in_place, *myRep->data());
        }
    }

    T &operator*()
    {
        UT_ASSERT(myRep);
        makeUnique();
        return *myRep->data();
    }
    const T &operator*() const
    {
        UT_ASSERT(myRep);
        return *myConstRep->data();
    }

    T *operator->()
    {
        UT_ASSERT(myRep);
        makeUnique();
        return myRep->data();
    }
    const T *operator->() const
    {
        UT_ASSERT(myRep);
        return myConstRep->data();
    }

    /// Return a const reference to the stored data. Never copies.
    /// NB: This allows a non-unique, non-const, UT_COWValue<T>, to read the
    ///     data without first forcing the value to be hardened.
    const T &peek() const { return *myConstRep->data(); }

    void swap(UT_COWValue<T>& other)
    {
        std::swap(myRep, other.myRep);
    }

    /// Return the global static immortal default-constructed UT_COWValue for
    /// the type.
    static const UT_COWValue<T> &getStaticEmpty()
    {
        static const UT_COWValue<T> theInstance{};
        return theInstance;
    }

protected:
    /// The actual control block for a value referenced by (potentially
    /// multiple) UT_COWValues
    ///
    /// These can be in one of three states:
    ///     - unique: only one UT_COWValue has mutable access to the data
    ///     stored
    ///     - nonunique: multiple UT_COWValues have const access to the data
    ///     stored
    ///     - immortal: an arbitrary number of UT_COWValues have const access
    ///     to the read-only data stored
    ///
    /// Immortal Reps are used to provide a cheap global
    /// default-constructed version of the contained type.
    class Rep
    {
        friend class UT_COWValue<T>;

        struct ImmortalTag
        {
        };

        /// Stored as the myRefCount for an immortal Rep.
        inline const static exint IMMORTAL_REF_COUNT = -1;

    protected:
        typedef T element_type;

        Rep() : myData{}, myRefCount(1) {}
        Rep(const T &data) : myData(T(data)), myRefCount(1) {}
        Rep(T &&data) : myData(std::move(data)), myRefCount(1) {}
        template <typename... Args>
        Rep(std::in_place_t, Args &&...args)
            : myData(std::forward<Args>(args)...), myRefCount(1)
        {
        }
        /// Construct the global immortal Rep for this type -- should
        /// only be called by getStaticEmpty().
        explicit Rep(ImmortalTag) : myData{}, myRefCount{IMMORTAL_REF_COUNT} {}

        // TODO: should there be emplace-style construct-in-place constructors?

        Rep(const Rep &other) = delete;
        Rep &operator=(const Rep &other) = delete;

        ~Rep() { UT_ASSERT(isImmortal() || myRefCount.relaxedLoad() == 0); }

        bool isUnique() const
        {
            return myRefCount.load(SYS_MEMORY_ORDER_ACQUIRE) == 1;
        }
        bool isImmortal() const
        {
            return myRefCount.relaxedLoad() == IMMORTAL_REF_COUNT;
        }
        exint refCount() const
        {
            return myRefCount.load(SYS_MEMORY_ORDER_ACQUIRE);
        }

        T *data() { return &myData; }
        const T *data() const { return &myData; }

        /// Return the global static immortal default-constructed Rep for the
        /// type.
        static const Rep *getStaticEmpty()
        {
            static const Rep theInstance{ImmortalTag{}};
            return &theInstance;
        }

    private:
        void incRef()
        {
            UT_ASSERT(!isImmortal());
            myRefCount.add(1, SYS_MEMORY_ORDER_RELAXED);
        }

        void decRef()
        {
            UT_ASSERT(!isImmortal());
            if (myRefCount.add(-1, SYS_MEMORY_ORDER_ACQ_REL)
                == 0)
                delete this;
        }

        SYS_AtomicInt32 myRefCount;
        T myData;
    };

    void safeIncRef() const
    {
        if (!myConstRep->isImmortal())
            myRep->incRef();
    }

    void safeDecRef()
    {
        if (!myConstRep->isImmortal())
            myRep->decRef();
    }

    // This union is used to make it clear where
    // we expect to have a possibly-const handleref.
    union
    {
        const Rep *myConstRep;
        Rep *myRep;
    };
};

namespace UT
{
template <typename T>
struct DefaultClearer;

template <typename S>
struct DefaultClearer<UT_COWValue<S>>
{
    static void clear(UT_COWValue<S>& v) { v = UT_COWValue<S>(); }
    static bool isClear(const UT_COWValue<S>& v) { return v.isImmortal(); }
    static void clearConstruct(UT_COWValue<S> *p)
    {
        new ((void*)p) UT_COWValue<S>();
    }
    static const bool clearNeedsDestruction = false;
};
}

#endif // __UT_COWVALUE_H__