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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +109 -0
- data/Cargo.lock +325 -0
- data/Cargo.toml +29 -0
- data/LICENSE.txt +21 -0
- data/README.md +352 -0
- data/ext/refresh_machines_native/core/CHANGELOG.md +77 -0
- data/ext/refresh_machines_native/core/Cargo.toml +21 -0
- data/ext/refresh_machines_native/core/README.md +175 -0
- data/ext/refresh_machines_native/core/src/decision.rs +83 -0
- data/ext/refresh_machines_native/core/src/lead.rs +123 -0
- data/ext/refresh_machines_native/core/src/lease.rs +42 -0
- data/ext/refresh_machines_native/core/src/lib.rs +564 -0
- data/ext/refresh_machines_native/core/src/policy.rs +79 -0
- data/ext/refresh_machines_native/core/src/refusal.rs +47 -0
- data/ext/refresh_machines_native/extconf.rb +2 -0
- data/ext/refresh_machines_native/ffi/Cargo.toml +22 -0
- data/ext/refresh_machines_native/ffi/extconf.rb +14 -0
- data/ext/refresh_machines_native/ffi/src/answers.rs +117 -0
- data/ext/refresh_machines_native/ffi/src/init.rs +66 -0
- data/ext/refresh_machines_native/ffi/src/lib.rs +389 -0
- data/ext/refresh_machines_native/ffi/src/values.rs +124 -0
- data/lib/refresh_machines/version.rb +5 -0
- data/lib/refresh_machines.rb +113 -0
- data/sig/refresh_machines.rbs +179 -0
- metadata +90 -0
|
@@ -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
|
+
}
|