pageCacheStorage.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_PAGE_CACHE_STORAGE_H
#define PXR_EXEC_EF_PAGE_CACHE_STORAGE_H


#include "pxr/pxr.h"

#include "pxr/exec/ef/api.h"
#include "pxr/exec/ef/pageCache.h"
#include "pxr/exec/ef/pageCacheCommitRequest.h"

#include "pxr/exec/vdf/lruCache.h"
#include "pxr/exec/vdf/request.h"
#include "pxr/exec/vdf/types.h"

#include <tbb/concurrent_vector.h>

#include <atomic>
#include <functional>
#include <memory>
#include <vector>

PXR_NAMESPACE_OPEN_SCOPE

class EfLeafNodeCache;
class VdfExecutorInterface;
class VdfMask;
class VdfMaskedOutput;

class EfPageCacheStorage
{
    // The executor needs direct access to the page cache
    template <template <typename> class E, typename D>
    friend class EfPageCacheBasedExecutor;

    // The cache commit request needs direct access to the page cache
    friend class EfPageCacheCommitRequest;

    // Predicate type used for invalidation. The predicate returns
    // \c true if the page indexed by the specified key value shall
    // receive invalidation.
    using _CacheIteratorPredicateFunction =
        std::function<bool (const VdfVector &)>;

public:
    EF_API
    ~EfPageCacheStorage();

    template < typename T >
    static EfPageCacheStorage *New(
        const VdfMaskedOutput &keyMaskedOutput,
        EfLeafNodeCache *leafNodeCache);

    EF_API
    static size_t GetNumBytesUsed();

    EF_API
    static size_t GetNumBytesLimit();

    EF_API
    static bool HasReachedMemoryLimit();

    EF_API
    static void SetMemoryUsageLimit(size_t bytes);

    EF_API
    bool IsEnabled() const;

    EF_API
    void SetEnabled(bool enable);

    EF_API
    const VdfRequest &GetCacheableRequest(const VdfRequest &request) const;

    EF_API
    bool GetCachedKeys(
        const _CacheIteratorPredicateFunction &predicate,
        const VdfRequest &request,
        std::vector<const VdfVector *> *cachedKeys) const;

    EF_API
    void Invalidate(
        const _CacheIteratorPredicateFunction &predicate);

    EF_API
    void Invalidate(
        const _CacheIteratorPredicateFunction &predicate,
        const VdfMaskedOutputVector &invalidationRequest);

    EF_API
    void Clear();

    EF_API
    void ClearNodes(
        const VdfNetwork &network,
        const tbb::concurrent_vector<VdfIndex> &nodes);

    EF_API
    void Resize(const VdfNetwork &network);

    EF_API
    void WillDeleteNode(const VdfNode &node);

private:
    // Constructor
    EF_API
    EfPageCacheStorage(
        const VdfMaskedOutput &keyMaskedOutput,
        EfLeafNodeCache *leafNodeCache,
        Ef_PageCache *newPageCache);

    // Returns \c true of the given \p output is a key output.
    EF_API
    bool _IsKeyOutput(
        const VdfOutput &output,
        const VdfMask &mask) const;

    // Returns a pointer to an existing, or newly created cache at the
    // page indexed by \p key.
    EF_API
    Ef_OutputValueCache *_GetOrCreateCache(const VdfVector &key);

    // Returns a set of all outputs dependent on the specified request.
    EF_API
    const VdfOutputToMaskMap &_FindDependencies(
        const VdfMaskedOutputVector &request) const;

    // Commits data to an output value cache, returning the size of the
    // committed data, in bytes.
    EF_API
    size_t _Commit(
        const VdfExecutorInterface &executor,
        const VdfRequest &request,
        Ef_OutputValueCache::ExclusiveAccess *cacheAccess);

    // Commits data for a single output to an output value cache, returning the
    // size of the committed data, in bytes.
    EF_API
    size_t _Commit(
        const VdfMaskedOutput &maskedOutput,
        const VdfVector &value,
        Ef_OutputValueCache::ExclusiveAccess *cacheAccess);

private:
    // The key masked output.
    VdfMaskedOutput _keyMaskedOutput;

    // The leaf node cache.
    EfLeafNodeCache *_leafNodeCache;

    // Pointer to the page cache managed by this class.
    std::unique_ptr<Ef_PageCache> _pageCache;

    // An entry in the cacheableRequests cache. The entry becomes invalid on
    // changes to the leaf node cache, so we store the leaf node cache version
    // along with the cached request.
    struct _CacheableRequestEntry {
        _CacheableRequestEntry() : version(0) {}
        size_t version;
        VdfRequest request;
    };

    // An LRU cache with cacheable requests.
    using _CacheableRequests =
        VdfLRUCache<VdfRequest, _CacheableRequestEntry, VdfRequest::Hash>;
    mutable _CacheableRequests _cacheableRequests;

    // Flags nodes that have had at least one output value stored in at
    // least one page. Once added, node references will not be removed
    // until the node is being deleted from the network. This serves as
    // an acceleration structure, which limits the set of nodes that could
    // possibly have output values stored in the page cache.
    std::unique_ptr<std::atomic<bool>[]> _nodeRefs;
    size_t _numNodeRefs;

    // The number of bytes currently used.
    static std::atomic<size_t> _numBytesUsed;

    // The upper memory limit in bytes.
    static std::atomic<size_t> _numBytesLimit;

    // Is this storage enabled?
    bool _enabled;

};

template < typename T >
EfPageCacheStorage *
EfPageCacheStorage::New(
    const VdfMaskedOutput &keyMaskedOutput,
    EfLeafNodeCache *leafNodeCache)
{
    return new EfPageCacheStorage(
        keyMaskedOutput, leafNodeCache, Ef_PageCache::New<T>());
}

PXR_NAMESPACE_CLOSE_SCOPE

#endif