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

#ifndef __APEX_BUFFER_H__
#define __APEX_BUFFER_H__

#include "APEX_API.h"
#include "APEX_COW.h"
#include "APEX_Types.h"

#include <UT/UT_Array.h>
#include <UT/UT_Assert.h>
#include <UT/UT_Debug.h>
#include <UT/UT_Format.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_Optional.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_WorkBuffer.h>
#include <SYS/SYS_Types.h>

#include <utility>

/*

We currently support data on the buffer that requires a node compilation
to initialize (such as SOP_VerbParms etc.), this could very likely be
refactored to be placed in a node's callback::RunData argument, but still yet
to investigate fully.

A possible thought here is to have a special tag for data types such as this
and separate out their storage so we keep the data that cannot be mem copied
away from those that can.

*/

namespace apex
{

class APEX_Argument;

/*
Any type information (size_t) is taken directly from the APEX_TypeDefinition subclass.
*/

/// Expandable storage of arbitrary runtime types for APEX program state. Indexed by @ref APEX_Buffer.
class APEX_API APEX_TypedBuffer
{
public:
    APEX_TypedBuffer(const APEX_TypeDefinitionBase *typedfn)
    {
        myTypeDefinition = typedfn;
    }

    ~APEX_TypedBuffer()
    {
        clear();
    }
    void clear();
    void allocate(exint size);

    void *storage() { return myData; }
    void *data(exint index = 0);
    const APEX_TypeDefinitionBase *typeDefinition() { return myTypeDefinition; }

private:
    // There's some redundancy here if the parent APEX_Buffer
    // stored these in a map... we could just store
    // a flat array of APEX_TypedBuffer's on the APEX_Buffer
    // and do any lookups using this member.
    const APEX_TypeDefinitionBase *myTypeDefinition = nullptr;

    // Our actual data storage - std::pmr::monotonic_allocator is maybe worth looking into?
    //  as these buffers will only grow during graph compilation and will not ever resize
    //  until they are wiped clean by a graph definition change.
    void *myData = nullptr;
};

using APEX_DataID = int64;
#define APEX_INVALID_DATAID -1
/*
The buffer should not deal with typeIds?
These are not guaranteed and so can only be resolved by a given
APEX_Registry, or collection thereof. So any APIs dealing with typeIds
need to resolve the APEX_TypeDefinition subclass against a registry before
querying the buffer.
*/

/// Holds all of the memory for execution state of a compiled APEX graph.
class APEX_API APEX_Buffer : UT_NonCopyable
{
public:
    APEX_Buffer()
    {}

    /// Get a new unique data ID.
    static APEX_DataID nextDataId();

    void clear()
    {
        myTypedBuffers.clear();
        myIsLocked = false;
    }

    /// Get the type-specific storage for a given type, or @c nullptr if not found.
    APEX_TypedBuffer *findTypedBuffer(const APEX_TypeDefinitionBase *type_defn)
    {
        for (auto &buf : myTypedBuffers)
        {
            if (buf.typeDefinition() == type_defn)
                return &buf;
        }
        return nullptr;
    }

    APEX_TypedBuffer *getTypedBuffer(exint index)
    {
        if (index < 0 || index >= myTypedBuffers.size())
            return nullptr;
        return &myTypedBuffers[index];
    }

    /// Get the index at which a given type is stored in this buffer, or -1 if not present.
    exint typeIndex(const APEX_TypeDefinitionBase *type_defn)
    {
        exint result = 0;
        for (auto &buf : myTypedBuffers)
        {
            if (buf.typeDefinition() == type_defn)
            {
                break;
            }
            result++;
        }
        if (result >= myTypedBuffers.size())
            return -1;
        return result;
    }

    /// Allocate a type-specific storage buffer of the given type of the given size. Returns the index
    /// of the new storage.
    exint allocate(const APEX_TypeDefinitionBase *type_defn, exint size)
    {
        exint type_index = typeIndex(type_defn);
        if (type_index > -1)
        {
            UTdebugPrint("Attempt to allocate multiple buffers of the same type!");
            return type_index;
        }
        exint t_buf_idx = myTypedBuffers.emplace_back(type_defn);
        myTypedBuffers[t_buf_idx].allocate(size);
        return t_buf_idx;
    }

    /// Extend the type-specific storage buffer of the given type by one element and return an ApexArgument tracking it.
    APEX_Argument append(const APEX_TypeDefinitionBase *type_defn);

    /// Set the value of the given argument in this buffer to the value. The type of the argument must support copying.
    void set(APEX_Argument &arg, void *value);
    /// Prevent further modifications to the layout of this buffer.
    void lock() { myIsLocked = true; }
    // This relies on the source of the APEX_TypeDefinition to be static
    // UT_Map<APEX_TypeDefinitionBase *, APEX_TypedBuffer> myTypedBuffers;
private:
    UT_Array<APEX_TypedBuffer> myTypedBuffers;
    bool myIsLocked = false;
};

/// Represents a location for a single object inside of an APEX_Buffer. 
class APEX_API APEX_Argument
{
public:
    APEX_Buffer *buffer = nullptr;
    const APEX_TypeDefinitionBase *type_defn = nullptr;
    exint offset = -1;

    bool isValid() const
    {
        return buffer && type_defn && (offset > -1);
    }

    void *getVoidPtr()
    {
        if (!buffer)
            return nullptr;
        APEX_TypedBuffer *typed_buffer = buffer->findTypedBuffer(type_defn);
        if (!typed_buffer || offset < 0)
            return nullptr;
        return typed_buffer->data(offset);
    }

    const void *getVoidPtr() const
    {
        if (!buffer)
            return nullptr;
        APEX_TypedBuffer *typed_buffer = buffer->findTypedBuffer(type_defn);
        if (!typed_buffer || offset < 0)
            return nullptr;
        return typed_buffer->data(offset);
    }
};

/// Represents a location for a single object inside of an APEX_Buffer while keeping track of some notion
/// of the data's freshness. Used by parameter dictionaries for cheap output caching.
class APEX_API APEX_TrackedArgument : public APEX_Argument
{
public:
    APEX_DataID myDataId = APEX_Buffer::nextDataId();

    APEX_DataID dataId() const { return myDataId; }
    void bumpDataId() { myDataId = APEX_Buffer::nextDataId(); }
    void copyDataId(const APEX_TrackedArgument &other) { myDataId = other.dataId(); }
};

/// Check if a callback argument holds an instance of the given type.
template <typename T>
static bool
isType(const APEX_Argument &arg)
{
    const APEX_TypeDefinitionBase *test_type = findTypeDef<T>();
    return arg.type_defn == test_type;
}

/// Return the address of the data contained in the passed argument if it is of the provided type,
/// otherwise return nullptr. APEX equivalent of @c dynamic_cast.
template <typename T>
static T *
castArg(APEX_Argument *arg)
{
    if (!isType<T>(*arg))
        return nullptr;
    void *arg_ptr = arg->getVoidPtr();
    return reinterpret_cast<T *>(arg_ptr);
}

/// Return the address of the data contained in the passed argument if it is of the provided type,
/// otherwise return nullptr. APEX equivalent of @c dynamic_cast.
template <typename T>
static const T *
castArg(const APEX_Argument *arg)
{
    if (!isType<T>(*arg))
        return nullptr;
    const void *arg_ptr = arg->getVoidPtr();
    return reinterpret_cast<const T *>(arg_ptr);
}

/// Returns an optional of the requested argument's value
template <typename T>
static UT_Optional<T>
castArgValue(APEX_Argument &arg)
{
    UT_Optional<T> result;

    T *value = castArg<T>(&arg);
    if (value)
        result = *value;

    return result;
}

/// Specialization for bools to allow conversion from integers
template <>
inline UT_Optional<Bool>
castArgValue(APEX_Argument &arg)
{
    UT_Optional<Bool> result;

    if (Bool *value = castArg<Bool>(&arg))
        result = *value;
    else if (Int *value = castArg<Int>(&arg))
        result = (*value != 0);

    return result;
}

/// Specialization for ints to allow conversion from bools
template <>
inline UT_Optional<Int>
castArgValue(APEX_Argument &arg)
{
    UT_Optional<Int> result;

    if (Int *value = castArg<Int>(&arg))
        result = *value;
    else if (Bool *value = castArg<Bool>(&arg))
        result = (*value? 1 : 0);

    return result;
}

/// Safely copy data from one argument to another. Returns true if the copy actually occurred.
static bool
copyArgData(APEX_Argument *dst, const APEX_Argument *src, bool allow_implicit_conversion=false)
{
    UT_ASSERT(dst->isValid());
    UT_ASSERT(src->isValid());

    void *dst_ptr = dst->getVoidPtr();
    const void *src_ptr = src->getVoidPtr();
    if (dst->type_defn != src->type_defn)
    {
        if (!allow_implicit_conversion)
            return false;

        if (isType<Bool>(*dst) && isType<Int>(*src))
        {
            // Int to bool conversion
            Int val_int = *castArg<Int>(src);
            Bool val_bool = val_int != 0;
            Bool &dst_val = *castArg<Bool>(dst);
            dst_val = val_bool;
            return true;
        }
        else if (isType<Int>(*dst) && isType<Bool>(*src))
        {
            // Bool to int conversion
            Bool val_bool = *castArg<Bool>(src);
            Int val_int = val_bool? 1 : 0;
            Int &dst_val = *castArg<Int>(dst);
            dst_val = val_int;
            return true;
        }

        return false;
    }
    if (!dst->type_defn->isCopyable())
        return false;
    if (dst_ptr == src_ptr)
        return false;
    dst->type_defn->setData(dst_ptr, src_ptr);
    return true;
}

/// Returns the value of the argument as a string.
APEX_API UT_StringHolder
APEXformatArg(const APEX_Argument *arg);

/// Takes a formatting string, and an array of arguments, and writes the
/// formatted string to the result.
APEX_API void
APEXformatString(
        String &result,
        const String &format_str,
        const UT_Array<const APEX_Argument *> &args);

} // end namespace apex

#endif // __APEX_BUFFER_H__