executorInterface.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_EXECUTOR_API_H
#define PXR_EXEC_VDF_EXECUTOR_API_H
 
 
#include "pxr/pxr.h"
 
#include "pxr/exec/vdf/api.h"
#include "pxr/exec/vdf/maskedOutputVector.h"
#include "pxr/exec/vdf/types.h"
 
#include "pxr/base/tf/hashset.h"
 
#include <atomic>
#include <memory>
#include <mutex>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class VdfMask;
class VdfNetwork;
class VdfOutput;
class VdfRequest;
class VdfSchedule;
class VdfVector;
class VdfExecutionStats;
class VdfExecutorErrorLogger;
class VdfExecutorFactoryBase;
class VdfExecutorInvalidator;
class VdfExecutorObserver;
 
 
class VDF_API_TYPE VdfExecutorInterface
{
public:
    VdfExecutorInterface(const VdfExecutorInterface &) = delete;
    VdfExecutorInterface &operator=(const VdfExecutorInterface &) = delete;
 
    VDF_API
    virtual ~VdfExecutorInterface();
 
 
    VDF_API
    void Run(
        const VdfSchedule &schedule, 
        VdfExecutorErrorLogger *errorLogger = NULL);
 
    VDF_API
    void Run(
        const VdfSchedule &schedule,
        const VdfRequest &computeRequest,
        VdfExecutorErrorLogger *errorLogger = NULL);
 
 
 
 
    virtual const VdfExecutorFactoryBase &GetFactory() const = 0; 
 
 
 
 
    VDF_API
    void RegisterObserver(const VdfExecutorObserver *observer) const;
 
    VDF_API
    void UnregisterObserver(const VdfExecutorObserver *observer) const;
 
 
 
 
    virtual void Resize(const VdfNetwork &network) {}
 
    virtual void SetOutputValue(
        const VdfOutput &output,
        const VdfVector &value,
        const VdfMask &mask) = 0;
 
    virtual bool TakeOutputValue(
        const VdfOutput &output,
        VdfVector *value,
        const VdfMask &mask) = 0;
 
    const VdfVector *GetOutputValue(
        const VdfOutput &output,
        const VdfMask &mask) const {
        return _GetOutputValueForReading(output, mask);
    }
 
    virtual void DuplicateOutputData(
        const VdfOutput &sourceOutput,
        const VdfOutput &destOutput) = 0;
 
 
 
 
    const VdfExecutorInterface *GetParentExecutor() const {
        return _parentExecutor;
    }
 
    VDF_API
    void SetParentExecutor(const VdfExecutorInterface *parentExecutor);
 
 
 
 
    VDF_API
    void InvalidateValues(
        const VdfMaskedOutputVector &invalidationRequest);
 
    VDF_API
    void InvalidateTopologicalState();
 
    VDF_API
    void ClearData();
 
    VDF_API
    void ClearDataForOutput(const VdfId outputId, const VdfId nodeId);
 
    virtual bool IsEmpty() const = 0;
 
 
 
 
    void IncrementExecutorInvalidationTimestamp() {
        ++_executorInvalidationTimestamp;
    }
 
    void InheritExecutorInvalidationTimestamp(const VdfExecutorInterface &executor) {
        _executorInvalidationTimestamp = 
            executor.GetExecutorInvalidationTimestamp();
    }
 
    VdfInvalidationTimestamp GetExecutorInvalidationTimestamp() const {
        return _executorInvalidationTimestamp;
    }
 
    virtual bool HasInvalidationTimestampMismatch(
        const VdfOutput &source, 
        const VdfOutput &dest) const = 0;
 
 
 
 
    void SetInterruptionFlag(const std::atomic_bool *interruptionFlag) {
        _interruptionFlag = interruptionFlag;
    }
 
    const std::atomic_bool *GetInterruptionFlag() const {
        return _interruptionFlag;
    }
 
    bool HasBeenInterrupted() const {
        return _interruptionFlag && _interruptionFlag->load();
    }
 
 
 
 
    void SetExecutionStats(VdfExecutionStats *stats) {
        _stats = stats;
    }
 
    VdfExecutionStats *GetExecutionStats() const {
        return _stats;
    }
 
 
 
protected:
 
    VDF_API
    VdfExecutorInterface();
 
    VDF_API
    explicit VdfExecutorInterface(const VdfExecutorInterface *parentExecutor);
 
    virtual void _Run(
        const VdfSchedule &schedule,
        const VdfRequest &computeRequest,
        VdfExecutorErrorLogger *errorLogger) = 0;
 
    virtual const VdfVector *_GetInputValue(
        const VdfConnection &connection,
        const VdfMask &mask) const = 0;
 
    virtual const VdfVector *_GetOutputValueForReading(
        const VdfOutput &output,
        const VdfMask &mask) const = 0;
 
    virtual VdfVector *_GetOutputValueForWriting(
        const VdfOutput &output) const = 0;
 
    virtual bool _IsOutputInvalid(
        const VdfId outputId,
        const VdfMask &invalidationMask) const = 0;
 
    virtual bool _InvalidateOutput(
        const VdfOutput &output,
        const VdfMask &invalidationMask) = 0;
 
    virtual bool _PreProcessInvalidation(
        const VdfMaskedOutputVector &invalidationRequest,
        VdfMaskedOutputVector *processedRequest) {
        return false;
    }
 
    virtual void _UpdateInvalidationTimestamp() = 0;
 
    VDF_API
    virtual void _ClearData();
 
    VDF_API
    virtual void _ClearDataForOutput(const VdfId outputId, const VdfId nodeId);
 
    virtual void _SetReferenceOutputValue(
        const VdfOutput &destOutput,
        const VdfOutput &sourceOutput,
        const VdfMask &sourceMask) const = 0;
 
    virtual void _TouchOutput(const VdfOutput &output) const = 0;
 
private:
 
    // VdfContext needs access to _SetReferenceOutputValue,
    // _GetOutputValueForReading, _GetOutputValueForWriting and _LogWarning.
    friend class VdfContext;
 
    // VdfIterator needs friend access to _GetInputValue,
    // _GetOutputValueForReading and _GetOutputValueForWriting.
    friend class VdfIterator;
 
    // VdfSpeculationNode needs friend access to _GetOutputValueForWriting.
    friend class VdfSpeculationNode;
 
    // These classes need access to _TouchOutput.
    template<template <typename> class E, class D>
    friend class VdfSpeculationExecutor;
    template<class T> friend class VdfSpeculationExecutorEngine;
    template<class T> friend class VdfPullBasedExecutorEngine;
    template<class T> friend class VdfParallelSpeculationExecutorEngine;
 
    // VdfExecutorInvalidator needs access to _InvalidateOutput.
    friend class VdfExecutorInvalidator;
 
    // The optional invalidator, responsible for invalidating output state
    // and temporary buffers for outputs and their dependent outputs.
    std::unique_ptr<VdfExecutorInvalidator> _invalidator;
 
    // Optional, externally provided (i.e. not owned by the executor) object
    // to keep track of execution statistics.
    VdfExecutionStats *_stats;
 
    // Keeps track of the VdfExecutorObservers registered with this executor
    typedef TfHashSet<const VdfExecutorObserver *, TfHash> _Observers;
    mutable _Observers _observers;
 
    // Access to the _observers set can happen from multiple threads.  The
    // scenario where this happens is when background execution is interrupted
    // with sharing enabled.  Interuption iterates over the _observers lists in
    // order to notify.  That notification causes sharing node to release
    // sub-executors via a worker thread.  That also does unregister from the
    // _observers set while the main thread is still using the set to interrupt.
    mutable std::recursive_mutex _observersLock;   
 
    // The executor stores its own invalidation timestamp.
    // This timestamp will be applied to the data manager upon
    // invalidating values.
    VdfInvalidationTimestamp _executorInvalidationTimestamp;
 
    // Optional parent executor.
    const VdfExecutorInterface *_parentExecutor;
 
    // Interruption flag
    const std::atomic_bool *_interruptionFlag;
 
};
 
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif