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

#ifndef __PDG_NODE_INTERFACE_H__
#define __PDG_NODE_INTERFACE_H__

#include "PDG_API.h"

#include "PDG_ApplicationShim.h"
#include "PDG_AttributeInfo.h"
#include "PDG_JobScriptInfo.h"
#include "PDG_NodePorts.h"
#include "PDG_Port.h"

#include <PDGT/PDGT_ValueArgs.h>

#include <UT/UT_Array.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringMap.h>

#include <SYS/SYS_TypeDecorate.h>

#define PDG_BUILTIN_PARAM_PREFIX "pdg_"
#define PDG_BUILTIN_TAG_PREFIX "pdg::"

#define PDG_BUILTIN_PARAM(name) PDG_BUILTIN_PARAM_PREFIX name
#define PDG_SEP_PARAM(index) "sepparm" #index
#define PDG_BUILTIN_TAG(name) PDG_BUILTIN_TAG_PREFIX name

class PDG_Node;
class PDG_WorkItem;
class UT_WorkBuffer;

class PDG_API PDG_NodeInterface : UT_NonCopyable
{
public:
    struct ParameterGroup
    {
        UT_StringHolder name;

        exint           count;
        exint           parent;

        bool            multiparm;
    };

    using ParameterGroupArray = UT_Array<ParameterGroup>;

    struct AutoFileDependency
    {
        UT_StringHolder type;
        UT_StringHolder key;
        PDGT_ValueArgs args;
    };

    using DependencyArray   = UT_Array<AutoFileDependency>;

public:

    /// UT_StringHolder instances for built in PDG parm/data field names. Since
    /// some of these are used during the cook, it's advantageous to store them
    /// as static instances and refer to them using PDG_NodeInterace::theXYZX 
    /// rather just referring to them with a const char* to avoid rehashing for
    /// map lookups. 
    static const UT_StringHolder theProcessorCommandParm;
    static const UT_StringHolder theProcessorWorkItemGenerationParm;
    static const UT_StringHolder theProcessorCacheModeParm;
    static const UT_StringHolder theProcessorCookTypeParm;
    static const UT_StringHolder theProcessorServiceNameParm;
    static const UT_StringHolder theProcessorServiceResetWhenParm;
    static const UT_StringHolder theProcessorServiceResetTypeParm;
    static const UT_StringHolder theProcessorUseServiceBlockParm;
    static const UT_StringHolder theProcessorPriorityTypeParm;
    static const UT_StringHolder theProcessorPriorityExpressionParm;

    static const UT_StringHolder theProcessorLabelTypeParm;
    static const UT_StringHolder theProcessorLabelExpressionParm;

    static const UT_StringHolder theProcessorUseScheduleWhenParm;
    static const UT_StringHolder theProcessorScheduleWhenParm;

    static const UT_StringHolder theFeedbackBeginParm;
    static const UT_StringHolder theFeedbackFilesParm;
    static const UT_StringHolder theFeedbackAttribsParm;
    static const UT_StringHolder theFeedbackAttribPatternParm;

    static const UT_StringHolder thePartitionerSortParm;
    static const UT_StringHolder thePartitionerSortAttribParm;
    static const UT_StringHolder thePartitionerSortDirectionParm;
    static const UT_StringHolder thePartitionerSortRequiredParm;
    static const UT_StringHolder thePartitionerWhenParm;
    static const UT_StringHolder thePartitionerIgnoreFailures;

    static const UT_StringHolder thePartitionerSplitEnabledParm;
    static const UT_StringHolder thePartitionerSplitAttributeParm;
    static const UT_StringHolder thePartitionerSplitMissingParm;
    static const UT_StringHolder thePartitionerSplitDefaultParm;
    static const UT_StringHolder thePartitionerSplitPartialParm;

    static const UT_StringHolder thePartitionerTargetTypeParm;
    static const UT_StringHolder thePartitionerTargetParm;
    static const UT_StringHolder thePartitionerMergeParm;

    static const UT_StringHolder thePartitionerMergeOutputsParm;
    static const UT_StringHolder thePartitionerMergeAttribsParm;
    static const UT_StringHolder thePartitionerMergeOpParm;
    static const UT_StringHolder thePartitionerMergePatternParm;
    static const UT_StringHolder thePartitionerMergePreserveParm;

    static const UT_StringHolder thePartitionerStoreIDsParm;
    static const UT_StringHolder thePartitionerIDAttribParm;

    static const UT_StringHolder thePartitionerSetFrameParm;

    static const UT_StringHolder theSchedulerWorkingDirParm;
    static const UT_StringHolder theSchedulerDataSourceParm;
    static const UT_StringHolder theSchedulerValidateOutputsParm;
    static const UT_StringHolder theSchedulerCheckExpectedOutputsParm;
    static const UT_StringHolder theSchedulerCompressWorkItemDataParm;
    static const UT_StringHolder theSchedulerTickPeriodParm;
    static const UT_StringHolder theSchedulerMaxItemsParm;
    static const UT_StringHolder theSchedulerUseMaxTasksParm;
    static const UT_StringHolder theSchedulerMaxTasksParm;
    static const UT_StringHolder theSchedulerMapModeParm;
    static const UT_StringHolder theSchedulerMapZoneParm;
    static const UT_StringHolder theSchedulerUseMapZoneParm;
    static const UT_StringHolder theSchedulerWaitForFailuresParm;
    static const UT_StringHolder theSchedulerDeleteTempDirParm;

    static const UT_StringHolder theSchedulerRpcTimeout;
    static const UT_StringHolder theSchedulerRpcRetries;
    static const UT_StringHolder theSchedulerRpcBackoff;
    static const UT_StringHolder theSchedulerRpcBatch;
    static const UT_StringHolder theSchedulerRpcRelease;
    static const UT_StringHolder theSchedulerRpcIgnoreErrors;
    static const UT_StringHolder theSchedulerRpcMaxErrors;

    static const UT_StringHolder theTagExpandName;
    static const UT_StringHolder theTagOpDepDirty;
    static const UT_StringHolder theTagOpDepRegen;
    static const UT_StringHolder theTagExtraInput;

    static const UT_StringHolder theSeparatorLabel;

    static const UT_StringHolder theGenerateMenuScript;
    static const UT_StringHolder theCacheModeMenuScript;

public:
                                PDG_NodeInterface(
                                    UT_StringHolder name = "",
                                    UT_StringHolder data_type = "");
    virtual                     ~PDG_NodeInterface();

    int64                       getMemoryUsage(bool inclusive) const;

    /// Clones the template interface into the ports/parameters on this
    /// interface.
    void                        cloneFrom(const PDG_NodeInterface& interface);

    /// Adds builtin ports for the specified node type and subtype
    void                        addBuiltinPorts(
                                    PDG_NodeType type,
                                    PDG_NodeSubtype sub_type);

    /// Queries the work item data type associated with this node
    PDG_WorkItemDataType*       workItemDataType()
                                    { return myWorkItemDataType; }
    const PDG_WorkItemDataType* workItemDataType() const
                                    { return myWorkItemDataType; }

    /// Resolves and caches the work item data type
    bool                        resolveWorkItemDataType(UT_WorkBuffer& errors);

    /// Returns the list of all ports of the specified type
    const PDG_PortArray&        ports(PDG_PortType type) const;
    const PDG_PortArray&        inputPorts() const;
    const PDG_PortArray&        outputPorts() const;
    const PDG_PortArray&        parameters() const;

    /// Returns the list of parameter groups for the node
    const ParameterGroupArray&  parameterGroups() const
                                    { return myParameterGroups; }

    /// Returns the list of parameters with the specified tag
    bool                        parametersForTag(
                                    const UT_StringHolder& tag,
                                    PDG_PortArray& parameters) const;

    /// Returns the list of custom parameter ports.
    const PDG_PortArray&        customParameters() const;

    /// Find a port by type, index and/or name. If no matching port is found,
    /// nullptr is returned.
    PDG_Port*                   port(PDG_PortType type, int index) const;
    PDG_Port*                   port(
                                    PDG_PortType type,
                                    const UT_StringHolder& name) const;
    PDG_Port*                   port(const UT_StringHolder& name) const;

    /// Specialized functions for finding input ports by name or index
    PDG_Port*                   inputPort(int index) const;
    PDG_Port*                   inputPort(const UT_StringHolder& name) const;
    bool                        inputPortsForNode(
                                    PDG_Node* node,
                                    PDG_PortArray& ports) const;
    bool                        inputPortsForWorkItem(
                                    const PDG_WorkItem* work_item,
                                    PDG_PortArray& ports) const;
    bool                        isWorkItemFromInputPort(
                                    const PDG_WorkItem* work_item,
                                    const UT_StringHolder& name) const;

    /// Sepcialized functions for finding output ports by name or index
    PDG_Port*                   outputPort(int index) const;
    PDG_Port*                   outputPort(const UT_StringHolder& name) const;

    /// Returns the parameter with the specified name, or nullptr if no such
    /// parameter exists.
    PDG_Port*                   parameter(
                                    const UT_StringHolder& name,
                                    int multi=-1) const;

    /// Returns the value and default value of the parameter with the
    /// specified name and index. If no parameter is found or the index is
    /// out of range, nullptr is returned.
    PDGT_Value*                 paramValue(
                                    const UT_StringHolder& name,
                                    int index=0) const;
    PDGT_Value*                 defaultParamValue(
                                    const UT_StringHolder& name,
                                    int index=0) const;

    /// Returns the numbers of ports with the specified type (input,
    /// output, etc).
    int                         portCount(PDG_PortType type) const;
    int                         inputCount() const;
    int                         outputCount() const;
    int                         parameterCount() const;

    /// Returns information about the number of ordered vs. unordered input
    /// ports on this node.
    bool                        hasUnorderedPorts() const;
    int                         numOrderedPorts() const;

    /// Adds the specified port, which can be an input, output or a parameter.
    /// Returns the new port on success, else returns failure.
    PDG_Port*                   addPort(
                                    PDG_PortType type,
                                    const PDG_WorkItemDataType* data_type,
                                    const UT_StringHolder& name,
                                    const UT_StringHolder& label,
                                    const UT_StringArray& tags = UT_StringArray(),
                                    int size = 0,
                                    bool ordered = true,
                                    bool custom = false);

    /// Adds a parameter with the specified data type, size, name, label and
    /// tag list. Returns the parameter on success, or nullptr on failure.
    PDG_Port*                    addParameter(
                                    PDGT_Value::DataType data_type,
                                    const UT_StringHolder& name,
                                    const UT_StringHolder& label,
                                    const UT_StringArray& tags,
                                    int size = 1,
                                    bool custom = false);

    /// Adds a parameter with a data type, name, label and optional size.
    PDG_Port*                    addParameter(
                                    PDGT_Value::DataType data_type,
                                    const UT_StringHolder& name,
                                    const UT_StringHolder& label,
                                    int size = 1,
                                    bool custom = false);

    /// Removes the specified parameter by name, and returns true if the
    /// parameter was found and successfully removed.
    bool                        removeParameter(const UT_StringHolder& name);

    /// Adds a new file dependency to the node interface
    void                        addFileDependency(
                                    const UT_StringHolder& file_path);

    /// Adds a new parameter group to the node interface
    void                        addParameterGroup(
                                        const UT_StringHolder& name,
                                        bool root = true,
                                        bool multiparm = false);

    /// Ends the current parameter group
    void                        endParameterGroup();

    /// If this interface represents a template, returns the name of that
    /// template
    const UT_StringHolder&      templateName() const
                                    { return myTemplateName; }

    /// Returns the template interface that defined how this interface
    /// was created
    virtual const PDG_NodeInterface*
                                templateInterface() const
                                    { return nullptr; }

    /// Returns true if the node interface is valid
    bool                        isValid() const
                                    { return myValidFlag; }

    /// Returns the list of external files that this node depends on.
    const DependencyArray&      autoDependencies() const
                                    { return myAutoDependencies; }

    /// Returns the list of common expression variables, available on all
    /// parameters on this node interface.
    const PDG_Port::ExpressionVars&
                                commonVars() const
                                    { return myCommonVars; }

    /// Returns the underlying application node associated with this PDG node,
    /// for example a TOP node or TOP scheduler. This may be null.
    PDG_ApplicationShim::Node*  appNode() const
                                    { return myAppNode.get(); }

    /// Sets the underlying app node.
    template <typename T, typename... Args>
    void                        setAppNode(Args&&... args)
                                    {
                                        myAppNode = UTmakeUnique<T>(
                                            std::forward<Args>(args)...);
                                    }

    /// Returns the attribute info object for this node interface. If this is
    /// a template loaded from .json, the attribute info object contains the
    /// definition as it was specified in the template. Otherwise, if this is
    /// a cooked node, then it contains the evaluated attribute info from the
    /// last cook.
    const PDG_AttributeInfo&    attributeInfo() const
                                    { return myAttributeInfo; }

    /// Clears and sets the attribute info for this interface
    void                        setAttributeInfo(const PDG_AttributeInfo& info)
                                    { myAttributeInfo = info; }

    /// Returns the script info for this node interface.
    const PDG_JobScriptInfo&    scriptInfo() const
                                    { return myScriptInfo; }

    /// Sets the script info for the interface
    void                        setScriptInfo(const PDG_JobScriptInfo& info)
                                    { myScriptInfo = info; }

    /// Adds a single entry to the job script info's service compatiblity
    /// list
    void                        setServiceCompatibility(
                                    const UT_StringHolder& service_type_name,
                                    bool compatible);

    /// Adds an error to the node interface -- implemented in subclasses
    virtual void                addError(const UT_StringHolder& message) const
                                    {}

    /// Adds an error using a format string, instead of plain string
    template <typename... Args>
    void                        addErrorFmt(
                                        const char* fmt,
                                        Args&&... args) const
                                    {
                                        UT_WorkBuffer buffer;
                                        buffer.format(
                                            fmt, std::forward<Args>(args)...);
                                        addError(buffer.buffer());
                                    }

    /// Adds a warning to the node interface -- implemented in subclasses
    virtual void                addWarning(const UT_StringHolder& message) const
                                    {}

    /// Adds a warning using a format string, instead of plain string
    template <typename... Args>
    void                        addWarningFmt(
                                        const char* fmt,
                                        Args&&... args) const
                                    {
                                        UT_WorkBuffer buffer;
                                        buffer.format(
                                            fmt, std::forward<Args>(args)...);
                                        addWarning(buffer.buffer());
                                    }

    /// Evaluates a parameter and reports errors if desired
    template <typename T>
    bool                        evaluate(T& result,
                                         const UT_StringHolder& name,
                                         const PDG_WorkItem* work_item=nullptr,
                                         int index=0,
                                         int multi=-1) const
    {
        PDG_Port* parm = parameter(name, multi);
        if (!parm)
            return false;

        UT_WorkBuffer errors;
        if (parm->evaluate(index, result, work_item, errors))
            return true;

        addError(errors.buffer());
        return false;
    }

    /// Evaluates a string parameter as a raw string, and reports errors if
    /// desired.
    bool                        evaluateRaw(
                                    UT_StringHolder& result,
                                    const UT_StringHolder& name,
                                    const PDG_WorkItem* work_item=nullptr,
                                    int index=0,
                                    int multi=-1) const
    {
        PDG_Port* parm = parameter(name, multi);
        if (!parm)
            return false;

        UT_WorkBuffer errors;
        if (parm->evaluateRaw(index, result, work_item, errors))
            return true;

        addError(errors.buffer());
        return false;
    }

    /// Evaluates a parameter as an array and reports errors if desired
    template <typename T>
    bool                        evaluateArray(
                                        T& result,
                                        const UT_StringHolder& name,
                                        const PDG_WorkItem* work_item=nullptr,
                                        int multi=-1) const
    {
        PDG_Port* parm = parameter(name, multi);
        if (!parm)
            return false;

        UT_WorkBuffer errors;
        if (parm->evaluate(result, work_item, errors))
            return true;

        addError(errors.buffer());
        return false;
    }

protected:
    PDG_AttributeInfo           myAttributeInfo;

private:
    PDG_Port*                   addPortInternal(
                                    PDG_PortType type,
                                    const PDG_WorkItemDataType* data_type,
                                    const UT_StringHolder& name,
                                    const UT_StringHolder& label,
                                    int size = 0,
                                    bool ordered = true,
                                    bool custom = false,
                                    bool builtin = false);
private:
    friend class PDG_NodeTemplate;

    using TaggedParameters = UT_StringMap<PDG_PortArray>;

    PDG_NodePorts               myPorts;
    TaggedParameters            myTaggedParameters;
    PDG_PortArray               myCustomParameters;
    UT_StringArray              myMultiEntries;
    DependencyArray             myAutoDependencies;
    PDG_Port::ExpressionVars    myCommonVars;

    ParameterGroupArray         myParameterGroups;

    UT_StringHolder             myTemplateName;
    UT_StringHolder             mySpecifiedWorkItemDataType;
    mutable PDG_WorkItemDataType*
                                myWorkItemDataType;
    UT_UniquePtr<PDG_ApplicationShim::Node>
                                myAppNode;

    PDG_JobScriptInfo           myScriptInfo;

    int                         myCurrentParameterGroup;
    int                         myNumOrderedPorts;

    bool                        myUnorderedFlag;
    bool                        myValidFlag;
    bool                        myNoSchedulerParams;
    bool                        myHasCustomInputs;
    bool                        myHasCustomOutputs;
};

SYS_DECLARE_LEGACY_TR(PDG_NodeInterface)

#endif