PDG_EvaluationContext.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_EVALUATION_CONTEXT_H__
#define __PDG_EVALUATION_CONTEXT_H__

#include "PDG_API.h"

#include "PDG_AttributeEvaluator.h"
#include "PDG_AttributeInfo.h"

#include <PY/PY_Result.h>

#include <UT/UT_ErrorManager.h>
#include <UT/UT_Function.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_StringMap.h>

#include <SYS/SYS_Hash.h>

#include <iosfwd>

class PY_PyObject;
class PY_CompiledCode;
class PY_EvaluationContext;

class PDG_AttributePyObject;
class PDG_Graph;
class PDG_GraphContext;
class PDG_Node;
class PDG_WorkItem;

class UT_IStream;
class UT_StringHolder;
class UT_WorkBuffer;

/*
 * A context for evaluation PDG Python expression. Each thread-local context has
 * its own local dictionary which it uses to evaluate expressions, allowing
 * node authors to insert their own local variables in node callbacks. The dict
 * is cleared at the beginning of each callback invocation.
 */
class PDG_API PDG_EvaluationContext : public UT_NonCopyable
{
public:
    /// Evaluation context state
    enum State
    {
        eStateNone,
        eStateStatic,
        eStateDynamic,
        eStateCooking,
        eStateDirtying
    };

    /// Enumeration of python script evaluation results
    enum EvaluationResult
    {
        /// The script succeeded without any exceptions
        eResultSuccess,

        /// The script encountered an error or exception
        eResultFailure,

        /// The script was aborted, e.g. with a sys.exit(..) call
        eResultAbort
    };

    /// Scoped reset of the thread-local context cooking/generation state
    class PDG_API StateScope
    {
    public:
        StateScope(
            int thread,
            State state,
            bool localize,
            const PDG_Node* node,
            const PDG_WorkItem* work_item,
            PDG_GraphContext* context);
        StateScope(
            int thread,
            State state,
            bool localize,
            const PDG_Node* node,
            const PDG_WorkItem* work_item,
            fpreal time);
        ~StateScope();
        UT_NON_COPYABLE(StateScope)

    private:
        void                init(
                                int thread,
                                State state,
                                bool localize,
                                const PDG_Node* node,
                                const PDG_WorkItem* work_item,
                                fpreal time);

    private:
        UT_AutoErrorManager myErrorManager;
        const PDG_Node*     myActiveNode;
        const PDG_Node*     myNode;
        const PDG_WorkItem* myPreviousItem;
        PY_PyObject*        myLocals;
        fpreal              myEvalTime;
        int                 myThread;

        State               myState;
        bool                myParameterError;
        bool                myPushedDir;
        bool                myLocalize;
        bool                myPreviousParent;
    };

    /// Scoped setter of local work item
    class PDG_API ItemScope
    {
    public:
        ItemScope(int thread,
                  const PDG_WorkItem* work_item,
                  bool is_parent);
        ~ItemScope();
        UT_NON_COPYABLE(ItemScope)

    private:
        const PDG_WorkItem*     myPreviousItem;
        int                     myThread;
        bool                    myPreviousParent;
    };

    /// Scoped block that records PDG attribute evaluations
    class PDG_API AttribRecordScope
    {
    public:
        using ExprData          = PDG_AttributeInfo::ExprData;

    public:
                                AttribRecordScope(int thread);
                                ~AttribRecordScope();
                                UT_NON_COPYABLE(AttribRecordScope)

        void                    reset();
        void                    record(const UT_StringHolder& attrib);
        const UT_StringArray&   expressionAttribs() const
                                    { return myExpressionAttribs; }

    private:
        UT_StringArray          myExpressionAttribs;
        AttribRecordScope*      myPreviousRecord;
        int                     myThread;
    };

    /// Utility function type for converting a PDG_WorkItem* to a PY_PyObject.
    using WorkItemCaster = UT_Function<PY_PyObject*(const PDG_WorkItem*)>; 

public:
    /// Constructs a new context. Should not be called, only here because the
    /// thread local var needs it to be public instead of private.
    PDG_EvaluationContext();
    ~PDG_EvaluationContext();

    UT_NON_COPYABLE(PDG_EvaluationContext)

    /// Returns the built-in functions that are available in the the context
    static void                     builtinFunctions(UT_StringArray& functions);

    /// Sets the work item caster function, which is used when setting a work
    /// item as a Python dictonary variable from C++. If the caster function
    /// is not installed, a slower code path that looks up the work item from
    /// the graph is used instead.
    static void                     setWorkItemCaster(
                                                const WorkItemCaster& caster);


    ///  Configures whether or not all PDG_EvaluationContext instance should
    /// use Python.
    static void                     setUsePython(bool use_python);

    /// Returns the shared Python context in which expressions evaluated
    static PY_EvaluationContext&    getExpressionContext();

    /// Returns the thread-local PDG_EvaluationContext instance
    static PDG_EvaluationContext*   getContext();

    /// Returns the thread-local PDG_EvaluationContext instance for the
    /// specific thread
    static PDG_EvaluationContext*   getContext(int thread);


    /// Sets the global batch subitem index. Used when constructing an active
    /// work item on the job side, to make attributes available.
    static void                     setGlobalSubItemIndex(int index,
                                                          bool dirty);

    /// Sets the global active work item. Used for setting an active item
    /// in the current houdini session for debugging, or as part of a houdini-
    /// based job on the farm.
    static void                     setGlobalWorkItem(
                                            const PDG_WorkItem* work_item,
                                            bool dirty);

    /// Sets the global active item for an out of process work item job
    static void                     setGlobalJobWorkItem(
                                        PDG_WorkItem* work_item,
                                        const UT_StringHolder& node_name,
                                        const UT_StringHolder& scheduler_name);

    /// Adds the specified attributes to the global set of time dependent 
    /// attribs, for out-of-process batch cooks that have different attribute
    /// values at each frame.
    static void                     setTimeDependentAttribs(
                                        const UT_ArrayStringSet& names,
                                        bool dirty);

    /// Dirties all dependent attributes
    static void                     dirtyAllAttribs();

    /// Saves all attributes and field from the global active work item to the
    /// specified output stream.
    static bool                     saveGlobalWorkItem(std::ostream &os);

    /// Loads the data from the specified input stream into a free-standing
    /// work item, which is saved as the default global item until one is
    /// selected in the UI.
    static bool                     loadGlobalWorkItem(UT_IStream& is);

    /// Quries the global work item. This should not be used in most cases,
    /// except for when checking if the global item needs to be cleared
    static const PDG_WorkItem*      globalWorkItem(bool sub_item);

    /// Queries the global node name. Used on the job side to determine the
    /// work item name, since the work item does not directly store a string
    /// name on its own.
    static const UT_StringHolder&   globalNodeName();

    /// Queries the global scheduler name. Used on the job side to determine 
    /// the submitting scheduler name, since the work item doesn't have direct
    /// access to the scheduler itself.
    static const UT_StringHolder&   globalSchedulerName();

    /// Returns true if PDG attribute evaluation is time dependent, else false
    static bool                     useTimeDependentAttribs();

    /// Returns true if the specified attribute is time dependent, else false
    static bool                     isTimeDependent(
                                        const UT_StringHolder& name);

    /// Queries the current active work item. If a PDG cook is in-progress, this
    /// will return the thread-local item. If there is no active cook, this will
    /// return whatever global work item was set
    static const PDG_WorkItem*      activeWorkItem(int thread);

    /// Queries the thread local is-parent flag
    static bool                     activeIsParent(int thread);

    /// Returns true if the thread local state is generating
    static bool                     isLocalGenerating(int thread);

    /// Returns true if the thread local state is runtime
    static bool                     isLocalRuntime(int thread);
    
    /// Returns true if the thread local state indicates the thread is being
    /// used to do PDG work
    static bool                     isLocalActive(int thread);

    /// Returns true if a PDG job is active, either in process or out of
    /// process, for the specified thread. Out of process jobs that load in a
    /// PDG work item are always considered to be active PDG jobs. Otherwise,
    /// this method falls back to ::isLocalActive.
    static bool                     isLocalCookingPDG(int thread);

    /// Returns the current state of the thread local evaluation context
    static State                    localState(int thread);

    /// Returns the current evaluation time of the thread local context
    static fpreal                   localEvalTime(int thread);

    /// Returns the thread-local active node
    static const PDG_Node*          localActiveNode(int thread);


    /// Gets an attribute evaluator
    static PDG_AttributeEvaluator*  createAttributeEvaluator(int thread,
                                                             const char* name);

    /// Sets the Python evaluation dictionary directly
    static void                     setDict(int thread, PY_PyObject* locals);

    /// Returns the local Python dictionary object
    static PY_PyObject*             localDict(int thread);

    /// Sets or updates primitive values in the Python dictionary
    static void                     updateDict(int thread,
                                               const UT_StringHolder& name,
                                               fpreal value);
    static void                     updateDict(int thread,
                                               const UT_StringHolder& name,
                                               int value);
    static void                     updateDict(int thread,
                                               const UT_StringHolder& name,
                                               const UT_StringHolder& value);

    /// Sets or updates a PDG work in the Python dictionary
    static void                     updateDict(int thread,
                                               const UT_StringHolder& name, 
                                               const PDG_WorkItem* work_item);

    /// Sets or updates a PDG node in the Python dictionary
    static void                     updateDict(int thread,
                                               const UT_StringHolder& name, 
                                               const PDG_Node* node);

    /// Sets or update a PDG graph inthe Python dictionary
    static void                     updateDict(int thread,
                                               const UT_StringHolder& name,
                                               const PDG_Graph* graph);

    /// Resets the thread-local context's local Python dictionary
    static void                     resetDict(int thread);


    /// Primitive Python eval methods (loat, int, string)
    static EvaluationResult         evaluate(int thread,
                                             const PY_CompiledCode& expression,
                                             fpreal& result,
                                             UT_WorkBuffer& errors);
    static EvaluationResult         evaluate(int thread,
                                             const PY_CompiledCode& expression,
                                             exint& result,
                                             UT_WorkBuffer& errors);
    static EvaluationResult         evaluate(int thread,
                                             const PY_CompiledCode& expression,
                                             UT_StringHolder& result,
                                             UT_WorkBuffer& errors);

    /// PyObject eval method
    static EvaluationResult         evaluate(int thread,
                                             const PY_CompiledCode& expression,
                                             void*& result,
                                             UT_WorkBuffer& errors);

    /// Void/no-result eval method
    static EvaluationResult         evaluate(int thread,
                                             const PY_CompiledCode& expression,
                                             UT_WorkBuffer& errors);

    /// Evaluates an abritrary string and returns the PyObject, rather than
    /// evaluating a compiled code instance.
    static EvaluationResult         evaluateCodeString(
                                              int thread,
                                              const UT_StringHolder& raw_code,
                                              void*& result,
                                              bool multi,
                                              UT_WorkBuffer& errors);

    /// Saves a PyObject attribute to a string
    static bool                     savePyObjectAttr(
                                              int thread,
                                              UT_StringHolder& result,
                                              const PDG_AttributePyObject* attr,
                                              const UT_StringHolder& module);

    /// Loads a PyObject attribute to a string
    static bool                     loadPyObjectAttr(
                                              int thread,
                                              void*& result,
                                              const UT_StringHolder& attr_data,
                                              const UT_StringHolder& module);

    /// Cooks work item with the specified job script module
    static bool                     cookWorkItem(
                                              int thread,
                                              const UT_StringHolder& module,
                                              PDG_WorkItem* work_item,
                                              UT_WorkBuffer& errors);

    /// Hashes a PyOvject attribute
    static bool                     hashPyObjectAttr(
                                            SYS_HashType& result,
                                            const PDG_AttributePyObject* attr,
                                            UT_WorkBuffer& errors);

    /// Updates parameter error state
    static void                     updateParameterEvaluation(
                                            int thread,
                                            bool has_error);

public:
    /// Returns the context's active work item
    const PDG_WorkItem*             workItem() const;

    /// Returns true if the local work item is the parent item for the 
    /// evaluation
    bool                            isParent() const;

    /// Returns the active node for the the context
    const PDG_Node*                 activeNode() const;

    /// Returns the state of the context
    State                           state() const;

    /// Returns the parameter evaluation state of the context
    bool                            hasParameterError() const;

    /// Returns the current evaluation time of the context
    fpreal                          evalTime() const;

    /// Returns true if the context is in a generating state
    bool                            isGenerating() const
                                        { return (myState == eStateStatic) ||
                                                 (myState == eStateDynamic); }

    /// Returns true if the context is in a cooking state
    bool                            isCooking() const
                                        { return (myState == eStateCooking); }

    /// Returns true if the context is in a runtime state
    bool                            isRuntime() const
                                        { return (myState == eStateDynamic) ||
                                                 (myState == eStateCooking) ||
                                                 (myState == eStateNone); }
                                        

    /// Returns true if the context is actively doing PDG work
    bool                            isActive() const
                                        { return myState != eStateNone; }

    /// Returns true if the context should force file paths to be localized
    bool                            isLocalize() const
                                        { return myIsLocalize; }

    /// Returns true if the specified work item can be dirtied in the
    /// current context
    bool                            canDirty(const PDG_WorkItem* work_item) const;

    /// Returns true if the specified node can be dirtied in the current
    /// context
    bool                            canDirty(const PDG_Node* node) const;

    /// General version of the above method that can be called without a node
    bool                            canDirty() const;

    /// Records an attribute access with the active scope block, if one has
    /// been set
    void                            recordAttribute(const UT_StringHolder& name)
                                        {
                                            if (myAttributeRecord)
                                                myAttributeRecord->record(name);
                                        }

private:
    /// Internal initialize logic
    void                            init();

    /// Internal reset logic
    void                            reset();

    /// Returns the local dictionary
    PY_PyObject*                    dict() const;

    /// Returns the context's local work item
    const PDG_WorkItem*             activeWorkItem() const;

    /// Returns the context's current attribute record block, or nullptr if
    /// one has not been set.
    AttribRecordScope*              attributeRecord() const;

    /// Gets/Sets the local work item
    void                            setWorkItem(const PDG_WorkItem* work_item,
                                                bool parent);

    /// Sets the active node for the context
    void                            setActiveNode(const PDG_Node* node);

    /// Sets the context state
    void                            setState(State state);

    /// Sets the context parameter evaluation state
    void                            setParameterError(bool has_error);

    /// Sets the context eval time
    void                            setEvalTime(fpreal time);

    /// Sets the forced localization flag
    void                            setLocalize(bool localize);

    /// Set the active attribute record scope
    void                            setAttributeRecord(AttribRecordScope* scope);

    /// Adds an attribute evaluator to the map, or returns one if it already
    /// exists. Templated so the caller can select the type
    PDG_AttributeEvaluator*         attributeEvaluator(const char* name);

    /// Generic evaluation method that returns the result of an expression in
    /// a PY_Result object
    EvaluationResult                evaluate(const PY_CompiledCode& expression,
                                             PY_Result::Type type,
                                             PY_Result& result,
                                             bool include_details,
                                             UT_WorkBuffer& errors);

    /// Sets the local dictionary. If the locals object is nullptr, resets the
    /// dictionary to an empty dict
    void                            setLocalDict(PY_PyObject* locals);

    /// Copies the local dict if it has modifications, else returns a nullptr
    PY_PyObject*                    saveLocalDict();

    /// Restores and frees the local dict
    void                            restoreLocalDict(PY_PyObject* locals);

    /// Sets a local dictionary entry by running a script
    void                            setLocalDictEntryByScript(
                                                    const UT_StringHolder& name,
                                                    const char* py_expression);
    /// Sets a local dictionary entry as a PyObject
    void                            setLocalDictEntryByObject(
                                                    const UT_StringHolder& name,
                                                    PY_PyObject* py_obj);

private:
    using EvaluatorMap = UT_StringMap<UT_UniquePtr<PDG_AttributeEvaluator>>;

    PY_PyObject*                    myLocalDict;
    const PDG_WorkItem*             myActiveWorkItem;
    const PDG_Node*                 myActiveNode;
    EvaluatorMap                    myAttributeMap;
    AttribRecordScope*              myAttributeRecord;
    fpreal                          myEvalTime;

    State                           myState;

    bool                            myDictModified : 1;
    bool                            myIsParent : 1;
    bool                            myIsLocalize : 1;
    bool                            myHasParameterError : 1;
};

#endif