Stroika Library 3.0d24
 
Loading...
Searching...
No Matches
TimedCache.inl
1/*
2 * Copyright(c) Sophist Solutions, Inc. 1990-2026. All rights reserved
3 */
4#include "Stroika/Foundation/Containers/Mapping.h"
5#include "Stroika/Foundation/Debug/Assertions.h"
6#include "Stroika/Foundation/Debug/Trace.h"
7#include "Stroika/Foundation/Execution/Common.h"
8
9namespace Stroika::Foundation::Cache {
10
11 /*
12 ********************************************************************************
13 ************************* TimedCache<KEY,VALUE,TRAITS> *************************
14 ********************************************************************************
15 */
16 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
17 template <typename K>
18 inline auto TimedCache<KEY, VALUE, TRAITS>::MyResult_::MakeCacheElement (const K& key) const -> CacheElement
19 {
20 if constexpr (kTrackExpiration) {
21 if constexpr (same_as<void, VALUE>) {
22 return CacheElement{.fKey = key, .fExpiresAt = fExpiresAt};
23 }
24 else {
25 return CacheElement{.fKey = key, .fValue = fResult, .fExpiresAt = fExpiresAt};
26 }
27 }
28 else if constexpr (kTrackFreshness) {
29 if constexpr (same_as<void, VALUE>) {
30 return CacheElement{.fKey = key, .fLastRefreshedAt = fLastRefreshedAt};
31 }
32 else {
33 return CacheElement{.fKey = key, .fValue = fResult, .fLastRefreshedAt = fLastRefreshedAt};
34 }
35 }
36 }
37
38 /*
39 ********************************************************************************
40 ************************* TimedCache<KEY,VALUE,TRAITS> *************************
41 ********************************************************************************
42 */
43 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
44 TimedCache<KEY, VALUE, TRAITS>::TimedCache ()
45 requires (not is_empty_v<decltype (TRAITS::kDefaultMaxAge)>)
46 {
47 if constexpr (TRAITS::kPerCacheMaxAge) {
48 fMaxAge_ = TRAITS::kDefaultMaxAge;
49 }
50 if constexpr (TRAITS::kAutomaticPurgeFrequency != TimeStampDifferenceType{TimedCacheSupport::kNoAutomaticPurgeSentinal}) {
51 fNextAutoClearAt_ = TRAITS::GetCurrentTimestamp () + TRAITS::kAutomaticPurgeFrequency;
52 }
53 }
54 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
55 TimedCache<KEY, VALUE, TRAITS>::TimedCache (TimeStampDifferenceType maxAge)
56 requires (TRAITS::kPerCacheMaxAge)
57 : fMaxAge_{maxAge}
58 , fNextAutoClearAt_{TRAITS::GetCurrentTimestamp () + TRAITS::kAutomaticPurgeFrequency} // hopefully optimized away if kNoAutomaticPurgeSentinal
59 {
60 Require (fMaxAge_ > 0.0s);
61 }
62 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
63 inline TimedCache<KEY, VALUE, TRAITS>::TimedCache (TimedCache&& src) noexcept
64 : fMaxAge_{src.fMaxAge_}
65 , fNextAutoClearAt_{src.fNextAutoClearAt_}
66 {
67 [[maybe_unused]] auto&& srcLock = scoped_lock{src.fMaybeMutex_};
68 fData_ = move (src.fData_);
69 fStats_ = move (src.fStats_);
70 }
71 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
72 inline TimedCache<KEY, VALUE, TRAITS>::TimedCache (const TimedCache& src)
73 : fMaxAge_{src.fMaxAge_}
74 , fNextAutoClearAt_{src.fNextAutoClearAt_}
75 {
76 [[maybe_unused]] auto&& srcLock = shared_lock{src.fMaybeMutex_};
77 fData_ = src.fData_;
78 fStats_ = src.fStats_;
79 }
80 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
81 inline auto TimedCache<KEY, VALUE, TRAITS>::operator= (TimedCache&& rhs) noexcept -> TimedCache&
82 {
83 [[maybe_unused]] auto&& locks = scoped_lock{rhs.fMaybeMutex_, fMaybeMutex_};
84 fMaxAge_ = rhs.fMaxAge_;
85 fNextAutoClearAt_ = rhs.fNextAutoClearAt_;
86 fData_ = move (rhs.fData_);
87 fStats_ = move (rhs.fStats_);
88 return *this;
89 }
90 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
91 inline auto TimedCache<KEY, VALUE, TRAITS>::operator= (const TimedCache& rhs) -> TimedCache&
92 {
93 [[maybe_unused]] auto&& locks = scoped_lock{rhs.fMaybeMutex_, fMaybeMutex_};
94 fMaxAge_ = rhs.fMaxAge_;
95 fNextAutoClearAt_ = rhs.fNextAutoClearAt_;
96 fData_ = rhs.fData_;
97 fStats_ = rhs.fStats_;
98 return *this;
99 }
100 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
101 inline bool TimedCache<KEY, VALUE, TRAITS>::Expired_ (const MyResult_& r, TimeStampType now) const
102 {
103 qStroika_ATTRIBUTE_INDETERMINATE TimeStampType expiresAt;
104 if constexpr (kTrackExpiration) {
105 expiresAt = r.fExpiresAt;
106 }
107 else if constexpr (kTrackFreshness) {
108 expiresAt = r.fLastRefreshedAt + GetMaxAge_ ();
109 }
110 return now > expiresAt;
111 }
112 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
113 constexpr auto TimedCache<KEY, VALUE, TRAITS>::GetMaxAge_ () const -> TimeStampDifferenceType
114 {
115 if constexpr (TRAITS::kPerCacheMaxAge) {
116 return fMaxAge_;
117 }
118 else {
119 return TRAITS::kDefaultMaxAge;
120 }
121 }
122 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
123 inline auto TimedCache<KEY, VALUE, TRAITS>::GetMaxAge () const -> TimeStampDifferenceType
124 {
125 if constexpr (TRAITS::kPerCacheMaxAge) {
126 shared_lock critSec{fMaybeMutex_};
127 return GetMaxAge_ ();
128 }
129 else {
130 return TRAITS::kDefaultMaxAge;
131 }
132 }
133 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
134 void TimedCache<KEY, VALUE, TRAITS>::SetMaxAge (TimeStampDifferenceType maxAge)
135 requires (TRAITS::kPerCacheMaxAge)
136 {
137 Require (maxAge > 0.0s);
138 scoped_lock critSec{fMaybeMutex_};
139 if (fMaxAge_ != maxAge) {
140 fMaxAge_ = maxAge;
141 ClearExpired_ (); // ClearExpired_ not AutomaticallyClearExpiredDataSometimes_ to force auto-update of fNextAutoClearAt_, and cuz moderately likely items interestingly out of date after adjust of min allowed freshness
142 }
143 }
144 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
145 auto TimedCache<KEY, VALUE, TRAITS>::Elements () const -> Traversal::Iterable<CacheElement>
146 {
147 shared_lock critSec{fMaybeMutex_};
148 vector<CacheElement> r;
149 r.reserve (fData_.size ());
150 TimeStampType now = TRAITS::GetCurrentTimestamp ();
151 for (const auto& i : fData_) {
152 if (not Expired_ (i.second, now)) {
153 r.push_back (i.second.MakeCacheElement (i.first));
154 }
155 }
156 return Traversal::Iterable<CacheElement>{move (r)};
157 }
158 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
159 template <typename K>
160 auto TimedCache<KEY, VALUE, TRAITS>::Keys () const -> Traversal::Iterable<K>
161 requires (IKeyedCache<K>)
162 {
163 vector<KEY> r;
164 shared_lock critSec{fMaybeMutex_};
165 r.reserve (fData_.size ());
166 TimeStampType now = TRAITS::GetCurrentTimestamp ();
167 for (const auto& i : fData_) {
168 if (not Expired_ (i.second, now)) {
169 r.push_back (i.first);
170 }
171 }
172 return Traversal::Iterable<KEY>{move (r)};
173 }
174 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
175 template <typename K, typename V>
176 requires (IKeyedCache<K> and not IValuelessCache<V>)
177 optional<VALUE> TimedCache<KEY, VALUE, TRAITS>::Lookup (typename Common::ArgByValueType<K> key) const
178 {
179 shared_lock critSec{fMaybeMutex_};
180 typename MyMapType_::const_iterator i = fData_.find (key);
181 if (i == fData_.end ()) {
182 fStats_.IncrementMisses ();
183 return nullopt;
184 }
185 else {
186 if (Expired_ (i->second)) {
187 /*
188 * Cannot update fData_ to indicate item expired const constant overload
189 */
190 fStats_.IncrementMisses ();
191 return nullopt;
192 }
193 fStats_.IncrementHits ();
194 return i->second.fResult;
195 }
196 }
197 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
198 template <typename K, typename V>
199 requires (IKeyedCache<K> and not IValuelessCache<V>)
200 optional<VALUE> TimedCache<KEY, VALUE, TRAITS>::Lookup (typename Common::ArgByValueType<K> key)
201 {
202 shared_lock critSec{fMaybeMutex_};
203 typename MyMapType_::iterator i = fData_.find (key);
204 if (i == fData_.end ()) {
205 fStats_.IncrementMisses ();
206 return nullopt;
207 }
208 else {
209 if (Expired_ (i->second)) {
210 /*
211 * since expired, remove from cache
212 */
213 (void)fData_.erase (i);
214 fStats_.IncrementMisses ();
215 return nullopt;
216 }
217 // unclear if we should do this test before or after expired check above???
218 if constexpr (TRAITS::kAutomaticallyMarkDataAsRefreshedEachTimeAccessed) {
219 i->second.fLastRefreshedAt = TRAITS::GetCurrentTimestamp ();
220 }
221 fStats_.IncrementHits ();
222 return i->second.fResult;
223 }
224 }
225 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
226 template <typename K>
227 requires (IKeyedCache<K> and TRAITS::kTrackFreshness)
228 optional<VALUE> TimedCache<KEY, VALUE, TRAITS>::Lookup (typename Common::ArgByValueType<K> key, TimeStampDifferenceType maxAge) const
229 {
230 shared_lock critSec{fMaybeMutex_};
231 typename MyMapType_::const_iterator i = fData_.find (key);
232 TimeStampType now = TRAITS::GetCurrentTimestamp ();
233 if (i == fData_.end ()) {
234 fStats_.IncrementMisses ();
235 return nullopt;
236 }
237 else {
238 if (i->second.fLastRefreshedAt + maxAge <= now) {
239 /*
240 * Cannot update fData_ to indicate item expired const constant overload
241 */
242 fStats_.IncrementMisses ();
243 return nullopt;
244 }
245 fStats_.IncrementHits ();
246 return i->second.fResult;
247 }
248 }
249 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
250 template <typename K>
251 requires (not IKeyedCache<K>)
252 optional<VALUE> TimedCache<KEY, VALUE, TRAITS>::Lookup () const
253 {
254 shared_lock critSec{fMaybeMutex_};
255 if (optional<VALUE> ov = fData_) {
256 if (Expired_ (*ov)) {
257 /*
258 * Cannot update fData_ to indicate item expired const constant overload
259 */
260 fStats_.IncrementMisses ();
261 return nullopt;
262 }
263 fStats_.IncrementHits ();
264 return ov->fResult;
265 }
266 return nullopt;
267 }
268 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
269 template <typename K>
270 requires (not IKeyedCache<K>)
271 optional<VALUE> TimedCache<KEY, VALUE, TRAITS>::Lookup ()
272 {
273 scoped_lock critSec{fMaybeMutex_};
274 if (optional<VALUE> ov = fData_) {
275 if (Expired_ (*ov)) {
276 /*
277 * since expired, remove from cache
278 */
279 fData_ = nullopt;
280 fStats_.IncrementMisses ();
281 return nullopt;
282 }
283 fStats_.IncrementHits ();
284 return ov->fResult;
285 }
286 return nullopt;
287 }
288 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
289 template <typename K>
290 requires (not IKeyedCache<K> and TRAITS::kTrackFreshness)
291 inline optional<VALUE> TimedCache<KEY, VALUE, TRAITS>::Lookup (TimeStampDifferenceType maxAge) const
292 {
293 if (optional<MyResult_> ov = fData_) {
294 TimeStampType now = TRAITS::GetCurrentTimestamp ();
295 if (ov->fLastRefreshedAt + maxAge <= now) {
296 /*
297 * Cannot update fData_ to indicate item expired const constant overload
298 */
299 fStats_.IncrementMisses ();
300 return nullopt;
301 }
302 fStats_.IncrementHits ();
303 return ov->fResult;
304 }
305 return nullopt;
306 }
307 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
308 template <typename K, typename V>
309 requires (IKeyedCache<K> and IValuelessCache<V>)
310 optional<KEY> TimedCache<KEY, VALUE, TRAITS>::Lookup (typename Common::ArgByValueType<K> key) const
311 {
312 shared_lock critSec{fMaybeMutex_};
313 typename MyMapType_::const_iterator i = fData_.find (key);
314 if (i == fData_.end ()) {
315 fStats_.IncrementMisses ();
316 return nullopt;
317 }
318 else {
319 if (Expired_ (i->second)) {
320 /*
321 * Cannot update fData_ to indicate item expired const constant overload
322 */
323 fStats_.IncrementMisses ();
324 return nullopt;
325 }
326 fStats_.IncrementHits ();
327 // return the STORED key object, which could contain more fields/data than the argument KEY
328 return i->first;
329 }
330 }
331 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
332 template <typename K>
333 auto TimedCache<KEY, VALUE, TRAITS>::LookupDetails (typename Common::ArgByValueType<K> key) const -> optional<tuple<VALUE, TimeStampType>>
334 requires (kTrackExpiration and IKeyedCache<K>)
335 {
336 shared_lock critSec{fMaybeMutex_};
337 typename MyMapType_::const_iterator i = fData_.find (key);
338 if (i == fData_.end ()) {
339 fStats_.IncrementMisses ();
340 return nullopt;
341 }
342 else {
343 if (Expired_ (i->second)) {
344 /*
345 * Cannot update fData_ to indicate item expired const constant overload
346 */
347 fStats_.IncrementMisses ();
348 return nullopt;
349 }
350 fStats_.IncrementHits ();
351 return make_tuple (i->second.fResult, i->second.fExpiresAt);
352 }
353 }
354 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
355 template <typename K>
356 auto TimedCache<KEY, VALUE, TRAITS>::LookupDetails (typename Common::ArgByValueType<K> key) -> optional<tuple<VALUE, TimeStampType>>
357 requires (kTrackExpiration and IKeyedCache<K>)
358 {
359 shared_lock critSec{fMaybeMutex_};
360 typename MyMapType_::iterator i = fData_.find (key);
361 if (i == fData_.end ()) {
362 fStats_.IncrementMisses ();
363 return nullopt;
364 }
365 else {
366 if (Expired_ (i->second)) {
367 /*
368 * since expired, remove from cache
369 */
370 (void)fData_.erase (i);
371 fStats_.IncrementMisses ();
372 return nullopt;
373 }
374 fStats_.IncrementHits ();
375 return make_tuple (i->second.fResult, i->second.fExpiresAt);
376 }
377 }
378 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
379 template <typename K>
380 auto TimedCache<KEY, VALUE, TRAITS>::LookupDetails (typename Common::ArgByValueType<K> key) const -> optional<tuple<VALUE, TimeStampType>>
381 requires (kTrackFreshness and IKeyedCache<K>)
382 {
383 shared_lock critSec{fMaybeMutex_};
384 typename MyMapType_::const_iterator i = fData_.find (key);
385 if (i == fData_.end ()) {
386 fStats_.IncrementMisses ();
387 return nullopt;
388 }
389 else {
390 if (Expired_ (i->second)) {
391 /*
392 * Cannot update fData_ to indicate item expired const constant overload
393 */
394 fStats_.IncrementMisses ();
395 return nullopt;
396 }
397 fStats_.IncrementHits ();
398 return make_tuple (i->second.fResult, i->second.fLastRefreshedAt);
399 }
400 }
401 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
402 template <typename K>
403 inline auto TimedCache<KEY, VALUE, TRAITS>::LookupDetails (typename Common::ArgByValueType<K> key) -> optional<tuple<VALUE, TimeStampType>>
404 requires (kTrackFreshness and IKeyedCache<K>)
405 {
406 shared_lock critSec{fMaybeMutex_};
407 typename MyMapType_::iterator i = fData_.find (key);
408 if (i == fData_.end ()) {
409 fStats_.IncrementMisses ();
410 return nullopt;
411 }
412 else {
413 if (Expired_ (i->second)) {
414 /*
415 * since expired, remove from cache
416 */
417 (void)fData_.erase (i);
418 fStats_.IncrementMisses ();
419 return nullopt;
420 }
421 // unclear if we should do this test before or after expired check above???
422 if constexpr (TRAITS::kAutomaticallyMarkDataAsRefreshedEachTimeAccessed) {
423 i->second.fLastRefreshedAt = TRAITS::GetCurrentTimestamp ();
424 }
425 fStats_.IncrementHits ();
426 return make_tuple (i->second.fResult, i->second.fLastRefreshedAt);
427 }
428 }
429 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
430 template <typename K>
431 auto TimedCache<KEY, VALUE, TRAITS>::LookupDetails (typename Common::ArgByValueType<K> key, TimeStampDifferenceType maxAge) const
432 -> optional<tuple<VALUE, TimeStampType>>
433 requires (kTrackFreshness and IKeyedCache<K>)
434 {
435 shared_lock critSec{fMaybeMutex_};
436 typename MyMapType_::const_iterator i = fData_.find (key);
437 TimeStampType now = TRAITS::GetCurrentTimestamp ();
438 if (i == fData_.end ()) {
439 fStats_.IncrementMisses ();
440 return nullopt;
441 }
442 else {
443 if (i->second.fLastRefreshedAt + maxAge <= now) {
444 /*
445 * Cannot update fData_ to indicate item expired const constant overload
446 */
447 fStats_.IncrementMisses ();
448 return nullopt;
449 }
450 fStats_.IncrementHits ();
451 return make_tuple (i->second.fResult, i->second.fLastRefreshedAt);
452 }
453 }
454 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
455 template <typename K>
456 auto TimedCache<KEY, VALUE, TRAITS>::LookupDetails (TimeStampDifferenceType maxAge) const -> optional<tuple<VALUE, TimeStampType>>
457 requires (not IKeyedCache<K>)
458 {
459 AssertNotImplemented (); // but easy
460 return nullopt;
461 }
462 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
463 template <typename K, typename V>
464 requires (IKeyedCache<K> and IValuelessCache<V>)
465 auto TimedCache<KEY, VALUE, TRAITS>::LookupDetails (typename Common::ArgByValueType<K> key) const -> optional<tuple<KEY, TimeStampType>>
466 {
467 static_assert (not IKeyedCache<KEY>); // cuz cannot be both unkeyed and valueless
468 shared_lock critSec{fMaybeMutex_};
469 typename MyMapType_::const_iterator i = fData_.find (key);
470 if (i == fData_.end ()) {
471 fStats_.IncrementMisses ();
472 return nullopt;
473 }
474 else {
475 if (Expired_ (i->second)) {
476 /*
477 * Cannot update fData_ to indicate item expired const constant overload
478 */
479 fStats_.IncrementMisses ();
480 return nullopt;
481 }
482 fStats_.IncrementHits ();
483 // return the STORED key object, which could contain more fields/data than the argument KEY
484 return i->first;
485 }
486 }
487 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
488 template <typename K>
489 auto TimedCache<KEY, VALUE, TRAITS>::GetExpiration () const -> optional<TimeStampType>
490 requires (not IKeyedCache<K>)
491 {
492 if (optional<MyResult_> ov = fData_) {
493 if (Expired_ (*ov)) {
494 /*
495 * Cannot update fData_ to indicate item expired const constant overload
496 */
497 fStats_.IncrementMisses ();
498 return nullopt;
499 }
500 fStats_.IncrementHits ();
501 return ov->fResult;
502 }
503 return nullopt;
504 }
505 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
506 template <typename K>
507 auto TimedCache<KEY, VALUE, TRAITS>::GetExpiration (typename Common::ArgByValueType<K> key) const -> optional<TimeStampType>
508 requires (IKeyedCache<K>)
509 {
510 typename MyMapType_::const_iterator i = fData_.find (key);
511 if (i == fData_.end ()) {
512 return nullopt;
513 }
514 if (Expired_ (i->second)) {
515 return nullopt;
516 }
517 if constexpr (kTrackExpiration) {
518 return i->second.fExpiresAt;
519 }
520 else if constexpr (kTrackFreshness) {
521 return i->second.fLastRefreshedAt + GetMaxAge_ ();
522 }
523 }
524 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
525 template <typename K, Common::invocable_r<VALUE, KEY> CACHE_FILLTER_T>
526 requires (IKeyedCache<K>)
527 VALUE TimedCache<KEY, VALUE, TRAITS>::LookupValue (typename Common::ArgByValueType<K> key, CACHE_FILLTER_T&& cacheFiller)
528 {
529 if (optional<VALUE> o = Lookup (key)) {
530 return *o;
531 }
532 else {
533 return LockingLookupValueAdder_ (key, forward<CACHE_FILLTER_T> (cacheFiller));
534 }
535 }
536 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
537 template <typename K, Common::invocable_r<VALUE, KEY> CACHE_FILLTER_T>
538 requires (IKeyedCache<K> and TRAITS::kTrackFreshness)
539 VALUE TimedCache<KEY, VALUE, TRAITS>::LookupValue (typename Common::ArgByValueType<K> key, TimeStampDifferenceType maxAge, CACHE_FILLTER_T&& cacheFiller)
540 {
541 if (optional<VALUE> o = Lookup (key, maxAge)) {
542 return *o;
543 }
544 else {
545 return LockingLookupValueAdder_ (key, forward<CACHE_FILLTER_T> (cacheFiller));
546 }
547 }
548 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
549 template <typename K, Common::invocable_r<VALUE> CACHE_FILLTER_T>
550 requires (not IKeyedCache<K>)
551 VALUE TimedCache<KEY, VALUE, TRAITS>::LookupValue (CACHE_FILLTER_T&& cacheFiller)
552 {
553 if (optional<VALUE> ov = Lookup ()) {
554 return *ov;
555 }
556 else {
557 return LockingLookupValueAdder_ (forward<CACHE_FILLTER_T> (cacheFiller));
558 }
559 }
560 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
561 template <typename K, Common::invocable_r<VALUE> CACHE_FILLTER_T>
562 requires (not IKeyedCache<K> and TRAITS::kTrackFreshness)
563 VALUE TimedCache<KEY, VALUE, TRAITS>::LookupValue (TimeStampDifferenceType maxAge, CACHE_FILLTER_T&& cacheFiller)
564 {
565 if (optional<VALUE> ov = Lookup (maxAge)) {
566 return *ov;
567 }
568 else {
569 return LockingLookupValueAdder_ (forward<CACHE_FILLTER_T> (cacheFiller));
570 }
571 }
572 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
573 template <typename K, typename V, Common::invocable_r<K, K> CACHE_FILLTER_T>
574 requires (IKeyedCache<K> and IValuelessCache<V>)
575 KEY TimedCache<KEY, VALUE, TRAITS>::LookupValue (typename Common::ArgByValueType<K> key, CACHE_FILLTER_T&& cacheFiller)
576 {
577 if (optional<KEY> ok = Lookup (key)) {
578 return *ok;
579 }
580 else {
581 KEY kr = forward<CACHE_FILLTER_T> (cacheFiller) (key);
582 Add (kr);
583 return kr;
584 }
585 }
586 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
587 template <typename K, Common::invocable_r<VALUE> CACHE_FILLTER_T>
588 requires (not IKeyedCache<K>)
589 inline VALUE TimedCache<KEY, VALUE, TRAITS>::LockingLookupValueAdder_ (CACHE_FILLTER_T&& cacheFiller)
590 {
591 VALUE r = forward<CACHE_FILLTER_T> (cacheFiller) ();
592 Add (r);
593 return r;
594 }
595 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
596 template <typename K, Common::invocable_r<VALUE, KEY> CACHE_FILLTER_T>
597 requires (IKeyedCache<K>)
598 inline VALUE TimedCache<KEY, VALUE, TRAITS>::LockingLookupValueAdder_ (typename Common::ArgByValueType<K> key, CACHE_FILLTER_T&& cacheFiller)
599 {
600 if constexpr (TRAITS::kHoldWriteLockDuringCacheFill) {
601 scoped_lock critSec{fMaybeMutex_};
602 VALUE v = forward<CACHE_FILLTER_T> (cacheFiller) (key);
603 AutomaticallyClearExpiredDataSometimes_ ();
604 Add_ (key, v);
605 return v;
606 }
607 else {
608 VALUE v = forward<CACHE_FILLTER_T> (cacheFiller) (key);
609 Add (key, v); // public API so will acquire lock
610 return v;
611 }
612 }
613 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
614 template <typename K>
615 requires (IKeyedCache<K> and IValuelessCache<VALUE>)
616 void TimedCache<KEY, VALUE, TRAITS>::Add (typename Common::ArgByValueType<K> key)
617 {
618 scoped_lock critSec{fMaybeMutex_};
619 // nb skip AutomaticallyClearExpiredDataSometimes_ cuz Valueless has no map, and add will just overwrite
620 TimeStampType now = TRAITS::GetCurrentTimestamp ();
621 if constexpr (kTrackExpiration) {
622 Add_ (key, now + GetMaxAge_ ());
623 }
624 else if constexpr (kTrackFreshness) {
625 Add_ (key, now);
626 }
627 }
628 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
629 template <typename K, typename V>
630 requires (IKeyedCache<K> and not IValuelessCache<V>)
631 void TimedCache<KEY, VALUE, TRAITS>::Add (typename Common::ArgByValueType<K> key, typename Common::ArgByValueType<V> result)
632 {
633 scoped_lock critSec{fMaybeMutex_};
634 AutomaticallyClearExpiredDataSometimes_ ();
635 TimeStampType now = TRAITS::GetCurrentTimestamp ();
636 if constexpr (kTrackExpiration) {
637 Add_ (key, result, now + GetMaxAge_ ());
638 }
639 else if constexpr (kTrackFreshness) {
640 Add_ (key, result, now);
641 }
642 }
643 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
644 template <typename K, typename V>
645 requires (IKeyedCache<K> and not IValuelessCache<V> and TRAITS::kTrackFreshness)
646 void TimedCache<KEY, VALUE, TRAITS>::Add (typename Common::ArgByValueType<K> key, typename Common::ArgByValueType<V> result, TimeStampType freshAsOf)
647 {
648 scoped_lock critSec{fMaybeMutex_};
649 AutomaticallyClearExpiredDataSometimes_ ();
650 Add_ (key, result, freshAsOf);
651 }
652 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
653 template <typename K, typename V>
654 requires (IKeyedCache<K> and not IValuelessCache<V> and TRAITS::kTrackExpiration)
655 void TimedCache<KEY, VALUE, TRAITS>::Add (typename Common::ArgByValueType<K> key, typename Common::ArgByValueType<V> result, TimeStampType expiresAt)
656 {
657 scoped_lock critSec{fMaybeMutex_};
658 AutomaticallyClearExpiredDataSometimes_ ();
659 Add_ (key, result, expiresAt);
660 }
661 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
662 template <typename K, typename V>
663 requires (not IKeyedCache<K> and not IValuelessCache<V>)
664 inline void TimedCache<KEY, VALUE, TRAITS>::Add (typename Common::ArgByValueType<V> result)
665 {
666 TimeStampType now = TRAITS::GetCurrentTimestamp ();
667 if constexpr (kTrackExpiration) {
668 Add (result, now + GetMaxAge_ ());
669 }
670 else if constexpr (kTrackFreshness) {
671 Add (result, now);
672 }
673 }
674 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
675 template <typename K, typename V>
676 requires (not IKeyedCache<K> and not IValuelessCache<V> and TRAITS::kTrackFreshness)
677 inline void TimedCache<KEY, VALUE, TRAITS>::Add (typename Common::ArgByValueType<V> result, TimeStampType freshAsOf)
678 {
679 scoped_lock critSec{fMaybeMutex_};
680 // no AutomaticallyClearExpiredDataSometimes_ for not keyed cache
681 Add_ (result, freshAsOf);
682 }
683 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
684 template <typename K, typename V>
685 requires (not IKeyedCache<K> and not IValuelessCache<V> and TRAITS::kTrackExpiration)
686 inline void TimedCache<KEY, VALUE, TRAITS>::Add (typename Common::ArgByValueType<V> result, TimeStampType expiresAt)
687 {
688 scoped_lock critSec{fMaybeMutex_};
689 AutomaticallyClearExpiredDataSometimes_ ();
690 Add_ (result, expiresAt);
691 }
692 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
693 template <typename K>
694 requires (IKeyedCache<K> and IValuelessCache<VALUE> and TRAITS::kTrackExpiration)
695 inline void TimedCache<KEY, VALUE, TRAITS>::Add_ (typename Common::ArgByValueType<K> key, TimeStampType expiresAt)
696 {
697 fData_.insert_or_assign (key, MyResult_{.fExpiresAt = expiresAt});
698 }
699 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
700 template <typename K>
701 requires (IKeyedCache<K> and IValuelessCache<VALUE> and TRAITS::kTrackFreshness)
702 inline void TimedCache<KEY, VALUE, TRAITS>::Add_ (typename Common::ArgByValueType<K> key, TimeStampType freshAsOf)
703 {
704 fData_.insert_or_assign (key, MyResult_{.fLastRefreshedAt = freshAsOf});
705 }
706 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
707 template <typename K, typename V>
708 requires (IKeyedCache<K> and not IValuelessCache<V> and TRAITS::kTrackFreshness)
709 inline void TimedCache<KEY, VALUE, TRAITS>::Add_ (typename Common::ArgByValueType<K> key, typename Common::ArgByValueType<V> result, TimeStampType freshAsOf)
710 {
711 fData_.insert_or_assign (key, MyResult_{.fResult = result, .fLastRefreshedAt = freshAsOf});
712 }
713 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
714 template <typename K, typename V>
715 requires (IKeyedCache<K> and not IValuelessCache<V> and TRAITS::kTrackExpiration)
716 inline void TimedCache<KEY, VALUE, TRAITS>::Add_ (typename Common::ArgByValueType<K> key, typename Common::ArgByValueType<V> result, TimeStampType expiresAt)
717 {
718 fData_.insert_or_assign (key, MyResult_{.fResult = result, .fExpiresAt = expiresAt});
719 }
720 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
721 template <typename K, typename V>
722 requires (not IKeyedCache<K> and not IValuelessCache<V> and TRAITS::kTrackFreshness)
723 inline void TimedCache<KEY, VALUE, TRAITS>::Add_ (typename Common::ArgByValueType<V> result, TimeStampType freshAsOf)
724 {
725 fData_ = MyResult_{.fResult = result, .fLastRefreshedAt = freshAsOf};
726 }
727 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
728 template <typename K, typename V>
729 requires (not IKeyedCache<K> and not IValuelessCache<V> and TRAITS::kTrackExpiration)
730 inline void TimedCache<KEY, VALUE, TRAITS>::Add_ (typename Common::ArgByValueType<V> result, TimeStampType expiresAt)
731 {
732 fData_ = MyResult_{.fResult = result, .fExpiresAt = expiresAt};
733 }
734 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
735 template <typename K>
736 requires (IKeyedCache<K>)
737 inline void TimedCache<KEY, VALUE, TRAITS>::Remove (typename Common::ArgByValueType<K> key)
738 {
739 scoped_lock critSec{fMaybeMutex_};
740 fData_.erase (key);
741 AutomaticallyClearExpiredDataSometimes_ ();
742 }
743 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
744 template <qCompilerAndStdLib_ConstraintDiffersInTemplateRedeclaration_BWA (predicate<typename TimedCache<KEY, VALUE, TRAITS>::CacheElement>) PREDICATE>
745 void TimedCache<KEY, VALUE, TRAITS>::RemoveAll (PREDICATE&& p)
746 {
747 scoped_lock critSec{fMaybeMutex_};
748 for (auto i = fData_.begin (); i != fData_.end ();) {
749 if (p (i->second.MakeCacheElement (i->first))) {
750 i = fData_.erase (i);
751 }
752 else {
753 ++i;
754 }
755 }
756 }
757 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
758 template <Traversal::IIterableOfTo<KEY> ITERABLE_OF_KEY_TYPE>
759 void TimedCache<KEY, VALUE, TRAITS>::RetainAll (const ITERABLE_OF_KEY_TYPE& items)
760 {
761 scoped_lock critSec{fMaybeMutex_};
762 // quickie inefficient implementation
763 Containers::Mapping<KEY, MyResult_> tmp{this->fData_};
764 tmp.RetainAll (items);
765 fData_ = tmp.template As<MyMapType_> ();
766 }
767 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
768 inline void TimedCache<KEY, VALUE, TRAITS>::clear ()
769 {
770 scoped_lock critSec{fMaybeMutex_};
771 fData_.clear ();
772 }
773 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
774 inline void TimedCache<KEY, VALUE, TRAITS>::ClearExpiredData ()
775 {
776 scoped_lock critSec{fMaybeMutex_};
777 ClearExpired_ ();
778 }
779 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
780 inline void TimedCache<KEY, VALUE, TRAITS>::ClearExpiredData (TimeStampDifferenceType maxAge)
781 requires (TRAITS::kTrackFreshness)
782 {
783 scoped_lock critSec{fMaybeMutex_};
784 ClearExpired_ (maxAge);
785 }
786 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
787 inline typename TRAITS::StatsType TimedCache<KEY, VALUE, TRAITS>::GetStats () const
788 {
789 return fStats_;
790 }
791 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
792 inline void TimedCache<KEY, VALUE, TRAITS>::AutomaticallyClearExpiredDataSometimes_ ()
793 requires (IKeyedCache<KEY>)
794 {
795 if constexpr (TRAITS::kAutomaticPurgeFrequency != TimeStampDifferenceType{TimedCacheSupport::kNoAutomaticPurgeSentinal}) {
796 if constexpr (TRAITS::kAutomaticPurgeFrequency != TimeStampDifferenceType{TimedCacheSupport::kNoAutomaticPurgeSentinal}) {
797 if (fNextAutoClearAt_ < TRAITS::GetCurrentTimestamp ()) [[unlikely]] {
798 ClearExpired_ ();
799 WeakAssert (fNextAutoClearAt_ > TRAITS::GetCurrentTimestamp ()); // note internally resets fNextAutoClearAt_
800 }
801 }
802 }
803 }
804 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
805 void TimedCache<KEY, VALUE, TRAITS>::ClearExpired_ ()
806 requires (IKeyedCache<KEY>)
807 {
808 TimeStampType now = TRAITS::GetCurrentTimestamp ();
809 for (typename MyMapType_::iterator i = fData_.begin (); i != fData_.end ();) {
810 if (Expired_ (i->second, now)) {
811 i = fData_.erase (i);
812 }
813 else {
814 ++i;
815 }
816 }
817 if constexpr (TRAITS::kAutomaticPurgeFrequency != TimeStampDifferenceType{TimedCacheSupport::kNoAutomaticPurgeSentinal}) {
818 fNextAutoClearAt_ = now + TRAITS::kAutomaticPurgeFrequency;
819 }
820 }
821 template <IKey KEY, IValue VALUE, TimedCacheSupport::ITraits<KEY, VALUE> TRAITS>
822 void TimedCache<KEY, VALUE, TRAITS>::ClearExpired_ (TimeStampDifferenceType maxAge)
823 requires (IKeyedCache<KEY> and TRAITS::kTrackFreshness)
824 {
825 TimeStampType now = TRAITS::GetCurrentTimestamp ();
826 for (typename MyMapType_::iterator i = fData_.begin (); i != fData_.end ();) {
827 if (i->second.fLastRefreshedAt + maxAge <= now) {
828 i = fData_.erase (i);
829 }
830 else {
831 ++i;
832 }
833 }
834 if constexpr (TRAITS::kAutomaticPurgeFrequency != TimeStampDifferenceType{TimedCacheSupport::kNoAutomaticPurgeSentinal}) {
835 fNextAutoClearAt_ = now + TRAITS::kAutomaticPurgeFrequency;
836 }
837 }
838
839 ///////////////////
840 // DEPRECATED APIS
841 ///////////////////
842 template <typename KEY, typename VALUE, typename TIME_TRAITS = TimedCacheSupport::DefaultTraits<KEY, VALUE>>
843 class [[deprecated ("Since Stroika v3.0d23 - TimedCache has the same functionality and mostly the same names")]] CallerStalenessCache
844 : public TimedCache<KEY, VALUE, TimedCacheSupport::DefaultTraits<KEY, VALUE>> {
845 private:
846 using inherited = TimedCache<KEY, VALUE, TimedCacheSupport::DefaultTraits<KEY, VALUE>>;
847
848 public:
849 using TraitsType = typename inherited::TraitsType;
850 using TimeStampType = typename inherited::TimeStampType;
851 using TimeStampDifferenceType = typename inherited::TimeStampDifferenceType;
852
853 public:
854 [[deprecated ("Since Stroika v3.0d23, usually just get rid of call and argument can be used directly in situ")]]
855 static TimeStampType Ago (TimeStampDifferenceType backThisTime)
856 {
857 Require (backThisTime >= 0s);
858 return TraitsType::GetCurrentTimestamp () - backThisTime;
859 }
860 [[deprecated ("Since Stroika v3.0d23, use TraitsType::GetCurrentStamp")]]
861 static TimeStampType GetCurrentTimestamp ()
862 {
863 return TraitsType::GetCurrentTimestamp ();
864 }
865 };
866 template <typename KEY, typename VALUE, typename TIME_TRAITS = TimedCacheSupport::DefaultTraits<KEY, VALUE>>
867 class [[deprecated ("Since Stroika v3.0d23 - TimedCache (or SyncrhonizedTimedCache) has the same functionality and mostly the same "
868 "names")]] SynchronizedCallerStalenessCache
869 : public TimedCache<KEY, VALUE, TimedCacheSupport::InternallySynchronizedTraits<TimedCacheSupport::DefaultTraits<KEY, VALUE>>> {
870 private:
871 using inherited = TimedCache<KEY, VALUE, TimedCacheSupport::InternallySynchronizedTraits<TimedCacheSupport::DefaultTraits<KEY, VALUE>>>;
872
873 public:
874 using TraitsType = typename inherited::TraitsType;
875 using TimeStampType = typename inherited::TimeStampType;
876 using TimeStampDifferenceType = typename inherited::TimeStampDifferenceType;
877
878 public:
879 [[deprecated ("Since Stroika v3.0d23, usually just get rid of call and argument can be used directly in situ")]]
880 static TimeStampType Ago (TimeStampDifferenceType backThisTime)
881 {
882 Require (backThisTime >= 0s);
883 return TraitsType::GetCurrentTimestamp () - backThisTime;
884 }
885 [[deprecated ("Since Stroika v3.0d23, use TraitsType::GetCurrentStamp")]]
886 static TimeStampType GetCurrentTimestamp ()
887 {
888 return TraitsType::GetCurrentTimestamp ();
889 }
890 };
891
892}
AssertNotImplemented
#define AssertNotImplemented()
Definition Assertions.h:402
WeakAssert
#define WeakAssert(c)
A WeakAssert() is for things that aren't guaranteed to be true, but are overwhelmingly likely to be t...
Definition Assertions.h:439
qStroika_ATTRIBUTE_INDETERMINATE
#define qStroika_ATTRIBUTE_INDETERMINATE
qStroika_ATTRIBUTE_INDETERMINATE is used where you would use a C++ attribute for a variable that is i...
Definition StdCompat.h:393
Stroika::Foundation::Cache::TimedCache
Keep track of a bunch of objects, each with an associated time used to allow data to 'expire'.
Definition TimedCache.h:572
Stroika::Foundation::Cache::TimedCache::LookupValue
nonvirtual VALUE LookupValue(typename Common::ArgByValueType< K > key, CACHE_FILLTER_T &&cacheFiller)
Lookup value, and if missing, fetch it with argument cacheFiller (and add/return its value).
Stroika::Foundation::Cache::TimedCache::LookupDetails
nonvirtual optional< tuple< VALUE, TimeStampType > > LookupDetails(typename Common::ArgByValueType< K > key) const
Returns the value associated with argument 'key' (if IKeyedCache), or nullopt, if its missing (missin...
Stroika::Foundation::Cache::TimedCache::GetMaxAge
nonvirtual TimeStampDifferenceType GetMaxAge() const
Definition TimedCache.inl:123
Stroika::Foundation::Cache::TimedCache::Keys
nonvirtual Traversal::Iterable< K > Keys() const
Stroika::Foundation::Cache::TimedCache::SetMaxAge
nonvirtual void SetMaxAge(TimeStampDifferenceType maxAge)
Definition TimedCache.inl:134
Stroika::Foundation::Cache::TimedCache::Elements
nonvirtual Traversal::Iterable< CacheElement > Elements() const
Definition TimedCache.inl:145
Stroika::Foundation::Cache::TimedCache::GetExpiration
nonvirtual optional< TimeStampType > GetExpiration() const
Get the Expiration of object or nullopt of item expired/not in cache.
Stroika::Foundation::Cache::TimedCache::RetainAll
nonvirtual void RetainAll(const ITERABLE_OF_KEY_TYPE &items2Keep)
like Mapping<>::RetainAll () - throw away all elements not in items2Keep
Stroika::Foundation::Cache::TimedCache::Add
nonvirtual void Add(typename Common::ArgByValueType< K > key)
Stroika::Foundation::Traversal::Iterable
Iterable<T> is a base class for containers which easily produce an Iterator<T> to traverse them.
Definition Iterable.h:238
Stroika::Foundation::Cache::TimedCacheSupport::kNoAutomaticPurgeSentinal
constexpr float kNoAutomaticPurgeSentinal
see TimedCache<>::TraitsType::kAutomaticPurgeFrequency - disable automatic purging
Definition TimedCache.h:62
Stroika::Foundation::Cache::IKeyedCache
static constexpr bool IKeyedCache
Does this cache have a KEY type (overwhelming YES, but sometimes handy to have 'singleton' cache,...
Definition Foundation/Cache/Common.h:41
Stroika::Foundation::Common::ArgByValueType
conditional_t<(sizeof(CHECK_T)<=2 *sizeof(void *)) and is_trivially_copyable_v< CHECK_T >, CHECK_T, const CHECK_T & > ArgByValueType
This is an alias for 'T' - but how we want to pass it on stack as formal parameter.
Definition TypeHints.h:36
Stroika::Foundation::Cache::TimedCache::CacheElement
everything here is optional ;-) But typically, its fKey, fValue, fLastRefreshedAt
Definition TimedCache.h:653