APEX_COW.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:        APEX_COW.h (APEX Library, C++)
 *
 * COMMENTS:
 */

#ifndef __APEX_COW_H__
#define __APEX_COW_H__

#include "APEX_API.h"

#include <GU/GU_Detail.h>
#include <GU/GU_DetailHandle.h>
#include <GA/GA_Types.h>

#include <UT/UT_Array.h>
#include <UT/UT_COWValue.h> // IWYU pragma: export
#include <UT/UT_Tracing.h>

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

#include <utility>
#include <stddef.h>

namespace apex
{
template <typename T>
class APEX_COWHandle : public UT_COWValue<T>
{
public:
    using Parent = UT_COWValue<T>;

    using Parent::Parent;

    static const APEX_COWHandle<T>& getAPEXStaticEmpty()
    {
        return static_cast<const APEX_COWHandle<T>&>(Parent::getStaticEmpty());
    }
};

template <typename T>
class ApexArray : public APEX_COWHandle<UT_Array<T>>
{
public:
    using value_type = T;

    void operator=(const UT_Array<T> &other)
    {
        clear();
        append(other.data(), other.size());
    }

    exint append(const T &v)
    {
        return (**this).append(v);
    }

    exint append(const T &v, bool check_dup)
    {
        return (**this).append(v, check_dup);
    }

    void append(const T *v, exint num_entries)
    {
        // Avoid possibly deduplicating from the global empty if
        // this operation would do nothing.
        if (num_entries == 0)
            return;
        return (**this).append(v, num_entries);
    }

    template <typename... S>
    exint emplace_back(S &&...s)
    {
        return (**this).emplace_back(s...);
    }

    void setCapacity(exint capacity)
    {
        if (capacity == 0)
            clear();
        else
            (**this).setCapacity(capacity);
    }
    void setSize(exint newsize) { (**this).setSize(newsize); }
    exint size() const { return (**this).size(); }
    exint capacity() const { return (**this).capacity(); }

    T *data() { return (**this).data(); }
    const T *data() const { return (**this).data(); }

    T &operator[](exint index) { return (**this)[index]; }
    const T &operator[](exint index) const { return (**this)[index]; }

    void clear()
    {
        // Directly assign to the global empty array to avoid a makeUnique call just to
        // throw away the resulting copy.
        APEX_COWHandle<UT_Array<T>>::operator=({});
    }
    bool isEmpty() const { return (**this).isEmpty(); }

    exint find(const T &val, exint start = 0) const { return (**this).find(val, start); }

    using iterator = typename UT_Array<T>::iterator;
    using const_iterator = typename UT_Array<T>::const_iterator;
    using reverse_iterator = typename UT_Array<T>::reverse_iterator;
    using const_reverse_iterator = typename UT_Array<T>::const_reverse_iterator;

    iterator begin() { return (**this).begin(); }
    iterator end() { return (**this).end(); }
    const_iterator begin() const { return (**this).begin(); }
    const_iterator end() const { return (**this).end(); }
    iterator rbegin() { return (**this).rbegin(); }
    iterator rend() { return (**this).rend(); }
    const_iterator rbegin() const { return (**this).rbegin(); }
    const_iterator rend() const { return (**this).rend(); }
};

// Overload for custom formatting of ApexArray<T> with UTformat. It's will be found via ADL.
template <typename T>
inline size_t
format(char *buffer, size_t bufsize, const ApexArray<T> &v)
{
    return format(buffer, bufsize, v.peek());
}

/// APEX wrapper for geometry via GU_DetailHandle. Keeps a much stronger COW
/// guarantee than a raw GU_DetailHandle by using preserve requests to track
/// active APEX-side references to geo. Additionally, it lazily clears geo
/// when reset to its default state via operator= to keep operations like
/// replaceWith and stashAll fast.
class ApexGeometry
{
public:
    /// Construct an empty ApexGeometry.
    ApexGeometry()
        : // Simply setting stashed to true lets the rest of the class act
          // as if the geo is empty - this also means we don't have to allocate
          // a detail upfront as one will be created on-demand.
        myIsStashed(true)
    {
    }
    /// Construct an ApexGeometry referencing a GU_DetailHandle
    ApexGeometry(const GU_DetailHandle &gdh) : myHandle(gdh)
    {
        // Since we're not stashed, ensure we've added a preserveRequest.
        myHandle.addPreserveRequest();
    }
    /// Construct an ApexGeometry referencing a GU_DetailHandle
    ApexGeometry(GU_DetailHandle &&gdh) : myHandle(std::move(gdh))
    {
        // Since we're not stashed, ensure we've added a preserveRequest.
        // NOTE: we still do this for move-construct on a raw GU_DetailHandle because
        // we don't know if the caller had a preserveRequest (and regardless, cannot tell
        // it to discard its request directly).
        myHandle.addPreserveRequest();
    }
    ApexGeometry(const ApexGeometry &other)
    {
        if (other.myIsStashed)
            // If constructing from an empty geometry, just make another empty
            // geometry.
            myIsStashed = true;
        else
        {
            // Otherwise, reference the incoming geometry and add a new preserveRequest
            // to add another APEX reference to it.
            myHandle = other.myHandle;
            myHandle.addPreserveRequest();
        }
    }

    ApexGeometry(ApexGeometry &&other) noexcept
    {
        if (other.myIsStashed)
            // If constructing from an empty geometry, just make another empty
            // geometry.
            myIsStashed = true;
        else
        {
            // Otherwise steal the handle from the incoming object, setting
            // it as stashed to ensure it doesn't try to remove a preserveRequest.
            myHandle = std::move(other.myHandle);
            other.myIsStashed = true;
        }
    }

    ApexGeometry &operator=(const ApexGeometry &other)
    {
        if (&other == this)
            return *this;
        // If we're assigning a stashed geo (i.e. empty), and
        // we last were modified (so want to keep stale data),
        // just remove the preserveRequest if one was present.
        if (other.myIsStashed && myLastModified)
        {
            if (!std::exchange(myIsStashed, true))
                myHandle.removePreserveRequest();
        }
        // Otherwise, if assigning a stashed geo in general, mark
        // us as stashed, remove any preserveRequest if we weren't
        // already stashed, and clear the last modified and handle.
        else if (other.myIsStashed)
        {
            if (!std::exchange(myIsStashed, true))
                myHandle.removePreserveRequest();
            myHandle = {};
            myLastModified = false;
        }
        // Otherwise, we're assining an actual geometry, so we should
        // reference it. Ensure we remove the preserveRequest if we had
        // one, mark us no longer stashed, then alias the handle and add
        // a new preserveRequest since we're not stashed.
        else
        {
            if (!std::exchange(myIsStashed, false))
                myHandle.removePreserveRequest();
            myHandle = other.myHandle;
            myHandle.addPreserveRequest();
            myLastModified = false;
        }
        return *this;
    }

    ApexGeometry &operator=(ApexGeometry &&other) noexcept
    {
        if (&other == this)
            return *this;
        // If we're assigning a stashed geo (i.e. empty), and
        // we last were modified (so want to keep stale data),
        // just remove the preserveRequest if one was present.
        if (other.myIsStashed && myLastModified)
        {
            if (!std::exchange(myIsStashed, true))
                myHandle.removePreserveRequest();
        }
        // Otherwise, if assigning a stashed geo in general, mark
        // us as stashed, remove any preserveRequest if we weren't
        // already stashed, and clear the last modified and handle.
        else if (other.myIsStashed)
        {
            if (!std::exchange(myIsStashed, true))
                myHandle.removePreserveRequest();
            myHandle = {};
            myLastModified = false;
        }
        // Otherwise, we're assigning an actual geometry, so we should
        // reference it. Ensure we remove the preserveRequest if
        // we had one, mark us as no longer stashed, steal the old handle
        // (which should already have a preserveRequest as the other geo
        // is not stashed), and set the provided geometry to be stashed
        // so it does not try to remove a preserveRequest when it goes
        // out of scope.
        else
        {
            if (!std::exchange(myIsStashed, false))
                myHandle.removePreserveRequest();
            myHandle = std::move(other.myHandle);
            other.myIsStashed = true;
            myLastModified = false;
        }
        return *this;
    }

    ~ApexGeometry()
    {
        if (!myIsStashed) // The handle only has a preserve request if we are not stashed.
            myHandle.removePreserveRequest();
    }

    /// Returns whether the geometry is unique - if so, asUnsafeHandle can be used safely.
    bool isUnique() const { return myIsStashed || myHandle.getPreserveRequest() <= 1; }

    /// Ensures the underlying GU_DetailHandle is not being aliased. If for_overwrite is passed,
    /// the caller does not care about the actual contents of the geometry - it can be cleared if
    /// that would be faster than performing a copy, and stale data should be kept if doing so would
    /// not cause aliasing.
    void makeUnique(bool for_overwrite = false)
    {
        // First, ensure we know this is no longer a referenced geo.
        myLastModified = true;
        // Also, set myIsStashed back to false immediately as we're going to create an actual
        // geometry object.
        bool was_stashed = std::exchange(myIsStashed, false);
        // If we were stashed and had an invalid detail (such as from default construction), we can
        // immediately just create a new empty one and be finished.
        if (was_stashed && myHandle.isNull())
        {
            myHandle.allocateAndSet(new GU_Detail());
            myHandle.addPreserveRequest();
            return;
        }
        // If we were originally stashed, we need to un-stash: re-reference whatever geo we had
        // originally so that there are the correct number of references to it for the unique check.
        if (was_stashed)
        {
            myHandle.addPreserveRequest();
            if (!isUnique())
            {
                // If we're not unique, our stashed geometry has a preserve request
                // somewhere else so we need to start from a new geometry
                utZoneScopedN("ApexGeometry::makeUnique::stash::allocateGeoemtry");
                myHandle.removePreserveRequest();
                myHandle.allocateAndSet(new GU_Detail());
                myHandle.addPreserveRequest();
            }
            else if (!for_overwrite)
            {
                // Otherwise, we clear the geometry if it's note being overwritten
                utZoneScopedN("ApexGeometry::makeUnique::stash::reset");
                myHandle.gdpNC()->clear();
            }
            
            return;
        }

        // Otherwise, ensure we're unique
        if (isUnique())
            return;

        // If we're not unique, we need to make unique.
        if (for_overwrite)
        {
            // If for_overwrite was requested, we can do this cheeply by
            // creating a new geometry.
            utZoneScopedN("ApexGeometry::makeUnique::allocateGeoemtry");
            myHandle.removePreserveRequest();
            myHandle.allocateAndSet(new GU_Detail());
            myHandle.addPreserveRequest();
        }
        else
        {
            // Otherwise, if none of that shortcuts the slow copy, perform
            // a duplicateGeometry - remove the old preserveRequest and
            // add a new one to the fresh detail.
            utZoneScopedN("ApexGeometry::makeUnique");
            std::exchange(myHandle, myHandle.duplicateGeometry(GA_DATA_ID_CLONE))
                    .removePreserveRequest();
            myHandle.addPreserveRequest();
        }
        
    }
    /// Return a reference to the underlying GU_Detail, ensuring uniqueness.
    GU_Detail &operator*()
    {
        makeUnique();
        return *myHandle.gdpNC();
    }
    /// Return a const reference to the underlying GU_Detail, without ensuring uniqueness.
    inline const GU_Detail &operator*() const
    {
        if (myIsStashed)
            return *getStaticEmpty();
        return *myHandle.gdp();
    }
    /// Access the underlying GU_Detail, ensuring uniqueness
    GU_Detail *operator->()
    {
        makeUnique();
        return myHandle.gdpNC();
    }

    /// Access the underlying const GU_Detail, without ensuring uniqueness
    inline const GU_Detail *operator->() const
    {
        if (myIsStashed)
            return getStaticEmpty();
        return myHandle.gdp();
    }

    /// Access the underlying GU_Detail, ensuring uniqueness.
    GU_Detail *gdp() { return operator->(); }

    /// Access the underlying GU_Detail. If the geometry is currently stashed, this can return the
    /// old stale geometry so long as it is unique. Otherwise, in any case where the normal access
    /// logic would perform a copy, this will return an empty geometry object instead - only
    /// returning the actual current data for an unstashed geometry if it is already unique.
    ///
    /// This is useful for operations that will completely overwrite the contained geometry.
    GU_Detail *gdpForOverwrite()
    {
        makeUnique(true);
        return myHandle.gdpNC();
    }

    /// Access the underlying const GU_Detail, without ensuring uniqueness
    inline const GU_Detail *gdp() const { return operator->(); }

    /// Access the underlying const GU_Detail, without ensuring uniqueness
    inline const GU_Detail &peek() const { return **this; }

    /// Access the underlying const GU_Detail *, without ensuring uniqueness
    inline const GU_Detail *peekPtr() const { return operator->(); }

    /// Access the underlying detail handle, while only ensuring it is valid (i.e. without ensuring
    /// there are no other APEX references to it). Calling code should respect the rule that
    /// >1 preserveRequest means that other ApexGeometry objects are expecting the geo not to
    /// change.
    GU_DetailHandle &asUnsafeHandle(bool for_overwrite = false)
    {
        if (myIsStashed)
        {
            myIsStashed = false;
            if (myHandle.isNull())
                myHandle.allocateAndSet(new GU_Detail());
            else if (!for_overwrite)
                myHandle.gdpNC()->clear();
            myHandle.addPreserveRequest();
        }
        return myHandle;
    }

    /// Access the underlying GU_DetailHandle while first ensuring it is unique.
    GU_DetailHandle &asSafeHandle()
    {
        makeUnique();
        return myHandle;
    }

    /// Create a GU_ConstDetailHandle aliasing the current handle; if the calling code will cast
    /// away the const, force_copy can be set to call duplicateGeometry first (with the default
    /// clone data ID strategy).
    GU_ConstDetailHandle asConstHandle(
            bool force_copy = false,
            GA_DataIdStrategy explicit_strategy = GA_DATA_ID_CLONE) const
    {
        if (myIsStashed)
            return *getStaticEmptyHandle();
        if (force_copy)
        {
            utZoneScoped;
            return myHandle.duplicateGeometry(explicit_strategy);
        }
        else
            return myHandle;
    }

    APEX_API static const ApexGeometry &getStaticEmptyGeometry();

private:
    // Provide a statically allocated empty geometry for gdp() on a const, stashed
    // geometry object.
    static const GU_Detail *getStaticEmpty()
    {
        static const GU_Detail theEmpty{};
        return &theEmpty;
    }

    // Ditto, but for a detail handle.
    static const GU_DetailHandle *getStaticEmptyHandle()
    {
        struct HandleInit
        {
            HandleInit()
            {
                // Initialize here to use the C++ guaranteed
                // locking on static initialization (instead of possibly
                // repeatedly creating detail handles from separate threads)
                handle.allocateAndSet(new GU_Detail());
            }

            GU_DetailHandle handle;
        };

        static const HandleInit theEmpty;
        return &theEmpty.handle;
    }

    // The current geometry. We keep a preserveRequest alive on this so long as
    // myIsStashed is not set. Additionally, it is only allowed to be invalid if
    // myIsStashed is set - otherwise it must point to _some_ geometry.
    GU_DetailHandle myHandle;

    bool myLastModified = false; // If makeUnique was called and we have not been referenced since,
                                 // this is set. Keeps track of buffers we're interested in stashing.

    bool myIsStashed = false;    // If set, the geo is considered 'stashed': if the underlying handle
                                 // is unique, we can return it instead of an actually empty geometry
                                 // when requested.
};

// Overload for custom formatting of ApexGeometry with UTformat. It's will be found via ADL.
APEX_API size_t format(char *buffer, size_t bufsize, const ApexGeometry &v);

// Overload for custom formatting of ApexArray<ApexGeometry> with UTformat for ADL searches.
template <>
APEX_API size_t
format<ApexGeometry>(char *buffer, size_t bufsize, const ApexArray<ApexGeometry> &v);

} // end namespace apex

// The move constructor is only non-trivial because it needs to ensure the destructor of the
// moved-out-of object doesn't try to clean anything up - if it's guaranteed to never be called
// a memmove can be used instead.
SYS_DECLARE_IS_TR(apex::ApexGeometry);

#endif // header guard