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

#ifndef __APEX_CALLBACK_H__
#define __APEX_CALLBACK_H__

#include "APEX_API.h"
#include "APEX_ParmDict.h"
#include "APEX_Include.h"
#include "APEX_Types.h"

#include <UT/UT_Array.h>
#include <UT/UT_Options.h>
#include <UT/UT_OpUtils.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_Span.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringView.h>
#include <UT/UT_Tracing.h>
#include <UT/UT_Tuple.h>
#include <UT/UT_WorkBuffer.h>

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

#include <algorithm>
#include <iterator>
#include <string>
#include <type_traits>
#include <utility>

#include <cstddef>
//#include <stddef.h>

namespace apex
{

class APEX_Program;
class APEX_Argument;
class APEX_Graph;

struct APEX_Parm
{
    APEX_Parm() = default;

    APEX_Parm(const UT_StringHolder &name, const APEX_TypeDefinitionBase *typedefn)
        : myName(name), myTypeDefn(typedefn)
    {
    }

    UT_StringHolder myName;
    const APEX_TypeDefinitionBase *myTypeDefn;
    UT_StringHolder myAlias;

    // Used for py bindings
    using tuple_t = UT_Tuple<std::string, std::string>;
    tuple_t asTuple() const
    {
        return {myName.toStdString(), myTypeDefn ? myTypeDefn->repr().toStdString() : ""};
    }

    bool operator==(const APEX_Parm &other) const
    {
        return myName == other.myName && myTypeDefn == other.myTypeDefn;
    }

    bool operator!=(const APEX_Parm &other) const
    {
        return myName != other.myName || myTypeDefn != other.myTypeDefn;
    }

    const UT_StringHolder &name() const { return myName; }
    const APEX_TypeDefinitionBase *typeDefinition() const { return myTypeDefn; }
    const UT_StringRef &typeName() const
    {
        if (!myTypeDefn)
            return theUndefTypeName.asRef();
        return myTypeDefn->repr();
    }

    bool isValid() const { return !myName.isEmpty() && myName != "__invalid__"; }
    bool isSpare() const { return myName.startsWith(theSparePortPrefix); }
    bool isInplace() const { return myName.startsWith(theInplacePortPrefix); }
    bool isConditionalInplace() const { return myName.startsWith(theConditionalInplacePortPrefix); }
};

static const APEX_Parm theInvalidParm = {"__invalid__", nullptr};

using APEX_ParmPtr = UT_SharedPtr<APEX_Parm>;
using APEX_ParmList = UT_Array<APEX_Parm>;

struct ParmNameComp
{
    ParmNameComp(const UT_StringView &s) : myStr(s) {}

    bool operator()(APEX_Parm const &p)
    {
        if (myStr == p.myName)
            return true;

        UT_StringView name_view(p.myName);
        name_view = name_view.trimLeft("*");
        name_view = name_view.trimLeft("+");
        name_view = name_view.trimLeft("-");
        if (UT_StringView(myStr) == name_view)
            return true;

        return !p.myAlias.isEmpty() && myStr == p.myAlias;
    }

    UT_StringHolder myStr;
};

struct ParmIterator
{
    using iterator_category = std::forward_iterator_tag;
    using difference_type = std::ptrdiff_t;
    using value_type = APEX_Parm;
    using pointer = APEX_Parm *;   // or also value_type*
    using reference = APEX_Parm &; // or also value_type&
};

class APEX_API APEX_Signature
{
public:
    const APEX_ParmList &inputs() const { return myInputs; }
    const APEX_ParmList &outputs() const { return myOutputs; }

    APEX_ParmList myInputs;
    APEX_ParmList myOutputs;

    bool operator==(const APEX_Signature &other) const
    {
        return myInputs == other.myInputs && myOutputs == other.myOutputs;
    }

    bool operator!=(const APEX_Signature &other) const
    {
        return !(myInputs == other.myInputs && myOutputs == other.myOutputs);
    }

    exint findInputIndex(const UT_StringView &name) const
    {
        auto it = std::find_if (myInputs.begin(), myInputs.end(), ParmNameComp(name));
        return it != myInputs.end() ? std::distance(myInputs.begin(), it) : -1;
    }

    exint findOutputIndex(const UT_StringView &name) const
    {
        auto it = std::find_if (myOutputs.begin(), myOutputs.end(), ParmNameComp(name));
        return it != myOutputs.end() ? std::distance(myOutputs.begin(), it) : -1;
    }

    const APEX_Parm &findInput(const UT_StringRef &name) const
    {
        auto it = std::find_if (myInputs.begin(), myInputs.end(), ParmNameComp(name));
        if (it == myInputs.end())
            return theInvalidParm;
        return *it;
    }

    const APEX_Parm &findOutput(const UT_StringRef &name) const
    {
        auto it = std::find_if (myOutputs.begin(), myOutputs.end(), ParmNameComp(name));
        if (it == myOutputs.end())
            return theInvalidParm;
        return *it;
    }

    exint findInput(const UT_StringRef &name, APEX_Parm **parm)
    {
        exint index = findInputIndex(name);
        if (index != -1)
            *parm = &myInputs[index];

        return index;
    }

    exint findOutput(const UT_StringRef &name, APEX_Parm **parm)
    {
        exint index = findOutputIndex(name);
        if (index != -1)
            *parm = &myOutputs[index];

        return index;
    }

    exint numInputs() const { return myInputs.size(); }

    exint numOutputs() const { return myOutputs.size(); }

    exint size() const { return numInputs() + numOutputs(); }

    APEX_Parm &addInput(int idx, const APEX_Parm &parm)
    {
        if (idx < 0)
            idx = myInputs.append(parm);
        else
        {
            if (myInputs.isEmpty())
            {
                idx = myInputs.append(parm);
            }
            else
                myInputs.insertAt(parm, idx);
        }
        return myInputs[idx];
    }

    APEX_Parm &addOutput(int idx, const APEX_Parm &parm)
    {
        if (idx < 0)
            idx = myOutputs.append(parm);
        else
        {
            if (myOutputs.isEmpty())
            {
                idx = myOutputs.append(parm);
            }
            else
                idx = myOutputs.insertAt(parm, idx);
        }
        return myOutputs[idx];
    }

    void addSparePort(const UT_StringRef &name="", exint index = -1)
    {
        if (name.isEmpty())
        {
            addInput(-1, {theSparePortName.asRef(), nullptr});
            addOutput(-1, {theSparePortName.asRef(), nullptr});
        }
        else
        {
            UT_StringHolder full_name;
            full_name.format("+{}", name);
            addInput(SYSmin(index, myInputs.size()), {full_name, nullptr});
            addOutput(SYSmin(index, myOutputs.size()), {full_name, nullptr});
        }
    }

    bool addInputAlias(const UT_StringRef &name, const UT_StringRef &alias)
    {
        exint index = findInputIndex(name);
        if (index < 0)
            return false;

        UT_StringView alias_view(alias);
        alias_view = alias_view.trimLeft("*");
        alias_view = alias_view.trimLeft("+");
        alias_view = alias_view.trimLeft("-");
        if (findInputIndex(alias_view) >= 0)
            return false;
        
        myInputs[index].myAlias = alias_view;
        return true;
    }

    bool addOutputAlias(const UT_StringRef &name, const UT_StringRef &alias)
    {
        exint index = findOutputIndex(name);
        if (index < 0)
            return false;

        UT_StringView alias_view(alias);
        alias_view = alias_view.trimLeft("*");
        alias_view = alias_view.trimLeft("+");
        alias_view = alias_view.trimLeft("-");
        if (findOutputIndex(alias_view) >= 0)
            return false;
        
        myOutputs[index].myAlias = alias_view;
        return true;
    }

    // FIXME: this is broken until the removal of type enums is complete
    bool isGeneric() const { return false; }

#if 0
    void serialize(UT_String &str)
    {
        // UT_OptionsHolder inputs_opt;
        // UT_OptionsHolder outputs_opt;
        // UT_Options sig_opt;
        // for (auto &[name, _t] : inputs)
        //     inputs_opt.setOptionI(name,static_cast<int>(_t));
        // for (auto &[name, _t] : outputs)
        //     outputs_opt.setOptionI(name,static_cast<int>(_t));
        // sig_opt.setOptionDict("inputs", inputs_opt);
        // sig_opt.setOptionDict("outputs", outputs_opt);
        // sig_opt.dump();
    }
#endif

    static const APEX_Signature theEmptySignature;
};

using APEX_SignaturePtr = UT_SharedPtr<APEX_Signature>;

class APEX_ParmHandleRef
{
public:
    APEX_ParmHandleRef(APEX_Parm *parm) : myParmPtr(parm) {};
    APEX_ParmHandleRef(APEX_SignaturePtr &sig, APEX_Parm *parm) : myParmPtr(parm), myOwner(sig)
    {
        myOwns = false;
    };
    ~APEX_ParmHandleRef()
    {
        if (myOwns)
            delete myParmPtr;
    }
    APEX_Parm *ptr() { return myParmPtr; }

    bool isOwner() { return myOwns; }

    bool isValid()
    {
        if (!myOwns && !myOwner)
            return false;
        else
            return myParmPtr;
    }

    void setPtr(APEX_Parm *ptr, bool owns)
    {
        myParmPtr = ptr;
        myOwns = owns;
    }
    void incref() { myRefCount++; }
    void decref()
    {
        myRefCount--;
        if (myRefCount == 0)
            delete this;
    }

private:
    bool myOwns = false;
    exint myRefCount = 0;
    UT_SharedPtr<APEX_Signature> myOwner;
    APEX_Parm *myParmPtr = nullptr;
};

class APEX_ParmHandle
{
public:
    APEX_ParmHandle(APEX_SignaturePtr &sig, APEX_Parm *parm)
    {
        myHandle = new APEX_ParmHandleRef(sig, parm);
        myHandle->incref();
    }
    APEX_ParmHandle(APEX_Parm &&parm)
    {
        myHandle = new APEX_ParmHandleRef(nullptr);
        auto *copy = new APEX_Parm(parm);

        myHandle->setPtr(copy, true);
        myHandle->incref();
    }
    APEX_ParmHandle(const APEX_ParmHandle &other): myHandle(other.myHandle)
    {
        myHandle->incref();
    }

    ~APEX_ParmHandle()
    {
        myHandle->decref();
    }

    bool isOwner() const { return myHandle->isOwner(); }

    bool isValid() const { return myHandle && myHandle->isValid(); }

    bool isSpare() const { return isValid() && get()->isSpare(); }
    bool isInplace() const { return isValid() && get()->isInplace(); }
    bool isConditionalInplace() const { return isValid() && get()->isConditionalInplace(); }

    UT_StringHolder &name() { return get()->myName; }
    const UT_StringRef &typeName() { return get()->typeName(); }
    const APEX_TypeDefinitionBase *typeDefinition() { return get()->typeDefinition(); }

    APEX_ParmHandle freeze() const
    {
        const APEX_Parm *parm = get();
        return APEX_ParmHandle({parm->myName, parm->myTypeDefn});
    }

    APEX_Parm duplicateParm() const
    {
        if (isValid())
            return *get();
        return {"invalid", nullptr};
    }

    APEX_Parm *get() { return myHandle->ptr(); }
    const APEX_Parm *get() const { return myHandle->ptr(); }

private:
    APEX_ParmHandleRef *myHandle;
};

enum class APEX_CallbackType
{
    NOOP, /// Do nothing; ignored after compilation.

    NORMAL, /// Normal callback which is unconditionally executed

    /// @{ flow control

    IF_BEGIN, /// Callback is used as an IF_BEGIN: expects the signature to be exactly a Bool called
    /// condition + scope/spare
    IF_END,   /// Callback marks the end of an if block: expects the signature to be exactly
    /// scope/spare.

    LOOP_BEGIN, /// Marks the start of an arbitrary loop, expects RunData to be an iterator
    LOOP_END    /// Marks the end of an arbitrary loop, expects RunData to be an iterator and shares
    /// that rundata with the corresponding LOOP_BEGIN.

    /// @}
};

using APEX_ArgPtrs = UT_Array<void *>;

class APEX_API APEX_FunctionBase
{
public:
    virtual ~APEX_FunctionBase() = default;

    virtual const UT_StringHolder &getName() const = 0;
    virtual void compile(
            const APEX_Graph *graph,
            APEX_NodeID node_id,
            APEX_Program *prog,
            UT_Array<APEX_Argument> &args) const
    {
    }
    virtual void execute(APEX_ArgPtrs &arg_ptrs) const {}

    /// What kind of function is this? Informs things like scopes & conditions
    virtual APEX_CallbackType callbackType() const { return APEX_CallbackType::NOOP; };

    virtual const APEX_Signature &signature() const = 0;

    virtual const APEX_TypeDefinitionBase *runDataTypeDef() const { return nullptr; }

    /// Earliest Houdini version that this callback is allowed in "X.Y.Z" format
    virtual const char *minProductVersion() const { return nullptr; }

    /// Determines whether the callback should be hidden from the UI
    virtual bool isHidden() const { return false; }

    /// Whether the callback requires its input geometry CE caches to be flushed.
    virtual bool requiresCEFlush() const { return true; }

    /// Whether the callback leaves CE caches in its output geometry.
    virtual bool usesCE() const { return false; }

    /// Called for any type with rundata with a reference to the rundata so it can be initialized.
    virtual void runDataCompileHook(
            APEX_Argument *rundata_instance,
            const APEX_Graph *in_graph,
            APEX_NodeID for_node,
            APEX_Program *bind_to) const
    {
    }

    /// Does this node open a scope?
    bool opensScope() const
    {
        auto t = callbackType();
        return t == APEX_CallbackType::IF_BEGIN || t == APEX_CallbackType::LOOP_BEGIN;
    }

    /// Does this node close a scope?
    bool closesScope() const
    {
        auto t = callbackType();
        return t == APEX_CallbackType::IF_END || t == APEX_CallbackType::LOOP_END;
    }

    /// Name of the fake wire which is used to denote scope relationships.
    virtual UT_StringHolder scopeConnection() const { return ""; }

    virtual bool hasSubnetTemplate() const { return false; }

    virtual const Dict &parmDefaults() const
    {
        return Dict::getAPEXStaticEmpty();
    }
};

template <typename C, typename... Ts, size_t... Index>
inline void
applyArgs(const C &callback, APEX_ArgPtrs &arg_ptrs, std::index_sequence<Index...>)
{
    callback(*reinterpret_cast<std::remove_pointer_t<std::remove_const_t<Ts>> *>(arg_ptrs[Index])...);
}

/// Invoke the callback with the provided arguments, which are casted to type Ts...
template <typename C, typename... Ts>
inline void
applyArgs(const C &callback, APEX_ArgPtrs &arg_ptrs)
{
    applyArgs<C, Ts...>(callback, arg_ptrs, std::index_sequence_for<Ts...>{});
}

template <typename T>
void
addToSignature(APEX_Signature &sig, const UT_StringHolder &name)
{
    const APEX_TypeDefinitionBase *t_defn = findTypeDef<std::remove_const_t<T>>();

    if constexpr (std::is_const_v<T>)
    {
        sig.myInputs.emplace_back(name, t_defn);
        if (name.startsWith(theSparePortPrefix))
            sig.myOutputs.emplace_back(name, t_defn);
    }
    else
    {
        sig.myOutputs.emplace_back(name, t_defn);
        if (name.startsWith(theInplacePortPrefix)
            || name.startsWith(theConditionalInplacePortPrefix))
            sig.myInputs.emplace_back(name, t_defn);
    }
}

template <typename... Ts, size_t... Index>
APEX_Signature
makeSignature(
        UT_Span<const char* const, sizeof...(Ts)> argnames,
        std::index_sequence<Index...>)
{
    APEX_Signature result;
    ((addToSignature<Ts>(result, argnames[Index])), ...);
    return result;
}

template <typename... Ts>
APEX_Signature
makeSignature(UT_Span<const char* const, sizeof...(Ts)> argnames)
{
    if constexpr (sizeof...(Ts) == 0)
        return APEX_Signature();

    return makeSignature<Ts...>(argnames, std::index_sequence_for<Ts...>{});
}

/// NB: This overload is here for backward compatibility. It was used to handle
/// callbacks declaring an empty argnames member (since const char*[0] is a
/// non-standard c++ type). The rare callbacks which do have an empty argnames
/// member should instead use a std::array<T, 0>:
///     `static constexpr std::array<const char*, 0> argnames = {};`
template <typename... Ts>
APEX_Signature
makeSignature(std::nullptr_t)
{
    return APEX_Signature();
}

template <typename C, typename... Ts>
class APEX_GenericFunction : public APEX_FunctionBase
{
public:
    APEX_GenericFunction()
    {
        if constexpr (!std::is_null_pointer_v<decltype(C::argnames)>)
        {
            static_assert(
                sizeof...(Ts) == std::size(C::argnames),
                "Callback argnames size does not match template argument size");
        }

        myName = C::funcname.asHolder();
        mySignature = makeSignature<Ts...>(C::argnames);

        UT_Options defaults;
        defaults.setFromPyDictionary(C::parm_defaults);
        myDefaults->mergeUtOptions(&defaults, false, true, true, &mySignature);
    }

    ~APEX_GenericFunction() override {}

    const UT_StringHolder &getName() const override { return myName; }

    static constexpr const char *parm_defaults = "";

    const APEX_Signature &signature() const override { return mySignature; };

    APEX_CallbackType callbackType() const override { return APEX_CallbackType::NORMAL; }

    const Dict &parmDefaults() const override { return myDefaults; }

    void addSparePort(const UT_StringRef &name = "", exint index = -1)
    {
        mySignature.addSparePort(name, index);
    }

    bool addInputAlias(const UT_StringRef &name, const UT_StringRef &alias)
    {
        return mySignature.addInputAlias(name, alias);
    }

    bool addOutputAlias(const UT_StringRef &name, const UT_StringRef &alias)
    {
        return mySignature.addOutputAlias(name, alias);
    }

    void execute(APEX_ArgPtrs &arg_ptrs) const override
    {
        utZoneScopedN(C::funcname);
        const auto &derived = static_cast<const C &>(*this);
        applyArgs<C, Ts...>(derived, arg_ptrs);
    }

protected:
    UT_StringHolder myName;

private:
    APEX_Signature mySignature;
    Dict myDefaults;
};

/// Splits the namespace version of @a fullname into a name and version pair.
/// For example, "string::Build::3.0" is split as {"string::Build", "3.0"}.
inline std::pair<UT_StringHolder, UT_StringHolder>
APEXsplitNameAndVersion(const char *fullname)
{
    UT_WorkBuffer scope, name_space, core_name, version;
    UT_OpUtils::getComponentsFromFullName(
        fullname, &scope, &name_space, &core_name, &version);

    UT_WorkBuffer name;
    if (!name_space.isEmpty())
    {
        name.append(name_space);
        name.append("::");
    }
    name.append(core_name);

    return {std::move(name), std::move(version)};
}

/// Filters the @p callbacks array by removing the callbacks whose signatures
/// do not contain all parms present in the @p filter signature. Returns the
/// number of removed callbacks.
///
/// The filter signature represents a sparse set of required parms.
/// Callbacks with additional parms are not removed as long as all parms in the
/// filter signature are present in the callback signature.
template <typename T>
exint
APEXfilterCallbacksBySignature(UT_Array<const T *> &callbacks, const APEX_Signature &filter)
{
    exint removed_count = 0;
    for (auto it = callbacks.rbegin(); it != callbacks.rend(); ++it)
    {
        const T *ptr = *it;
        const APEX_Signature &sig = ptr->signature();

        // Compare input signatures
        bool input_matches = true;
        for (const APEX_Parm &filter_i : filter.inputs())
        {
            const APEX_Parm &cb_sig_i = sig.findInput(filter_i.name());
            if (!cb_sig_i.isValid() || cb_sig_i.myTypeDefn != filter_i.myTypeDefn)
            {
                input_matches = false;
                break;
            }
        }
        if (!input_matches)
        {
            callbacks.removeItem(it);
            removed_count++;
            continue;
        }

        // Compare output signatures
        bool output_matches = true;
        for (const APEX_Parm &filter_o : filter.outputs())
        {
            const APEX_Parm &sig_o = sig.findOutput(filter_o.name());
            if (!sig_o.isValid() || sig_o.myTypeDefn != filter_o.myTypeDefn)
            {
                output_matches = false;
                break;
            }
        }
        if (!output_matches)
        {
            callbacks.removeItem(it);
            removed_count++;
        }
    }

    return removed_count;
}

} // end namespace apex

#endif