network.h

Go to the documentation of this file.

//
// Copyright 2025 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_EXEC_VDF_NETWORK_H
#define PXR_EXEC_VDF_NETWORK_H
 
 
#include "pxr/pxr.h"
 
#include "pxr/exec/vdf/api.h"
#include "pxr/exec/vdf/types.h"
 
#include "pxr/base/tf/hash.h"
#include "pxr/base/tf/hashset.h"
#include "pxr/base/tf/smallVector.h"
#include "pxr/base/tf/span.h"
 
#include "tbb/concurrent_queue.h"
#include "tbb/concurrent_unordered_map.h"
#include "tbb/concurrent_vector.h"
 
#include <atomic>
#include <cstdint>
#include <vector>
#include <iosfwd>
#include <memory>
#include <unordered_map>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class TfToken;
 
class VdfConnection;
class VdfInput;
class VdfObjectPtr;
class VdfMask;
class VdfMaskedOutput;
class VdfNode;
class VdfOutput;
class VdfSchedule;
class VdfPoolChainIndex;
class VdfPoolChainIndexer;
class Vdf_ExecNodeDebugName;
class Vdf_InputAndOutputSpecsRegistry;
class Vdf_ScheduleInvalidator;
 
typedef TfHashSet<const VdfOutput *, TfHash> VdfOutputPtrSet;
 
class VdfNetwork
{
public:
 
    static const int AppendConnection = -1;
 
    VDF_API
    VdfNetwork();
 
    VDF_API
    ~VdfNetwork();
 
    VDF_API
    const std::string GetNodeDebugName(const VdfNode *node) const;
 
    uint32_t GetOutputCapacity() const { 
        return _outputCapacity.load(std::memory_order_acquire);
    }
 
    size_t GetNodeCapacity() const { return _nodes.size(); }
 
    size_t GetNumOwnedNodes() const { 
        return _nodes.size() - _freeNodeIds.unsafe_size();
    }
 
    const VdfNode *GetNode(size_t i) const {
        return i < _nodes.size() ? _nodes[i] : nullptr;
    }
 
    VdfNode *GetNode(size_t i) {
        return i < _nodes.size() ? _nodes[i] : nullptr;
    }
 
    VDF_API
    const VdfNode *GetNodeById(const VdfId nodeId) const;
 
    VDF_API
    VdfNode *GetNodeById(const VdfId nodeId);
 
 
    class VDF_API_TYPE EditMonitor
    {
    public:
        VDF_API
        virtual ~EditMonitor();
 
        virtual void WillClear() = 0;
 
        virtual void DidConnect(const VdfConnection *connection) = 0;
 
        virtual void DidAddNode(const VdfNode *node) = 0;
 
        virtual void WillDelete(const VdfNode *node) = 0;
 
        virtual void WillDelete(const VdfConnection *connection) = 0; 
    };
 
    VDF_API
    void Clear();
 
    VDF_API
    VdfConnection *Connect(
        VdfOutput     *output, 
        VdfNode       *inputNode,
        const TfToken &inputName,
        const VdfMask &mask,
        int            atIndex = AppendConnection);
 
    VDF_API
    VdfConnection *Connect(
        const VdfMaskedOutput &maskedOutput, 
        VdfNode               *inputNode,
        const TfToken         &inputName,
        int                    atIndex = AppendConnection);
 
    VDF_API
    bool Delete(VdfNode *node);
 
    VDF_API
    void Disconnect(VdfConnection *connection);
 
    VDF_API
    bool DisconnectAndDelete(VdfNode *node);
 
    VDF_API
    void ReorderInputConnections(
        VdfInput *input,
        const TfSpan<const VdfConnectionVector::size_type> &newToOldIndices);
 
    VDF_API
    void RegisterEditMonitor(EditMonitor *monitor);
 
    VDF_API
    void UnregisterEditMonitor(EditMonitor *monitor);
 
    size_t GetVersion() const { 
        return _version.load(std::memory_order_acquire);
    }
 
 
 
 
    VDF_API
    size_t DumpStats(std::ostream &os) const;
 
 
 
    VDF_API
    VdfPoolChainIndex GetPoolChainIndex(const VdfOutput &output) const;
 
 
private:
 
    friend class VdfNode;
    friend class VdfIsolatedSubnetwork;
    friend class VdfOutput;
 
    // Registers a name for a given node. 
    // 
    // Only VdfNode should call this function.
    //
    void _RegisterNodeDebugName(
        const VdfNode &node, VdfNodeDebugNameCallback &&callback);
 
    // Unregisters a name for a given node.  
    //
    // Should only be called by VdfNode's destructor.
    //
    void _UnregisterNodeDebugName(const VdfNode &node);
 
    // Adds a node to this network.
    //
    // Returns the index of node that was added.  Once a node is added to the
    // network, the network takes ownership.  Only VdfNode should call
    // this function.
    //
    void _AddNode(VdfNode *node);
 
    // Delete a node helper.
    //
    void _DeleteNode(VdfNode *node);
 
    // Removes the connection from the network, but does not delete it. Sends
    // out the deletion notification, as well as invalidates any structures
    // dependent on the connection state.
    //
    void _RemoveConnection(VdfConnection *connection);
 
    // Delete a connection helper function. Note that this method won't 
    // send out deletion notification.
    //
    void _DeleteConnection(VdfConnection *connection);
 
    // Removes \p node from the network, but doesn't delete it.  Uses \p monitor
    // to notify about any reindexing.
    //
    void _RemoveNode(VdfNode *node);
 
    // Informs the network that the affects mask for \p output has changed.
    //
    void _DidChangeAffectsMask(VdfOutput &output);
    
    // Returns an output id for a newly created output to use.
    //
    size_t _AcquireOutputId();
 
    // Releases an output id for use by a future output.
    //
    void _ReleaseOutputId(const VdfId id);
 
    // Increment the network edit version.
    //
    void _IncrementVersion();
 
    // \name Schedule Management
    //
    // These are methods that can only be called by VdfSchedule to register
    // an unregister itself from a network.  
    //
    // These methods are thread-safe and can safely be called from 
    // within execution.  This is needed for clients that schedule during
    // execution (e.g. speculation).
    //
    // @{
 
    friend class VdfSchedule;
    
    // Sets that a schedule is referencing this network.
    // 
    void _RegisterSchedule(VdfSchedule *schedule) const;
 
    // Clears the schedule from the list of schedules referencing this network.
    //
    void _UnregisterSchedule(VdfSchedule *schedule) const;
 
    // Returns a pointer to the schedule invalidator.
    //
    Vdf_ScheduleInvalidator* _GetScheduleInvalidator() const {
        return _scheduleInvalidator.get();
    }
 
    // @}
 
    // Returns the input/output specs registry for this network.
    //
    Vdf_InputAndOutputSpecsRegistry &_GetInputOutputSpecsRegistry() {
        return *_specsRegistry;
    }
 
    // The complete list of nodes managed by this network.
    tbb::concurrent_vector<VdfNode *> _nodes;
 
    // A queue of ids that are free to be assigned to new nodes.
    tbb::concurrent_queue<VdfId> _freeNodeIds;
 
    // The version with which to initialize new nodes
    VdfVersion _initialNodeVersion;
 
    // The number of output indices in this network.
    std::atomic<uint32_t> _outputCapacity;
 
    // The free output indices in the network.
    tbb::concurrent_queue<VdfId> _freeOutputIds;
 
    // The list of static edit monitors registered with this network.
    using _EditMonitorVector = TfSmallVector<EditMonitor *, 1>;
    _EditMonitorVector _monitors;
 
    // Helper class for invalidating schedules after topological changes.
    std::unique_ptr<Vdf_ScheduleInvalidator> _scheduleInvalidator;
 
    // Pool Chain Indexer
    std::unique_ptr<VdfPoolChainIndexer> _poolChainIndexer;
 
    // Input and output specs registry.
    std::unique_ptr<Vdf_InputAndOutputSpecsRegistry> _specsRegistry;
 
    // Edit version.
    std::atomic<size_t> _version;
 
    // Map from node to debug name.
    using _NodeDebugNamesMap = tbb::concurrent_unordered_map<
        VdfIndex,
        std::unique_ptr<Vdf_ExecNodeDebugName>, 
        TfHash>;
 
    _NodeDebugNamesMap _nodeDebugNames;
};
 
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif