TaggedCache.h

#pragma once
 
#include <xrpl/basics/SharedWeakCachePointer.h>
#include <xrpl/basics/SharedWeakCachePointer.ipp>  // IWYU pragma: keep
#include <xrpl/basics/UnorderedContainers.h>
#include <xrpl/basics/hardened_hash.h>
#include <xrpl/beast/clock/abstract_clock.h>
#include <xrpl/beast/insight/Collector.h>
#include <xrpl/beast/insight/Gauge.h>
#include <xrpl/beast/insight/Hook.h>
#include <xrpl/beast/insight/NullCollector.h>
#include <xrpl/beast/utility/Journal.h>
 
#include <atomic>
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <memory>
#include <mutex>
#include <string>
#include <thread>
#include <type_traits>
#include <vector>
 
namespace xrpl {
 
namespace detail {
 
// Replace-policy tags selecting how TaggedCache::canonicalizeImpl resolves a
// collision when the key already exists (defined in TaggedCache.ipp):
//   - ReplaceCached: always replace the cached value with `data`. `data` is
//     never written back and may be const.
//   - ReplaceClient: keep the cached value and write it back into `data` (the
//     client's pointer), which must therefore be writable.
//   - ReplaceDynamically: call the supplied callback to decide per call; `data`
//     is written back when the cached value is kept, so it must be writable.
struct ReplaceCached;
struct ReplaceClient;
struct ReplaceDynamically;
 
}  // namespace detail

template <
    class Key,
    class T,
    bool IsKeyCache = false,
    class SharedWeakUnionPointerType = SharedWeakCachePointer<T>,
    class SharedPointerType = std::shared_ptr<T>,
    class Hash = HardenedHash<>,
    class KeyEqual = std::equal_to<Key>,
    class Mutex = std::recursive_mutex>
class TaggedCache
{
public:
    using mutex_type = Mutex;
    using key_type = Key;
    using mapped_type = T;
    using clock_type = beast::AbstractClock<std::chrono::steady_clock>;
    using shared_weak_combo_pointer_type = SharedWeakUnionPointerType;
    using shared_pointer_type = SharedPointerType;
 
public:
    TaggedCache(
        std::string const& name,
        int size,
        clock_type::duration expiration,
        clock_type& clock,
        beast::Journal journal,
        beast::insight::Collector::ptr const& collector = beast::insight::NullCollector::make());
 
public:
    clock_type&
    clock();

    std::size_t
    size() const;
 
    int
    getCacheSize() const;
 
    int
    getTrackSize() const;
 
    float
    getHitRate();
 
    void
    clear();
 
    void
    reset();

    template <class KeyComparable>
    bool
    touchIfExists(KeyComparable const& key);
 
    using SweptPointersVector = std::vector<SharedWeakUnionPointerType>;
 
    void
    sweep();
 
    bool
    del(key_type const& key, bool valid);
 
private:
    // Selects the `data` parameter type of canonicalizeImpl from the replace
    // policy: const for detail::ReplaceCached (never written back), otherwise
    // writable.
    template <typename Policy>
    using CanonicalizeClientPointerType = std::conditional_t<
        std::is_same_v<detail::ReplaceCached, Policy>,
        SharedPointerType const&,
        SharedPointerType&>;

    template <class Policy, class Callback = std::nullptr_t>
    bool
    canonicalizeImpl(
        key_type const& key,
        CanonicalizeClientPointerType<Policy> data,
        Policy policy,
        Callback&& replaceCallback = nullptr);
 
public:
    template <class Callback>
    bool
    canonicalize(key_type const& key, SharedPointerType& data, Callback&& replaceCallback);

    bool
    canonicalizeReplaceCache(key_type const& key, SharedPointerType const& data);

    bool
    canonicalizeReplaceClient(key_type const& key, SharedPointerType& data);
 
    SharedPointerType
    fetch(key_type const& key);

    template <class ReturnType = bool>
    auto
    insert(key_type const& key, T const& value) -> ReturnType
        requires(!IsKeyCache);
 
    template <class ReturnType = bool>
    auto
    insert(key_type const& key) -> ReturnType
        requires IsKeyCache;
 
    // VFALCO NOTE It looks like this returns a copy of the data in
    //             the output parameter 'data'. This could be expensive.
    //             Perhaps it should work like standard containers, which
    //             simply return an iterator.
    //
    bool
    retrieve(key_type const& key, T& data);
 
    mutex_type&
    peekMutex();
 
    std::vector<key_type>
    getKeys() const;
 
    // CachedSLEs functions.
    double
    rate() const;

    template <class Handler>
    SharedPointerType
    fetch(key_type const& digest, Handler const& h);
    // End CachedSLEs functions.
 
private:
    SharedPointerType
    initialFetch(key_type const& key, std::scoped_lock<mutex_type> const& l);
 
    void
    collectMetrics();
 
private:
    struct Stats
    {
        template <class Handler>
        Stats(
            std::string const& prefix,
            Handler const& handler,
            beast::insight::Collector::ptr const& collector)
            : hook(collector->makeHook(handler))
            , size(collector->makeGauge(prefix, "size"))
            , hitRate(collector->makeGauge(prefix, "hit_rate"))
 
        {
        }
 
        beast::insight::Hook hook;
        beast::insight::Gauge size;
        beast::insight::Gauge hitRate;
 
        std::size_t hits{0};
        std::size_t misses{0};
    };
 
    class KeyOnlyEntry
    {
    public:
        clock_type::time_point lastAccess;
 
        explicit KeyOnlyEntry(clock_type::time_point const& lastAccess) : lastAccess(lastAccess)
        {
        }
 
        void
        touch(clock_type::time_point const& now)
        {
            lastAccess = now;
        }
    };
 
    class ValueEntry
    {
    public:
        shared_weak_combo_pointer_type ptr;
        clock_type::time_point lastAccess;
 
        ValueEntry(clock_type::time_point const& lastAccess, shared_pointer_type const& ptr)
            : ptr(ptr), lastAccess(lastAccess)
        {
        }
 
        [[nodiscard]] bool
        isWeak() const
        {
            if (!ptr)
                return true;
            return ptr.isWeak();
        }
        [[nodiscard]] bool
        isCached() const
        {
            return ptr && ptr.isStrong();
        }
        [[nodiscard]] bool
        isExpired() const
        {
            return ptr.expired();
        }
        SharedPointerType
        lock()
        {
            return ptr.lock();
        }
        void
        touch(clock_type::time_point const& now)
        {
            lastAccess = now;
        }
    };
 
    using Entry = std::conditional_t<IsKeyCache, KeyOnlyEntry, ValueEntry>;
 
    using KeyOnlyCacheType = hardened_partitioned_hash_map<key_type, KeyOnlyEntry, Hash, KeyEqual>;
 
    using KeyValueCacheType = hardened_partitioned_hash_map<key_type, ValueEntry, Hash, KeyEqual>;
 
    using cache_type = hardened_partitioned_hash_map<key_type, Entry, Hash, KeyEqual>;
 
    [[nodiscard]] std::thread
    sweepHelper(
        clock_type::time_point const& whenExpire,
        [[maybe_unused]] clock_type::time_point const& now,
        KeyValueCacheType::map_type& partition,
        SweptPointersVector& stuffToSweep,
        std::atomic<int>& allRemovals,
        std::scoped_lock<std::recursive_mutex> const&);
 
    [[nodiscard]] std::thread
    sweepHelper(
        clock_type::time_point const& whenExpire,
        clock_type::time_point const& now,
        KeyOnlyCacheType::map_type& partition,
        SweptPointersVector&,
        std::atomic<int>& allRemovals,
        std::scoped_lock<std::recursive_mutex> const&);
 
    beast::Journal journal_;
    clock_type& clock_;
    Stats stats_;
 
    mutex_type mutable mutex_;
 
    // Used for logging
    std::string name_;
 
    // Desired number of cache entries (0 = ignore)
    int const targetSize_;
 
    // Desired maximum cache age
    clock_type::duration const targetAge_;
 
    // Number of items cached
    int cacheCount_{0};
    cache_type cache_;  // Hold strong reference to recent objects
    std::uint64_t hits_{0};
    std::uint64_t misses_{0};
};
 
}  // namespace xrpl