refresh_machines 0.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,564 @@
1
+ #![no_std]
2
+ #![doc = include_str!("../README.md")]
3
+ #![cfg_attr(not(test), deny(clippy::indexing_slicing))]
4
+
5
+ use core::time::Duration;
6
+
7
+ use coalesce_machines::Coalescer;
8
+ pub use coalesce_machines::{FlightId, Notification, Outcome, WaiterId};
9
+
10
+ mod decision;
11
+ mod lead;
12
+ mod lease;
13
+ mod policy;
14
+ mod refusal;
15
+
16
+ pub use decision::{Decision, Forgetting, Revalidation};
17
+ pub use lease::Lease;
18
+ pub use policy::{Policy, State};
19
+ pub use refusal::Refusal;
20
+
21
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
22
+ struct Entry {
23
+ key: u64,
24
+ stored_at: Duration,
25
+ age: Duration,
26
+ policy: Policy,
27
+ /// Failed refreshes stay quiet while `now < retry_at`; zero means none.
28
+ retry_at: Duration,
29
+ }
30
+
31
+ impl Entry {
32
+ /// Metadata for a value that arrived at `now`, with no failure backoff.
33
+ const fn new(key: u64, now: Duration, age: Duration, policy: Policy) -> Self {
34
+ Self {
35
+ key,
36
+ stored_at: now,
37
+ age,
38
+ policy,
39
+ retry_at: Duration::ZERO,
40
+ }
41
+ }
42
+
43
+ const fn age_at(&self, now: Duration) -> Duration {
44
+ self.age.saturating_add(now.saturating_sub(self.stored_at))
45
+ }
46
+ }
47
+
48
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
49
+ struct Lead {
50
+ lease: u64,
51
+ key: u64,
52
+ flight: FlightId,
53
+ deadline: Duration,
54
+ }
55
+
56
+ /// Bounded freshness metadata plus one refresh lease per key.
57
+ ///
58
+ /// `KEYS` bounds the keys with stored metadata, `FLIGHTS` the refreshes in
59
+ /// progress, `WAITERS` the callers waiting on a refresh plus notifications
60
+ /// not yet drained.
61
+ ///
62
+ /// The refresher stores no values, fetches nothing and evicts nothing. It
63
+ /// answers whether the value the caller holds may be served, and who refreshes it.
64
+ #[derive(Debug, Clone, PartialEq, Eq)]
65
+ pub struct Refresher<const KEYS: usize, const FLIGHTS: usize, const WAITERS: usize> {
66
+ entries: [Option<Entry>; KEYS],
67
+ leads: [Option<Lead>; FLIGHTS],
68
+ /// Also the one id sequence of this refresher: leases are reserved from
69
+ /// it, between the flight and waiter ids it issues itself.
70
+ flights: Coalescer<FLIGHTS, WAITERS>,
71
+ now: Duration,
72
+ }
73
+
74
+ impl<const KEYS: usize, const FLIGHTS: usize, const WAITERS: usize> Default
75
+ for Refresher<KEYS, FLIGHTS, WAITERS>
76
+ {
77
+ fn default() -> Self {
78
+ Self::new()
79
+ }
80
+ }
81
+
82
+ impl<const KEYS: usize, const FLIGHTS: usize, const WAITERS: usize>
83
+ Refresher<KEYS, FLIGHTS, WAITERS>
84
+ {
85
+ /// Start with no metadata, nothing in flight, at time zero, in scope zero.
86
+ #[must_use]
87
+ pub const fn new() -> Self {
88
+ Self::with_scope(0)
89
+ }
90
+
91
+ /// Start empty at time zero, issuing leases and waiter ids that carry `scope`.
92
+ ///
93
+ /// Leases, waiter ids and flight ids all come from the one sequence of
94
+ /// the coalescer inside: the scope in the top 16 bits, a 48-bit sequence
95
+ /// below. No two ids of a refresher are equal, whatever their kind, so a
96
+ /// lease rebuilt as a waiter id, or the reverse, names nothing. Two
97
+ /// refreshers in the same scope issue the same ids, and an id handed to
98
+ /// the wrong one can name a live lease or waiter there. Give each
99
+ /// refresher, and each coalescer whose ids could meet it, its own scope:
100
+ /// an id from another scope is then always [`Refusal::Stale`]. Keeping
101
+ /// scopes distinct is the caller's job.
102
+ #[must_use]
103
+ pub const fn with_scope(scope: u16) -> Self {
104
+ Self::over(Coalescer::with_scope(scope))
105
+ }
106
+
107
+ /// Start empty at time zero, the id sequence continuing after `issued`.
108
+ ///
109
+ /// For a refresher that replaces an earlier one in the same `scope`, after
110
+ /// a restart: built with [`Self::with_scope`] it would count from one
111
+ /// again, and a lease or waiter id that outlived the restart could name a
112
+ /// new refresh. Save [`Self::issued`] before handing an id out and resume
113
+ /// from it, or give each incarnation a scope of its own. Every id up to
114
+ /// `issued` is then [`Refusal::Stale`]. Metadata and time are not resumed.
115
+ ///
116
+ /// `None` exactly when [`periscope_machines::Issuer::resumed`] answers
117
+ /// `None`: `issued` is beyond [`periscope_machines::SEQUENCE_MAX`].
118
+ #[must_use]
119
+ pub const fn resumed(scope: u16, issued: u64) -> Option<Self> {
120
+ match Coalescer::resumed(scope, issued) {
121
+ Some(flights) => Some(Self::over(flights)),
122
+ None => None,
123
+ }
124
+ }
125
+
126
+ /// The scope carried by every lease and waiter id this refresher issues.
127
+ #[must_use]
128
+ pub const fn scope(&self) -> u16 {
129
+ self.flights.scope()
130
+ }
131
+
132
+ /// How many ids this refresher has issued, of every kind: leases, waiter
133
+ /// ids and flight ids. The count to save for [`Self::resumed`].
134
+ #[must_use]
135
+ pub const fn issued(&self) -> u64 {
136
+ self.flights.issued()
137
+ }
138
+
139
+ /// Decide what a caller asking for `key` at `now` should do.
140
+ ///
141
+ /// A lease issued here must be reported within `lead_for`; after that the
142
+ /// next caller that needs one takes the refresh over and the old lease
143
+ /// goes stale. Callers already waiting keep waiting on the new leader.
144
+ ///
145
+ /// # Errors
146
+ ///
147
+ /// [`Refusal::TimeRegressed`], then [`Refusal::ZeroLead`] for a zero
148
+ /// `lead_for`, and, only when nothing is servable, a full table before a
149
+ /// spent sequence: [`Refusal::FlightsFull`] or [`Refusal::WaitersFull`],
150
+ /// then [`Refusal::Exhausted`]. A new refresh takes two ids, its lease and
151
+ /// its flight, so it is `Exhausted` with one id left; a takeover and a
152
+ /// wait take one. Nothing changes, and no id is consumed.
153
+ pub fn decide(
154
+ &mut self,
155
+ key: u64,
156
+ now: Duration,
157
+ lead_for: Duration,
158
+ ) -> Result<Decision, Refusal> {
159
+ self.check(now)?;
160
+ if lead_for.is_zero() {
161
+ return Err(Refusal::ZeroLead);
162
+ }
163
+ let live = self.lead_of(key).is_some_and(|lead| now < lead.deadline);
164
+ let held = self
165
+ .entry(key)
166
+ .map(|entry| (entry.age_at(now), entry.policy, entry.retry_at));
167
+ let decision = match held {
168
+ Some((age, policy, _)) if policy.state(age) == State::Fresh => Decision::Fresh { age },
169
+ Some((age, policy, retry_at))
170
+ if policy.while_revalidate(age) || (policy.if_error(age) && now < retry_at) =>
171
+ {
172
+ let revalidation = if live {
173
+ Revalidation::InFlight
174
+ } else if now < retry_at {
175
+ Revalidation::Backoff { until: retry_at }
176
+ } else {
177
+ self.lead(key, now, lead_for)
178
+ .map_or_else(Revalidation::Unavailable, Revalidation::Lead)
179
+ };
180
+ Decision::Stale { age, revalidation }
181
+ }
182
+ Some(_) | None if live => {
183
+ let (waiter, flight) = self.follow(key)?;
184
+ Decision::Wait { waiter, flight }
185
+ }
186
+ Some(_) | None => Decision::Fetch {
187
+ lease: self.lead(key, now, lead_for)?,
188
+ },
189
+ };
190
+ self.now = now;
191
+ Ok(decision)
192
+ }
193
+
194
+ /// Report a successful refresh: the value under the lease's key is new.
195
+ ///
196
+ /// `age` is how old the value already was when it arrived (zero when the
197
+ /// origin just produced it). Clears any failure backoff, settles the
198
+ /// refresh and queues a [`Outcome::Completed`] notification per waiter.
199
+ ///
200
+ /// # Errors
201
+ ///
202
+ /// [`Refusal::TimeRegressed`], [`Refusal::Stale`] when the lease is not
203
+ /// live, [`Refusal::EntriesFull`] when the key is new and no metadata slot
204
+ /// is free (the lease stays live: [`Self::forget`] a key and retry, or
205
+ /// [`Self::abandon`]). Nothing changes.
206
+ pub fn store(
207
+ &mut self,
208
+ lease: Lease,
209
+ now: Duration,
210
+ age: Duration,
211
+ policy: Policy,
212
+ ) -> Result<(), Refusal> {
213
+ self.check(now)?;
214
+ let Self {
215
+ entries,
216
+ leads,
217
+ flights,
218
+ ..
219
+ } = self;
220
+ let (lead, slot) = Self::held_in(leads, flights, lease).ok_or(Refusal::Stale)?;
221
+ let home = Self::room_in(entries, lead.key).ok_or(Refusal::EntriesFull)?;
222
+ Self::settle(flights, slot, lead.flight, Outcome::Completed)?;
223
+ *home = Some(Entry::new(lead.key, now, age, policy));
224
+ self.now = now;
225
+ Ok(())
226
+ }
227
+
228
+ /// Report a failed refresh, and learn whether the old value covers for it.
229
+ ///
230
+ /// Returns the age of the held value when its stale-if-error window is
231
+ /// open at `now`, `None` when there is nothing to fall back on. While the
232
+ /// value stays servable, callers are not asked to refresh again until
233
+ /// `retry_after` has passed. Waiters get [`Outcome::Abandoned`] and decide again.
234
+ ///
235
+ /// # Errors
236
+ ///
237
+ /// [`Refusal::TimeRegressed`], or [`Refusal::Stale`] when the lease is not
238
+ /// live. Nothing changes.
239
+ pub fn fail(
240
+ &mut self,
241
+ lease: Lease,
242
+ now: Duration,
243
+ retry_after: Duration,
244
+ ) -> Result<Option<Duration>, Refusal> {
245
+ self.check(now)?;
246
+ let (lead, slot) =
247
+ Self::held_in(&mut self.leads, &self.flights, lease).ok_or(Refusal::Stale)?;
248
+ Self::settle(&mut self.flights, slot, lead.flight, Outcome::Abandoned)?;
249
+ self.now = now;
250
+ let Some(entry) = self
251
+ .entries
252
+ .iter_mut()
253
+ .flatten()
254
+ .find(|entry| entry.key == lead.key)
255
+ else {
256
+ return Ok(None);
257
+ };
258
+ entry.retry_at = now.saturating_add(retry_after);
259
+ let age = entry.age_at(now);
260
+ Ok(entry.policy.if_error(age).then_some(age))
261
+ }
262
+
263
+ /// Give a lease back without an outcome, e.g. the fetch was cancelled.
264
+ ///
265
+ /// No failure is recorded and no backoff starts; the next caller that
266
+ /// needs a refresh leads one. Waiters get [`Outcome::Abandoned`].
267
+ ///
268
+ /// # Errors
269
+ ///
270
+ /// [`Refusal::Stale`] when the lease is not live. Nothing changes.
271
+ pub fn abandon(&mut self, lease: Lease) -> Result<(), Refusal> {
272
+ let (lead, slot) =
273
+ Self::held_in(&mut self.leads, &self.flights, lease).ok_or(Refusal::Stale)?;
274
+ Self::settle(&mut self.flights, slot, lead.flight, Outcome::Abandoned)
275
+ }
276
+
277
+ /// Revoke every lease whose deadline has passed, and return how many.
278
+ ///
279
+ /// [`Self::decide`] already takes an overdue refresh over when a caller
280
+ /// needs one. This is for the keys nobody asks about again: their waiters
281
+ /// get [`Outcome::Abandoned`] instead of waiting forever.
282
+ ///
283
+ /// # Errors
284
+ ///
285
+ /// [`Refusal::TimeRegressed`]. Nothing changes.
286
+ pub fn reap(&mut self, now: Duration) -> Result<usize, Refusal> {
287
+ self.check(now)?;
288
+ self.now = now;
289
+ let mut revoked = 0;
290
+ for slot in &mut self.leads {
291
+ let Some(lead) = slot.filter(|lead| now >= lead.deadline) else {
292
+ continue;
293
+ };
294
+ // A lead whose flight is not in the air stays put rather than
295
+ // vanish uncounted; `settle` flags the broken invariant.
296
+ if Self::settle(&mut self.flights, slot, lead.flight, Outcome::Abandoned).is_ok() {
297
+ // At most one per lead slot, so it cannot pass `FLIGHTS`.
298
+ revoked += 1;
299
+ }
300
+ }
301
+ Ok(revoked)
302
+ }
303
+
304
+ /// Record metadata for a value the caller stored without a lease.
305
+ ///
306
+ /// Replaces any metadata for `key` and clears its failure backoff. A
307
+ /// refresh in flight for the key is untouched; its report lands later.
308
+ ///
309
+ /// # Errors
310
+ ///
311
+ /// [`Refusal::TimeRegressed`], or [`Refusal::EntriesFull`] when the key is
312
+ /// new and no metadata slot is free. Nothing changes.
313
+ pub fn put(
314
+ &mut self,
315
+ key: u64,
316
+ now: Duration,
317
+ age: Duration,
318
+ policy: Policy,
319
+ ) -> Result<(), Refusal> {
320
+ self.check(now)?;
321
+ let home = Self::room_in(&mut self.entries, key).ok_or(Refusal::EntriesFull)?;
322
+ *home = Some(Entry::new(key, now, age, policy));
323
+ self.now = now;
324
+ Ok(())
325
+ }
326
+
327
+ /// Drop the metadata for `key`, e.g. because the cache evicted its value.
328
+ ///
329
+ /// Never refuses: [`Forgetting::Forgotten`] when there was metadata to
330
+ /// drop, [`Forgetting::NotHeld`] when the key already had none, which
331
+ /// changes nothing. A refresh in flight is untouched either way.
332
+ pub fn forget(&mut self, key: u64) -> Forgetting {
333
+ match self
334
+ .entries
335
+ .iter_mut()
336
+ .find(|slot| slot.is_some_and(|entry| entry.key == key))
337
+ .and_then(Option::take)
338
+ {
339
+ Some(_) => Forgetting::Forgotten,
340
+ None => Forgetting::NotHeld,
341
+ }
342
+ }
343
+
344
+ /// Drop metadata that is [`State::Expired`] at `now`, writing the keys to `out`.
345
+ ///
346
+ /// Writes the first `n` entries, returns `n`, leaves the rest untouched,
347
+ /// and stops when `out` is full: call again to continue. Only those `n`
348
+ /// are swept keys; `[0; N]` sizes the buffer, and zero is also a valid
349
+ /// key, so read no further than `n`. Keys with a refresh in flight are
350
+ /// kept. The values themselves are the caller's to delete.
351
+ ///
352
+ /// # Errors
353
+ ///
354
+ /// [`Refusal::TimeRegressed`]. Nothing changes.
355
+ pub fn sweep(&mut self, now: Duration, out: &mut [u64]) -> Result<usize, Refusal> {
356
+ self.check(now)?;
357
+ self.now = now;
358
+ let mut room = out.iter_mut();
359
+ let mut written = 0;
360
+ for slot in &mut self.entries {
361
+ let Some(entry) = *slot else {
362
+ continue;
363
+ };
364
+ if entry.policy.state(entry.age_at(now)) == State::Expired
365
+ && !self
366
+ .leads
367
+ .iter()
368
+ .flatten()
369
+ .any(|lead| lead.key == entry.key)
370
+ {
371
+ let Some(dst) = room.next() else {
372
+ break;
373
+ };
374
+ *slot = None;
375
+ *dst = entry.key;
376
+ // One per slot of `out`, so it cannot pass `out.len()`.
377
+ written += 1;
378
+ }
379
+ }
380
+ Ok(written)
381
+ }
382
+
383
+ /// Withdraw a waiter, whether still waiting or notified but undrained.
384
+ ///
385
+ /// # Errors
386
+ ///
387
+ /// [`Refusal::Stale`] when `waiter` is not registered. Nothing changes.
388
+ pub fn cancel(&mut self, waiter: WaiterId) -> Result<(), Refusal> {
389
+ Ok(self.flights.cancel(waiter)?)
390
+ }
391
+
392
+ /// Take the oldest queued notification, freeing its waiter slot.
393
+ pub fn poll(&mut self) -> Option<Notification> {
394
+ self.flights.poll()
395
+ }
396
+
397
+ /// Move queued notifications into `out`, oldest first, and return how many.
398
+ ///
399
+ /// Writes the first `n` entries and leaves the rest untouched; only those
400
+ /// `n` are notifications. `[Notification::default(); N]` sizes the buffer
401
+ /// with a placeholder the refresher never emits. Resumable: whatever did
402
+ /// not fit stays queued, in order.
403
+ pub fn drain(&mut self, out: &mut [Notification]) -> usize {
404
+ self.flights.drain(out)
405
+ }
406
+
407
+ /// Age of the value held for `key` at `now`, if there is metadata for it.
408
+ #[must_use]
409
+ pub fn age(&self, key: u64, now: Duration) -> Option<Duration> {
410
+ Some(self.entry(key)?.age_at(now))
411
+ }
412
+
413
+ /// Fresh, stale or expired at `now`; `None` when the key has no metadata.
414
+ #[must_use]
415
+ pub fn state(&self, key: u64, now: Duration) -> Option<State> {
416
+ let entry = self.entry(key)?;
417
+ Some(entry.policy.state(entry.age_at(now)))
418
+ }
419
+
420
+ /// Age of the held value if a refresh error at `now` may be answered with it.
421
+ #[must_use]
422
+ pub fn stale_if_error(&self, key: u64, now: Duration) -> Option<Duration> {
423
+ let entry = self.entry(key)?;
424
+ let age = entry.age_at(now);
425
+ entry.policy.if_error(age).then_some(age)
426
+ }
427
+
428
+ /// The lease currently refreshing `key`, overdue or not.
429
+ #[must_use]
430
+ pub fn leading(&self, key: u64) -> Option<Lease> {
431
+ Some(Lease(self.lead_of(key)?.lease))
432
+ }
433
+
434
+ /// The coalesce flight a live lease rides on.
435
+ ///
436
+ /// This is the [`Notification::flight`] the waiters of that refresh will
437
+ /// be woken with, so a drained notification can be tied back to a lease.
438
+ /// A takeover issues a new lease for the same flight: the new lease
439
+ /// answers the flight the old one did, and the old one answers `None`.
440
+ /// Once the refresh settles the lease is stale, so record the pairing
441
+ /// while the lease is live if it is needed after the report.
442
+ ///
443
+ /// `None` for a lease that is not live: never issued, reported, abandoned,
444
+ /// reaped, taken over, or issued in another scope.
445
+ #[must_use]
446
+ pub fn flight(&self, lease: Lease) -> Option<FlightId> {
447
+ if !self.flights.owns(lease.0) {
448
+ return None;
449
+ }
450
+ self.leads
451
+ .iter()
452
+ .flatten()
453
+ .find(|lead| lead.lease == lease.0)
454
+ .map(|lead| lead.flight)
455
+ }
456
+
457
+ /// The latest time this refresher accepted.
458
+ #[must_use]
459
+ pub const fn now(&self) -> Duration {
460
+ self.now
461
+ }
462
+
463
+ /// Keys with metadata.
464
+ #[must_use]
465
+ pub fn len(&self) -> usize {
466
+ self.entries.iter().flatten().count()
467
+ }
468
+
469
+ /// Whether no key has metadata.
470
+ #[must_use]
471
+ pub fn is_empty(&self) -> bool {
472
+ self.len() == 0
473
+ }
474
+
475
+ /// Refreshes not yet reported.
476
+ #[must_use]
477
+ pub const fn in_flight(&self) -> usize {
478
+ self.flights.in_flight()
479
+ }
480
+
481
+ /// Callers waiting on a refresh.
482
+ #[must_use]
483
+ pub fn waiting(&self) -> usize {
484
+ self.flights.waiting()
485
+ }
486
+
487
+ /// Notifications queued and not yet drained.
488
+ #[must_use]
489
+ pub const fn pending(&self) -> usize {
490
+ self.flights.pending()
491
+ }
492
+
493
+ /// Maximum keys with metadata (`KEYS`).
494
+ #[must_use]
495
+ pub const fn capacity(&self) -> usize {
496
+ KEYS
497
+ }
498
+
499
+ /// Maximum refreshes at once (`FLIGHTS`).
500
+ #[must_use]
501
+ pub const fn flight_capacity(&self) -> usize {
502
+ FLIGHTS
503
+ }
504
+
505
+ /// Maximum waiting callers plus undrained notifications (`WAITERS`).
506
+ #[must_use]
507
+ pub const fn waiter_capacity(&self) -> usize {
508
+ WAITERS
509
+ }
510
+
511
+ const fn check(&self, now: Duration) -> Result<(), Refusal> {
512
+ if now.as_nanos() < self.now.as_nanos() {
513
+ Err(Refusal::TimeRegressed)
514
+ } else {
515
+ Ok(())
516
+ }
517
+ }
518
+
519
+ fn entry(&self, key: u64) -> Option<&Entry> {
520
+ self.entries.iter().flatten().find(|entry| entry.key == key)
521
+ }
522
+
523
+ /// The slot holding `key`, else a free one.
524
+ fn room_in(entries: &mut [Option<Entry>; KEYS], key: u64) -> Option<&mut Option<Entry>> {
525
+ let slot = entries
526
+ .iter()
527
+ .position(|entry| entry.is_some_and(|entry| entry.key == key))
528
+ .or_else(|| entries.iter().position(Option::is_none))?;
529
+ entries.get_mut(slot)
530
+ }
531
+
532
+ fn lead_of(&self, key: u64) -> Option<&Lead> {
533
+ self.leads.iter().flatten().find(|lead| lead.key == key)
534
+ }
535
+
536
+ const fn over(flights: Coalescer<FLIGHTS, WAITERS>) -> Self {
537
+ Self {
538
+ entries: [None; KEYS],
539
+ leads: [None; FLIGHTS],
540
+ flights,
541
+ now: Duration::ZERO,
542
+ }
543
+ }
544
+
545
+ /// The record and slot of a live lease. An id this refresher never
546
+ /// issued, one from another scope included, is turned away before the
547
+ /// table is read; an id it issued as a waiter or a flight is in no lead.
548
+ fn held_in<'a>(
549
+ leads: &'a mut [Option<Lead>; FLIGHTS],
550
+ flights: &Coalescer<FLIGHTS, WAITERS>,
551
+ lease: Lease,
552
+ ) -> Option<(Lead, &'a mut Option<Lead>)> {
553
+ if !flights.owns(lease.0) {
554
+ return None;
555
+ }
556
+ leads.iter_mut().find_map(|slot| {
557
+ let lead = slot.filter(|lead| lead.lease == lease.0)?;
558
+ Some((lead, slot))
559
+ })
560
+ }
561
+ }
562
+
563
+ #[cfg(test)]
564
+ mod tests;
@@ -0,0 +1,79 @@
1
+ //! Freshness rules over explicit ages; no table, no clock.
2
+
3
+ use core::time::Duration;
4
+
5
+ /// Where a cached value stands against its [`Policy`] at a given age.
6
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
7
+ pub enum State {
8
+ /// Younger than `fresh_for`: serve it, no questions asked.
9
+ Fresh,
10
+ /// Past `fresh_for` but inside at least one stale window: servable only
11
+ /// under that window's condition.
12
+ Stale,
13
+ /// Past every window: not servable under any condition.
14
+ Expired,
15
+ }
16
+
17
+ /// Freshness rules for one stored value.
18
+ ///
19
+ /// Both stale windows open the moment the value stops being fresh, as in
20
+ /// RFC 5861. All three are spans; zero disables the rule.
21
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
22
+ pub struct Policy {
23
+ /// The value is fresh while its age is below this.
24
+ pub fresh_for: Duration,
25
+ /// After freshness ends, the value may be served for this long while a
26
+ /// revalidation runs in the background.
27
+ pub stale_while_revalidate: Duration,
28
+ /// After freshness ends, the value may be served for this long when a
29
+ /// refresh fails.
30
+ pub stale_if_error: Duration,
31
+ }
32
+
33
+ impl Policy {
34
+ /// Build a policy from its three durations.
35
+ #[must_use]
36
+ pub const fn new(
37
+ fresh_for: Duration,
38
+ stale_while_revalidate: Duration,
39
+ stale_if_error: Duration,
40
+ ) -> Self {
41
+ Self {
42
+ fresh_for,
43
+ stale_while_revalidate,
44
+ stale_if_error,
45
+ }
46
+ }
47
+
48
+ /// Classify a value of the given age.
49
+ #[must_use]
50
+ pub const fn state(&self, age: Duration) -> State {
51
+ if age.as_nanos() < self.fresh_for.as_nanos() {
52
+ State::Fresh
53
+ } else if self.while_revalidate(age) || self.if_error(age) {
54
+ State::Stale
55
+ } else {
56
+ State::Expired
57
+ }
58
+ }
59
+
60
+ /// Whether a value of this age may be served while it is revalidated.
61
+ #[must_use]
62
+ pub const fn while_revalidate(&self, age: Duration) -> bool {
63
+ self.within(age, self.stale_while_revalidate)
64
+ }
65
+
66
+ /// Whether a value of this age may be served because a refresh failed.
67
+ #[must_use]
68
+ pub const fn if_error(&self, age: Duration) -> bool {
69
+ self.within(age, self.stale_if_error)
70
+ }
71
+
72
+ /// Whether `age` is past freshness by less than `window`.
73
+ const fn within(&self, age: Duration, window: Duration) -> bool {
74
+ match age.checked_sub(self.fresh_for) {
75
+ Some(past) => past.as_nanos() < window.as_nanos(),
76
+ None => false,
77
+ }
78
+ }
79
+ }
@@ -0,0 +1,47 @@
1
+ use core::fmt;
2
+
3
+ /// Why a call changed nothing.
4
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
5
+ pub enum Refusal {
6
+ /// `now` is earlier than a time this refresher already accepted.
7
+ TimeRegressed,
8
+ /// A zero lead duration: the lease would be overdue before it was issued.
9
+ ZeroLead,
10
+ /// Every metadata slot holds another key.
11
+ EntriesFull,
12
+ /// Every refresh slot holds an unsettled refresh; no new key can be led.
13
+ FlightsFull,
14
+ /// Every waiter slot holds a waiting caller or an undrained notification.
15
+ WaitersFull,
16
+ /// The id space is spent; this refresher can register nothing more.
17
+ Exhausted,
18
+ /// The lease or waiter names nothing live.
19
+ Stale,
20
+ }
21
+
22
+ impl fmt::Display for Refusal {
23
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
24
+ f.write_str(match self {
25
+ Self::TimeRegressed => "time moved backwards",
26
+ Self::ZeroLead => "lead duration must be positive",
27
+ Self::EntriesFull => "every metadata slot is in use",
28
+ Self::FlightsFull => "every refresh slot is in use",
29
+ Self::WaitersFull => "every waiter slot is in use",
30
+ Self::Exhausted => "id space exhausted",
31
+ Self::Stale => "id does not name a live lease or waiter",
32
+ })
33
+ }
34
+ }
35
+
36
+ impl core::error::Error for Refusal {}
37
+
38
+ impl From<coalesce_machines::Refusal> for Refusal {
39
+ fn from(refusal: coalesce_machines::Refusal) -> Self {
40
+ match refusal {
41
+ coalesce_machines::Refusal::FlightsFull => Self::FlightsFull,
42
+ coalesce_machines::Refusal::WaitersFull => Self::WaitersFull,
43
+ coalesce_machines::Refusal::Exhausted => Self::Exhausted,
44
+ coalesce_machines::Refusal::Stale => Self::Stale,
45
+ }
46
+ }
47
+ }
@@ -0,0 +1,2 @@
1
+ # frozen_string_literal: true
2
+ require_relative 'ffi/extconf'