PDG_Graph.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_GRAPH_H__
#define __PDG_GRAPH_H__

#include "PDG_API.h"

#include "PDG_AttributeOwner.h"
#include "PDG_AttributeTypes.h"
#include "PDG_NodeTypes.h"
#include "PDG_RegisteredType.h"
#include "PDG_WorkItemDirty.h"

#include <UT/UT_ArrayMap.h>
#include <UT/UT_ArrayStringMap.h>
#include <UT/UT_ConcurrentHashMap.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringMap.h>
#include <UT/UT_RWLock.h>

class PDG_EvaluationContext;
class PDG_GraphContext;
struct PDG_MemoryInfo;
class PDG_NodeInterface;
class PDG_Node;
class PDG_NodeCallbackType;
class PDG_Port;
class PDG_WorkItem;
class PDG_WorkItemDirty;

class UT_WorkBuffer;

class PDG_API PDG_Graph : public PDG_AttributeOwner
{
public:
    /// Nodes not created by TOPs will have id = nodeIdBase + counter
    static constexpr PDG_NodeID nodeIdBase = 1000000;

    /// Typedef for work item id -> work item
    using IdMap     = UT_ConcurrentHashMap<PDG_WorkItemID, PDG_WorkItem*>;

public:
                            PDG_Graph(PDG_GraphContext* context);
                            ~PDG_Graph() override;

    /// Returns the total memory usage of the graph, and all the nodes and
    /// work items in it
    int64                   getMemoryUsage(bool inclusive) const;

    /// Returns the total memory usage of the graph, and all the nodes and
    /// work items in it.
    void                    memoryInfo(PDG_MemoryInfo& memory_info,
                                       bool inclusive) const;

    /// Returns a descriptive name of the attribute owner
    UT_StringHolder         attribOwnerName() const override;

    /// Checks if the specified flag is valid for this owner
    bool                    isAttribFlagValid(
                                PDG_AttributeFlag flag) const override;

    /// Checks if the specified bit vector flags is valid for this owner
    bool                    areAttribFlagsValid(uint16 flags) const override;

    /// Returns a human-readable description of the nodes in the graph
    void                    description(UT_WorkBuffer& buffer) const;

    /// Serializes the nodes to Python, which can then be used to rebuild the
    /// graph at a later point
    void                    serialize(UT_WorkBuffer& buffer) const;

    /// Constructs a new PDG node with a given node callbakc type, name and
    /// extra args
    PDG_Node*               createNode(PDG_NodeCallbackType* type_object,
                                       const UT_StringHolder& node_name,
                                       const PDGT_ValueArgs& args,
                                       UT_WorkBuffer& errors,
                                       PDG_NodeID id = -1);

    /// Adds an existing node to the graph 
    void                    insertNode(PDG_NodePtr& node);

    /// Renames a node given i's current/old node name. Does not update any
    /// external references to the node name
    bool                    renameNode(
                                    const UT_StringHolder& old_name,
                                    const UT_StringHolder& new_name);

    /// Renames a node give its ID. Does not update any external references
    /// tot he node name
    bool                    renameNodeById(
                                    PDG_NodeID node_id,
                                    const UT_StringHolder& new_name);

    /// Remove node/nodes from the graph
    PDG_NodePtr             removeNode(const UT_StringHolder& node_name);
    PDG_NodePtr             removeNodeById(PDG_NodeID node_id);
    void                    removeAllNodes();

    /// Notifies nodes that a scheduler has been removed
    void                    removeScheduler(PDG_Scheduler* scheduler);

    /// Accessors for nodes in the graph
    PDG_Node*               node(const UT_StringHolder& name) const;
    PDG_Node*               nodeById(PDG_NodeID id) const;
    int                     nodeCount() const
                                { return myNodeNameMap.size(); }
    const PDG_NodePtrMap&   nodes() const
                                { return myNodeNameMap; }

    /// Returns a unqiue name for a node by adding a numeric suffix until a
    /// name is found that isn't already in use
    UT_StringHolder         uniqueNodeName(const UT_StringHolder& name);

    /// Looks up a port using the node.port_name syntax
    PDG_Port*               nodePort(const UT_StringHolder& node_name,
                                     const UT_StringHolder& port_name) const;
    PDG_Port*               nodePort(const UT_StringHolder& full_name) const;

    /// Adds/ removes or queries external dependencies
    PDG_DependencyPtr       dependencyForKey(const UT_StringHolder& key) const;
    PDG_DependencyPtr       addDependency(const UT_StringHolder& type, 
                                          const UT_StringHolder& key,
                                          const PDGT_ValueArgs& args,
                                          UT_WorkBuffer& errors);
    void                    addDependency(PDG_DependencyPtr dependency);
    void                    removeDependency(PDG_DependencyPtr dependency);

    /// Returns the graph contex that owns this graph
    PDG_GraphContext*       context() const;

    
    /// Adds a work item to the work item id -> pointer map
    void                    addWorkItem(PDG_WorkItem* work_item);

    /// Removes a work item from the graph
    void                    removeWorkItem(PDG_WorkItem* work_item);


    /// Returns a work item for a given id
    PDG_WorkItem*           workItemById(PDG_WorkItemID id) const;

    /// Returns a work item for a given id. Iterates through all active
    static PDG_WorkItem*    workItemByGlobalId(PDG_WorkItemID id);

    /// Returns a list of work items for a given list of ids
    void                    workItemsById(
                                PDG_WorkItemArray& work_items,
                                const UT_ValArray<PDG_WorkItemID>& ids,
                                bool allow_null) const;

    /// Returns a work item for a given name
    PDG_WorkItem*           workItemByName(const UT_StringHolder& name) const;

    /// Returns a work item id from a name, assuming the name is using the
    /// node_id compatibility format
    PDG_WorkItemID          workItemIdFromName(const UT_StringHolder& name) const;

    /// Returns an array of work item IDs currently in the graph
    void                    workItemIds(PDG_WorkItemIDArray& ids) const;

    /// Returns the map of work item ids -> work item
    IdMap                   workItemIdMap() const   { return myWorkItemIdMap; }

    /// Returns a map of item->dependencies, item->dependents and ready items
    void                    dependencyGraph(
                                    PDG_WorkItemMap& dependencies,
                                    PDG_WorkItemMap& dependents,
                                    PDG_WorkItemArray& ready,
                                    bool expand,
                                    PDG_Scheduler* filter) const;

    /// Returns a static dependency graph as a map of work item -> dependencies
    /// If "inverse" is true, returns the dependent map instead
    void                    dependencyGraph(
                                    PDG_WorkItemMap& graph,
                                    bool inverse,
                                    bool expand,
                                    PDG_Scheduler* filter) const;

    /// Dirties all work items in the graph, faster than the standard dirty
    /// methods as it can simply blow away everything
    PDG_WorkItemDirty       dirtyAll(
                                bool remove_outputs,
                                bool apply_dirty) const;

    /// Dirties a work item by id
    ///
    /// Note that this method acquires the serial cook write lock, preventing
    /// any other code from accessing/generating static or dirtying work items
    PDG_WorkItemDirty       dirtyWorkItem(
                                PDG_WorkItemID id,
                                bool should_delete,
                                bool remove_outputs,
                                bool apply_dirty) const;

    /// Dirties a work item by pointer
    ///
    /// Note that this method acquires the serial cook write lock, preventing
    /// any other code from accessing/generating static or dirtying work items
    PDG_WorkItemDirty       dirtyWorkItem(
                                PDG_WorkItem* work_item,
                                bool should_delete,
                                bool remove_outputs,
                                bool apply_dirty) const;

    /// Dirities an array of work items
    ///
    /// Note that this method acquires the serial cook write lock, preventing
    /// any other code from accessing/generating static or dirtying work items
    PDG_WorkItemDirty       dirtyWorkItems(
                                const PDG_WorkItemArray& work_items,
                                PDG_Node* source_node,
                                bool should_delete,
                                bool remove_outputs,
                                bool apply_dirty,
                                bool emit_events) const;
    PDG_WorkItemDirty       dirtyWorkItems(
                                const PDG_WorkItemPtrArray& work_items,
                                PDG_Node* source_node,
                                bool should_delete,
                                bool remove_outputs,
                                bool apply_dirty,
                                bool emit_events) const;

    /// Dirities an array of work items, using the existing dirty state
    /// object.
    ///
    /// Note that this method acquires the serial cook write lock, preventing
    /// any other code from accessing/generating static or dirtying work items
    void                    dirtyWorkItems(
                                const PDG_WorkItemArray& work_items,
                                PDG_WorkItemDirty* dirty_state) const;
    void                    dirtyWorkItems(
                                const PDG_WorkItemPtrArray& work_items,
                                PDG_WorkItemDirty* dirty_state) const;

    /// Does a numeric data lookup, for use with the @ operator
    PDG_AttributeCast       numericData(
                                fpreal& param,
                                exint& query_index,
                                const PDG_AttributeEvaluator& evaluator) const;

    /// Does a string data lookup, for use with the @ operator
    PDG_AttributeCast       stringData(
                                UT_WorkBuffer& buffer,
                                exint& query_index,
                                const PDG_AttributeEvaluator& evaluator,
                                const PDG_EvaluationContext* local_context) const;

    /// Binds a global attribute to a specific work item
    void                    bindGlobalAttribute(
                                const UT_StringHolder& attrib_name,
                                PDG_WorkItem* work_item);

    /// Returns the work iterm that an attribute is bound to
    PDG_WorkItem*           boundAttributeWorkItem(
                                const UT_StringHolder& attrib_name) const;

    /// Adjusts the unique id counter so the specified ID is included in the
    /// range of used values.
    static void             addUniqueId(PDG_WorkItemID id);

    /// Returns a new unique work item id
    static PDG_WorkItemID   uniqueWorkItemId();

    /// Returns the current maximum unique work item id
    static PDG_WorkItemID   currentWorkItemId();

    /// Returns a new unique cache id
    PDG_CacheID             uniqueCacheId();

    /// Returns a new unique node id
    PDG_NodeID              uniqueNodeId();

    /// Increments the graph's cache id.
    void                    bumpCacheId();

    /// Returns the serial cook RW lock. This is only so that PDG_Node is able
    /// to use the lock to guard access to its static items, wrappers and done
    /// item lists.
    UT_RWLock&              serialCookLock()
                                { return mySerialCookLock; }

    /// Runs a functor on the specified node with the node lock held.
    template <typename Func>
    void                    safeNodeAccess(PDG_NodeID id, const Func& f) const
                                {
                                    UT_AutoReadLock nodes_lock(myNodesLock);
                                    auto it = myNodeIdMap.find(id);
                                    if (it != myNodeIdMap.end())
                                        f(it->second);
                                }

    /// Runs a functor on the node map with the node lock held.
    template <typename Func>
    void                    safeNodeMapAccess(const Func& f) const
                                {
                                    UT_AutoReadLock nodes_lock(myNodesLock);
                                    f(myNodeNameMap);
                                }

    /// Runs a functor on the specified work item with an ID map iterator
    /// held.
    template <typename Func>
    void                    safeWorkItemAccess(PDG_WorkItemID id,
                                               const Func& f) const
                                {
                                    IdMap::accessor access;
                                    if (myWorkItemIdMap.find(access, id))
                                        f(access->second);
                                }

private:
    friend class PDG_WorkItemDirty;

    /// Typedef for exteranl dependency map
    using DepMap                = UT_StringMap<PDG_DependencyPtr>;

    /// Typedef for node id -> node
    using NodeIdMap             = UT_ArrayMap<PDG_NodeID, PDG_Node*>;

    /// Map of work item ID to global attributes bound to that work item
    using GlobalAttribMap       = UT_ArrayMap<PDG_WorkItemID, UT_StringArray>;

    /// Inverse map for global attributes, mapping attribute name to work
    /// item ID
    using GlobalAttribInvMap    = UT_ArrayStringMap<PDG_WorkItem*>;

    void                    applyDirty(bool remove_outputs);

private:
    PDG_NodePtrMap          myNodeNameMap;
    NodeIdMap               myNodeIdMap;
    IdMap                   myWorkItemIdMap;

    GlobalAttribMap         myGlobalAttribMap;
    GlobalAttribInvMap      myGlobalAttribInvMap;

    SYS_AtomicCounter       myNodeIdCounter;
    PDG_CacheID             myCacheIdCounter;

    DepMap                  myDependencies;
    PDG_GraphContext*       myContext;

    mutable UT_RWLock       myNodesLock;
    mutable UT_RWLock       mySerialCookLock;
};

#endif /* __PDG_GRAPH_H__ */