xrpld
Loading...
Searching...
No Matches
TaggedCache.h
1#pragma once
2
3#include <xrpl/basics/SharedWeakCachePointer.h>
4#include <xrpl/basics/SharedWeakCachePointer.ipp> // IWYU pragma: keep
5#include <xrpl/basics/UnorderedContainers.h>
6#include <xrpl/basics/hardened_hash.h>
7#include <xrpl/beast/clock/abstract_clock.h>
8#include <xrpl/beast/insight/Collector.h>
9#include <xrpl/beast/insight/Gauge.h>
10#include <xrpl/beast/insight/Hook.h>
11#include <xrpl/beast/insight/NullCollector.h>
12#include <xrpl/beast/utility/Journal.h>
13
14#include <atomic>
15#include <chrono>
16#include <cstddef>
17#include <cstdint>
18#include <functional>
19#include <memory>
20#include <mutex>
21#include <string>
22#include <thread>
23#include <type_traits>
24#include <vector>
25
26namespace xrpl {
27
28namespace detail {
29
30// Replace-policy tags selecting how TaggedCache::canonicalizeImpl resolves a
31// collision when the key already exists (defined in TaggedCache.ipp):
32// - ReplaceCached: always replace the cached value with `data`. `data` is
33// never written back and may be const.
34// - ReplaceClient: keep the cached value and write it back into `data` (the
35// client's pointer), which must therefore be writable.
36// - ReplaceDynamically: call the supplied callback to decide per call; `data`
37// is written back when the cached value is kept, so it must be writable.
38struct ReplaceCached;
39struct ReplaceClient;
40struct ReplaceDynamically;
41
42} // namespace detail
43
57template <
58 class Key,
59 class T,
60 bool IsKeyCache = false,
61 class SharedWeakUnionPointerType = SharedWeakCachePointer<T>,
62 class SharedPointer = std::shared_ptr<T>,
63 class Hash = HardenedHash<>,
64 class KeyEqual = std::equal_to<Key>,
65 class Mutex = std::recursive_mutex>
67{
68public:
69 using MutexType = Mutex;
70 using key_type = Key;
71 using mapped_type = T;
73 using SharedWeakComboPointerType = SharedWeakUnionPointerType;
74 using SharedPointerType = SharedPointer;
75
76public:
78 std::string const& name,
79 int size,
80 ClockType::duration expiration,
82 beast::Journal journal,
84
85public:
91
96 size() const;
97
98 int
99 getCacheSize() const;
100
101 int
103
104 float
106
107 void
109
110 void
112
124 template <class KeyComparable>
125 bool
126 touchIfExists(KeyComparable const& key);
127
129
130 void
132
133 bool
134 del(key_type const& key, bool valid);
135
136private:
137 // Selects the `data` parameter type of canonicalizeImpl from the replace
138 // policy: const for detail::ReplaceCached (never written back), otherwise
139 // writable.
140 template <typename Policy>
143 SharedPointerType const&,
145
155 template <class Policy, class Callback = std::nullptr_t>
156 bool
158 key_type const& key,
160 Policy policy,
161 Callback&& replaceCallback = nullptr);
162
172 template <class Policy, class Callback = std::nullptr_t>
173 bool
176 key_type const& key,
178 Policy policy,
179 Callback&& replaceCallback = nullptr);
180
181public:
202 template <class Callback>
203 bool
204 canonicalize(key_type const& key, SharedPointerType& data, Callback&& replaceCallback);
205
220 bool
222
238 bool
240
242 fetch(key_type const& key);
243
249 template <class ReturnType = bool>
250 auto
251 insert(key_type const& key, T const& value) -> ReturnType
252 requires(!IsKeyCache);
253
265 template <class ReturnType = bool>
266 auto
267 insert(key_type const& key) -> ReturnType
268 requires IsKeyCache;
269
270 // VFALCO NOTE It looks like this returns a copy of the data in
271 // the output parameter 'data'. This could be expensive.
272 // Perhaps it should work like standard containers, which
273 // simply return an iterator.
274 //
275 bool
276 retrieve(key_type const& key, T& data);
277
279 getKeys() const;
280
281 // CachedSLEs functions.
285 double
286 rate() const;
287
294 template <class Handler>
296 fetch(key_type const& digest, Handler const& h);
297 // End CachedSLEs functions.
298
311 template <class Callback>
312 void
313 fetchAndModify(key_type const& key, Callback&& callback);
314
315private:
318
319 void
321
322private:
323 struct Stats
324 {
325 template <class Handler>
327 std::string const& prefix,
328 Handler const& handler,
329 beast::insight::Collector::Ptr const& collector)
330 : hook(collector->makeHook(handler))
331 , size(collector->makeGauge(prefix, "size"))
332 , hitRate(collector->makeGauge(prefix, "hit_rate"))
333
334 {
335 }
336
340 };
341
343 {
344 public:
346
350
351 void
353 {
354 lastAccess = now;
355 }
356 };
357
359 {
360 public:
363
368
369 [[nodiscard]] bool
370 isWeak() const
371 {
372 if (!ptr)
373 return true;
374 return ptr.isWeak();
375 }
376 [[nodiscard]] bool
377 isCached() const
378 {
379 return ptr && ptr.isStrong();
380 }
381 [[nodiscard]] bool
382 isExpired() const
383 {
384 return ptr.expired();
385 }
388 {
389 return ptr.lock();
390 }
391 void
393 {
394 lastAccess = now;
395 }
396 };
397
399
401
403
405
406 [[nodiscard]] std::thread
408 ClockType::time_point const& whenExpire,
409 [[maybe_unused]] ClockType::time_point const& now,
411 SweptPointersVector& stuffToSweep,
412 std::atomic<int>& allRemovals,
414
429 [[nodiscard]] std::thread
431 ClockType::time_point const& whenExpire,
432 ClockType::time_point const& now,
433 KeyOnlyCacheType::MapType& partition,
435 std::atomic<int>& allRemovals,
437
440 Stats stats_;
441
443
444 // Used for logging
446
447 // Desired number of cache entries (0 = ignore)
448 int const targetSize_;
449
450 // Desired maximum cache age
452
453 // Number of items cached
455 CacheType cache_; // Hold strong reference to recent objects
458};
459
460} // namespace xrpl
Abstract interface to a clock.
std::chrono::steady_clock::duration duration
std::chrono::steady_clock::time_point time_point
A generic endpoint for log messages.
Definition Journal.h:44
std::shared_ptr< Collector > Ptr
Definition Collector.h:29
A metric for measuring an integral value.
Definition Gauge.h:21
A reference to a handler for performing polled collection.
Definition Hook.h:14
static std::shared_ptr< Collector > make()
Seed functor once per construction.
std::unordered_map< key_type, mapped_type, hasher, key_equal, allocator_type > MapType
A combination of a std::shared_ptr and a std::weak_pointer.
ClockType::time_point lastAccess
void touch(ClockType::time_point const &now)
KeyOnlyEntry(ClockType::time_point const &lastAccess)
SharedWeakComboPointerType ptr
void touch(ClockType::time_point const &now)
ValueEntry(ClockType::time_point const &lastAccess, SharedPointerType const &ptr)
ClockType::time_point lastAccess
SharedPointerType lock()
SharedPointerType fetch(key_type const &key)
std::thread sweepHelper(ClockType::time_point const &whenExpire, ClockType::time_point const &now, KeyValueCacheType::MapType &partition, SweptPointersVector &stuffToSweep, std::atomic< int > &allRemovals, std::scoped_lock< std::recursive_mutex > const &)
bool canonicalizeReplaceClient(key_type const &key, SharedPointerType &data)
Insert the canonical entry for key, keeping any existing cached value.
SharedPointerType initialFetch(key_type const &key, std::scoped_lock< MutexType > const &l)
bool canonicalize(key_type const &key, SharedPointerType &data, Callback &&replaceCallback)
Replace aliased objects with originals.
int getTrackSize() const
bool canonicalizeImpl(key_type const &key, CanonicalizeClientPointerType< Policy > data, Policy policy, Callback &&replaceCallback=nullptr)
Shared implementation of the canonicalize family.
beast::AbstractClock< std::chrono::steady_clock > ClockType
Definition TaggedCache.h:72
bool retrieve(key_type const &key, T &data)
bool touchIfExists(KeyComparable const &key)
Refresh the last access time on a key if present.
bool canonicalizeImpl(std::scoped_lock< MutexType > const &, key_type const &key, CanonicalizeClientPointerType< Policy > data, Policy policy, Callback &&replaceCallback=nullptr)
canonicalizeImpl variant for callers that already hold mutex_.
bool del(key_type const &key, bool valid)
HardenedPartitionedHashMap< key_type, Entry, HardenedHash<>, std::equal_to< UInt256 > > CacheType
std::conditional_t< IsKeyCache, KeyOnlyEntry, ValueEntry > Entry
double rate() const
Returns the fraction of cache hits.
std::thread sweepHelper(ClockType::time_point const &whenExpire, ClockType::time_point const &now, KeyOnlyCacheType::MapType &partition, SweptPointersVector &, std::atomic< int > &allRemovals, std::scoped_lock< std::recursive_mutex > const &)
Sweep one partition of a key-only cache on its own thread.
auto insert(key_type const &key, T const &value) -> ReturnType requires(!IsKeyCache)
Insert the element into the container.
std::vector< key_type > getKeys() const
std::shared_ptr< int > SharedPointerType
Definition TaggedCache.h:74
HardenedPartitionedHashMap< key_type, KeyOnlyEntry, HardenedHash<>, std::equal_to< UInt256 > > KeyOnlyCacheType
HardenedPartitionedHashMap< key_type, ValueEntry, HardenedHash<>, std::equal_to< UInt256 > > KeyValueCacheType
TaggedCache(std::string const &name, int size, ClockType::duration expiration, ClockType &clock, beast::Journal journal, beast::insight::Collector::Ptr const &collector=beast::insight::NullCollector::make())
auto insert(key_type const &key) -> ReturnType
Insert a key into a key-only cache.
bool canonicalizeReplaceCache(key_type const &key, SharedPointerType const &data)
Insert/update the canonical entry for key, always replacing the cached value with data.
SharedWeakCachePointer< int > SharedWeakComboPointerType
Definition TaggedCache.h:73
std::conditional_t< std::is_same_v< detail::ReplaceCached, Policy >, SharedPointerType const &, SharedPointerType & > CanonicalizeClientPointerType
ClockType::duration const targetAge_
int getCacheSize() const
SharedPointerType fetch(key_type const &digest, Handler const &h)
Fetch an item from the cache.
void fetchAndModify(key_type const &key, Callback &&callback)
Fetch or create an entry and execute a callback while holding the lock.
std::vector< SharedWeakCachePointer< int > > SweptPointersVector
T is_same_v
TER valid(STTx const &tx, ReadView const &view, AccountID const &src, beast::Journal j)
Use hash_* containers for keys that do not need a cryptographically secure hashing algorithm.
Definition algorithm.h:5
static Hasher::result_type digest(void const *data, std::size_t size) noexcept
Definition tokens.cpp:140
PartitionedUnorderedMap< Key, Value, Hash, Pred, Allocator > HardenedPartitionedHashMap
beast::insight::Gauge size
beast::insight::Gauge hitRate
beast::insight::Hook hook
Stats(std::string const &prefix, Handler const &handler, beast::insight::Collector::Ptr const &collector)