PDG_NodeCallback.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_CALLBACK_H__
#define __PDG_NODE_CALLBACK_H__

#include "PDG_API.h"

#include "PDG_LogUtils.h"
#include "PDG_Node.h"
#include "PDG_RegisteredType.h"

#include <UT/UT_ParallelUtil.h>
#include <UT/UT_PerfMonAutoEvent.h>
#include <UT/UT_Performance.h>
#include <UT/UT_WorkBuffer.h>

#define _PDG_INVOKE_CALLBACK(result, type, state, node, item, localize, ...) \
{ \
    PDG_LogUtils::nodeLog( \
        PDG_LogUtils::eNodeDebugCallback, node, "CALLBACK on" #type, \
        UT_StringHolder::theEmptyString); \
    UT_WorkBuffer _event_path; \
    bool path_has_item = node->performancePath(_event_path, #type, item); \
    UT_PerfMonAutoPDGCookEvent event( \
        _event_path.buffer(), (path_has_item ? nullptr : #type)); \
    PDG_EvaluationContext::StateScope scope(SYSgetSTID(), state, \
        localize, node, item, node->context()); \
    UTisolate([&]() \
    { \
        try \
        {\
            result = node->callback()->postInvoke( \
                node->callback()->on ## type (__VA_ARGS__)); \
        } \
        catch (...) \
        { \
            result = PDG_CallbackResult::eFailure; \
        }\
    });\
}

#define PDG_NODE_CALLBACK(result, type, state, node, ...) \
{ \
    result = PDG_CallbackResult::eMissing; \
    if (node->callback()->hasCallback(PDG_NodeCallback::e ## type))\
    {\
        _PDG_INVOKE_CALLBACK( \
            result, type, state, node, nullptr, false, __VA_ARGS__); \
    }\
}

#define PDG_TASK_CALLBACK(result, type, item, localize) \
{ \
    result = PDG_CallbackResult::eMissing; \
    if (item->node()->callback()->hasCallback(PDG_NodeCallback::e ## type)) \
    {\
        PDG_AttributeMap::ScopedLock<false> auto_lock(item->attributes()); \
        _PDG_INVOKE_CALLBACK( \
            result, type, PDG_EvaluationContext::eStateCooking, \
            item->node(), item, localize, item); \
    } \
}

class PDG_DependencyHolder;
class PDG_Node;
class PDG_NodeOptions;
class PDG_PartitionHolder;
class PDG_WorkItemHolder;
class PDG_WorkItem;

class PDG_API PDG_NodeCallback : public PDG_TypeInstance
{    
public:
    /// Work item generation type
    enum GenerationType
    {
        eStaticGenerate     = 0,
        eDynamicGenerate    = 1,

        eStaticRegenerate   = 2,
        eDynamicRegenerate  = 3,
    };

    /// Enumeration of node callbacks. These enum values are a
    /// power of 2 since they go into a bit vector for checking
    /// the presence of callbacks
    enum CallbackType
    {
        eGenerate                   = 0x0001,
        eRegenerate                 = 0x0002,

        eAddInternalDependencies    = 0x0004,

        ePartition                  = 0x0008,
        ePostPartition              = 0x0010,
        eMapStatic                  = 0x0020,
        eMapDynamic                 = 0x0040,

        ePreCook                    = 0x0080,
        ePostCook                   = 0x0100,

        ePrepareTask                = 0x0200,
        eCookTask                   = 0x0400,
        ePostCookTask               = 0x0800,

        eSelectTask                 = 0x1000,
        eDeselectTask               = 0x2000,

        eConfigureNode              = 0x4000,

        eProcessorBits              = eGenerate | eRegenerate | eConfigureNode,
        ePartitionerBits            = ePartition,
        eMapperBits                 = eMapStatic | eMapDynamic,
    };

public:
    PDG_NodeCallback(const PDG_BaseType* type,
                     const PDGT_ValueArgs& extra_args,
                     PDG_Node* node);
    ~PDG_NodeCallback() override;

    /// Returns the memory usage of this callback
    int64           getMemoryUsage(bool inclusive) const override;

    /// Returns true if the node callback has the specified callback installed,
    /// else returns false
    bool            hasCallback(CallbackType callback_type) const;

    /// Enables a specific node callback
    void            enableCallback(CallbackType callback_type);

    /// Resets this node callback to match changes to the type object
    bool            reloadInstance(UT_WorkBuffer& errors) override;

    /// Performs post callback invocation logic and returns a final
    /// callback result
    PDG_CallbackResult
                    postInvoke(PDG_CallbackResult invoke_result) const;


    /// Generates static items via a work item holder. Called on processors.
    virtual PDG_CallbackResult
                    onGenerate(PDG_WorkItemHolder*,
                               const PDG_WorkItemArray&,
                               GenerationType generation_type);

    /// Regenerates static items, only called when items already exist. The 
    /// callback can add new items, or dirty/delete existing items.
    virtual PDG_CallbackResult
                    onRegenerate(PDG_WorkItemHolder*,
                                 const PDG_WorkItemArray&,
                                 const PDG_WorkItemArray&,
                                 GenerationType generation_type);

    /// Adds dependencies between newly created work items. Called on 
    /// processors.
    virtual PDG_CallbackResult
                    onAddInternalDependencies(PDG_DependencyHolder*,
                                              const PDG_WorkItemArray&,
                                              bool is_static);

    /// Groups upstream work items into partitions that can be non-disjoint and
    /// do not necessarily cover the set of all items. Called on partitioner
    /// nodes.
    virtual PDG_CallbackResult
                    onPartition(PDG_PartitionHolder*,
                                const PDG_WorkItemArray&,
                                const PDG_WorkItem*);

    /// Runs after partitions have been created, so that the node can edit
    /// attributes on the partition
    virtual PDG_CallbackResult
                    onPostPartition(
                                PDG_WorkItem* partition,
                                const PDG_WorkItemConstArray& partition_items);

    /// Adds dependencies between static itrems below a mapper node and static
    /// ancestors above. Called on mapper nodes.
    virtual PDG_CallbackResult
                    onMapStatic(PDG_DependencyHolder* holder,
                                const PDG_WorkItemArray& downstream_items,
                                const PDG_WorkItemArray& upstream_items);

    /// Adds dependencies between dynamic items above a mapper and static items
    /// below the mapper.
    virtual PDG_CallbackResult
                    onMapDynamic(PDG_DependencyHolder* holder,
                                 const PDG_WorkItemArray& downstream_items,
                                 const PDG_WorkItemArray& upstream_items);

    /// Called before the graph begins cooking. This is only called on nodes
    /// that are on the active cook path, and is guaranteed to be called on each
    /// node before any threaded cooking begins. If a Failure result is returned
    /// from any of the nodes, the cook is aborted
    virtual PDG_CallbackResult
                    onPreCook();

    /// Called on each node in the graph after the cook finishes.
    virtual PDG_CallbackResult
                    onPostCook();

    /// Called when a work item has all of its dependencies satisfied, and will
    /// be submitted to the scheduler or cooked in-process shortly.
    virtual PDG_CallbackResult
                    onPrepareTask(PDG_WorkItem* work_item);

    /// Called when a work item wants to cook in-process, but does not have its
    /// own cook implementation
    virtual PDG_CallbackResult
                    onCookTask(PDG_WorkItem* work_item);

    /// Called when a work item has completed cooking.
    virtual PDG_CallbackResult
                    onPostCookTask(PDG_WorkItem* work_item);

    /// Called when a work item is selected by TOPs.
    virtual PDG_CallbackResult
                    onSelectTask(PDG_WorkItem* work_item);

    /// Called when a work item is deselcted
    virtual PDG_CallbackResult
                    onDeselectTask(PDG_WorkItem* work_item);

    /// Called when the node should describe itself for the UI
    virtual PDG_CallbackResult
                    onConfigureNode(PDG_NodeOptions* node_options);

    /// Returns the node associated with this callback
    PDG_Node*       node() const;

    /// Returns the cook type of the node associated with this callback,
    /// if it's a processor node
    PDG_WorkItemCookType
                    cookType() const;


    /// Convenience method for evaluating a parameter on the underlying node
    template <typename T>
    bool            evaluate(
                        T& result,
                        const UT_StringHolder& name,
                        const PDG_WorkItem* work_item=nullptr,
                        int index=0,
                        int multi=-1) const
    {
        return myNode->evaluate(result, name, work_item, index, multi);
    }

    /// Convenience method for evaluating a parameter as an array on the
    /// underlying node
    template <typename T>
    bool            evaluateArray(
                        T& result,
                        const UT_StringHolder& name,
                        const PDG_WorkItem* work_item=nullptr,
                        int multi=-1) const
    {
        return myNode->evaluate(result, name, work_item, multi);
    }

    /// Evaluates a parameter as a string and returns the value back, instead
    /// of an error code.
    UT_StringHolder evaluateS(
                        const UT_StringHolder& name,
                        const PDG_WorkItem* work_item=nullptr,
                        int index=0,
                        int multi=-1) const
    {
        UT_StringHolder result = "";
        myNode->evaluate(result, name, work_item, index, multi);
        return result;
    }

    /// Evaluates a parameter as a raw string and returns the value back,
    /// instead of an error code.
    UT_StringHolder evaluateRaw(
                        const UT_StringHolder& name,
                        const PDG_WorkItem* work_item=nullptr,
                        int index=0,
                        int multi=-1) const
    {
        UT_StringHolder result = "";
        myNode->evaluateRaw(result, name, work_item, index, multi);
        return result;
    }

    /// Evaluates a parameter as a float and returns the value back, instead
    /// of an error code.
    fpreal          evaluateF(
                        const UT_StringHolder& name,
                        const PDG_WorkItem* work_item=nullptr,
                        int index=0,
                        int multi=-1) const
    {
        fpreal result = 0;
        myNode->evaluate(result, name, work_item, index, multi);
        return result;
    }

    /// Evaluates a parameter as an integer and returns the value back, instead
    /// of an error code.
    exint           evaluateI(
                        const UT_StringHolder& name,
                        const PDG_WorkItem* work_item=nullptr,
                        int index=0,
                        int multi=-1) const
    {
        exint result = 0;
        myNode->evaluate(result, name, work_item, index, multi);
        return result;
    }

    /// Evaluates a parameter as a boolean and returns the value back, instead
    /// of an error code.
    bool            evaluateB(
                        const UT_StringHolder& name,
                        const PDG_WorkItem* work_item=nullptr,
                        int index=0,
                        int multi=-1) const
    {
        bool result = false;
        myNode->evaluate(result, name, work_item, index, multi);
        return result;
    }

    /// Evaluates a parameter as an arbitrary type and returns the value back,
    /// instad of an error code.
    template <typename T>
    T               evaluateT(
                        const UT_StringHolder& name,
                        const PDG_WorkItem* work_item=nullptr,
                        int index=0,
                        int multi=-1) const
    {
        T result{};
        myNode->evaluate(result, name, work_item, index, multi);
        return result;
    }

protected:
    PDG_Node*       myNode;
    int             myCallbackBits;
};

#endif