leafNodeCache.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_EF_LEAF_NODE_CACHE_H
#define PXR_EXEC_EF_LEAF_NODE_CACHE_H


#include "pxr/pxr.h"

#include "pxr/exec/ef/api.h"
#include "pxr/exec/ef/dependencyCache.h"
#include "pxr/exec/ef/leafNodeIndexer.h"

#include "pxr/base/tf/hashmap.h"
#include "pxr/exec/vdf/maskedOutputVector.h"
#include "pxr/exec/vdf/sparseVectorizedOutputTraverser.h"
#include "pxr/exec/vdf/types.h"

#include <atomic>
#include <vector>

PXR_NAMESPACE_OPEN_SCOPE

class EfLeafNodeCache
{
public:
    EF_API
    EfLeafNodeCache();

    size_t GetVersion() const {
        return _version.load(std::memory_order_relaxed);
    }

    EF_API
    const VdfOutputToMaskMap &FindOutputs(
        const VdfMaskedOutputVector &outputs,
        bool updateIncrementally);

    EF_API
    const std::vector<const VdfNode *> &FindNodes(
        const VdfMaskedOutputVector &outputs,
        bool updateIncrementally);

    EF_API
    const std::vector<const VdfNode *> &FindNodes(
        const VdfMaskedOutputVector &outputs,
        const TfBits &outputsMask);

    EF_API
    void Clear();

    EF_API
    void WillDeleteConnection(const VdfConnection &connection);

    EF_API
    void DidConnect(const VdfConnection &connection);

private:
    // Holds the sets of leaf nodes, one for each output in the request, along
    // with cached, combined sets of leaf nodes given a mask of the requested
    // outputs. The sets contain indices into the leaf node indexer.
    struct _VectorizedCacheEntry {
        std::vector<TfBits> leafNodes;
        TfHashMap<TfBits, TfBits, TfBits::FastHash> combinedLeafNodes;
    };

    // Stores an array of leaf nodes, and outputs connected to these leaf nodes.
    struct _SparseCacheEntry {
        std::vector<const VdfNode *> nodes;
        VdfOutputToMaskMap outputs;
    };

    // Clears the vectorized and sparse caches along with the traverser used to
    // populate those caches, if their internal state has been flagged as being
    // invalid.
    void _ClearCachesIfInvalid();

    // Combine separate sets of leaf nodes into a single set.
    TfBits _CombineLeafNodes(
        const TfBits &outputsMask,
        const std::vector<TfBits> &leafNodes) const;

    // Populates the vectorized cache by doing a vectorized traversal.
    _VectorizedCacheEntry *_PopulateVectorizedEntry(
        const VdfMaskedOutputVector &outputs);

    // Populates the sparse cache by using the results from a previous,
    // vectorized traversal.
    _SparseCacheEntry *_PopulateSparseEntry(
        const VdfMaskedOutputVector &outputs,
        const TfBits &leafNodes);

    // The version of the cache. Incremented with every edit.
    std::atomic<size_t> _version;

    // Indicates that the internal state pertaining to vectorized and sparse
    // caches is invalid and that those caches be cleared.
    std::atomic<bool> _cachesAreInvalid;

    // The dependency cache used for fast lookups of input-to-output
    // dependencies.
    EfDependencyCache _dependencyCache;

    // The leaf node indexer associates each leaf node with a unique index.
    Ef_LeafNodeIndexer _indexer;

    // A cache of requested outputs to leaf node dependencies for each
    // individual output in the request.
    using _VectorizedCache = TfHashMap<
        VdfMaskedOutputVector,
        _VectorizedCacheEntry,
        VdfMaskedOutputVector_Hash>;
    _VectorizedCache _vectorizedCache;

    // A cache of requested outputs to leaf nodes and leaf node connected
    // outputs.
    using _SparseCache = TfHashMap<
        VdfMaskedOutputVector,
        _SparseCacheEntry,
        VdfMaskedOutputVector_Hash>;
    _SparseCache _sparseCache;

    // The traverser used to populate the vectorized cache.
    VdfSparseVectorizedOutputTraverser _traverser;
};

PXR_NAMESPACE_CLOSE_SCOPE

#endif