1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
//! COALESCING WITH NO CLOCK OF ITS OWN: the size-or-time batch, and the quiet-window debounce.
//!
//! Two machines and one posture. Neither owns a thread, neither owns a timer, and neither reads the
//! clock — `now` arrives as an ARGUMENT on every call that needs one. What each holds is the state a
//! coalescer has (an open batch and when it opened; a set of pending keys and when each falls
//! quiet), and what each answers is the one question a driving loop must ask on its behalf:
//! `deadline` — WHEN to come back.
//!
//! * [`Batcher<T>`] flushes on whichever arrives first, a count or a wait. `max_items` is BOTH the
//! trigger and the bound, so a driver that flushes only on the timer still cannot grow a batch
//! without end: a push into a full batch is REFUSED and the item handed back.
//! * [`Debounce<K>`] coalesces a burst per KEY. A second touch RESETS that key's window, so
//! `create` + `modify` + `modify` is one intake rather than three — and a key nobody re-touched is
//! untouched by the one somebody did.
//!
//! # THE OWNING LOOP DRIVES ME — the contract, and the whole of it
//!
//! Nothing here happens on its own. A loop that owns one of these machines runs three lines
//! forever, and the machine supplies the middle one:
//!
//! 1. ask `deadline()` — `None` means *nothing is pending, park until something arrives*;
//! 2. wait for whichever comes first, an arrival or that instant;
//! 3. hand the machine the `now` it woke at, and take what came due.
//!
//! The waiting is the LOOP's, and that is what makes the pair engine-agnostic. On the async engine
//! the driver is a long-lived task on the runtime the app ignited, and step 2 is that runtime's own
//! timer against its own channel; on the pure-thread engine it is a `Sweeper`-shaped park. Neither
//! spelling reaches in here, which is the same posture `Recurrence` and the poll clock behind a
//! `Resident` already take: a schedule computes instants and something else does the sleeping.
//!
//! It is also why a test needs no clock control and no waiting. `now` is a value, so a fake clock is
//! an [`Instant`](std::time::Instant) and some arithmetic, and a 500 ms window is exercised in
//! microseconds.
//!
//! # Durations arrive already parsed
//!
//! `max_wait` and `quiet` are [`Duration`](core::time::Duration)s. Where they came from — a default,
//! a `[registry]` section in a startup file, a knob on a request — is the options layer's business,
//! and the text form a person wrote is `humantime`'s. Neither word reaches this module, which
//! therefore has nothing to say about precedence between them.
//!
//! # Why this is CORE and rides no tier
//!
//! Both machines are `std` and arithmetic. They name no engine, no runtime, no backend and no
//! dependency, and their customers do not sit in one tier: the registry intake is a `runtime`
//! concern, and the record seat's write batching is a store one. Gating them on `runtime` would make
//! a coalescer that costs a build nothing unavailable to a build that has the store and no driver,
//! for no reason but where the first caller happened to live.
//!
//! # The plug sites
//!
//! These land AHEAD of their customers, and the demand that admitted them is one finding: the
//! feasibility census behind the root-key registry read the framework's timing suite as complete —
//! `park_on`, `select`, the shutdown arm, `Recurrence`, the merged tick cell, the sweeper — and
//! complete EXCEPT for these two shapes and the deadline schedule under them. Every seat below
//! wanted one, and every one of them would otherwise have written its own.
//!
//! * **The registry intake.** [`Debounce`] over root keys: a burst of filesystem events on one asset
//! becomes one analysis, and the driver feeds the head node once the key has fallen quiet.
//! * **The record seat's write batching.** [`Batcher`] over rows, where one batch is one
//! transaction — a count bound the transaction cannot exceed, and a wait so a trickle still lands.
//! * **A subscriber's publish cadence.** The fulltext index became a node and its write lane became
//! a seam; a cadence knob on that seam is a [`Batcher`] and nothing else.
//! * **The retirement sweep.** Retired keys collected into one `WHERE lineage IN (…)` rather than a
//! statement apiece.
//!
//! # Examples
//!
//! One driving loop's worth of turns, with the clock supplied by hand — which is exactly what a test
//! does, and exactly what a runtime's timer does for real:
//!
//! ```
//! use core::{num::NonZeroUsize, time::Duration};
//! use std::time::Instant;
//!
//! use ingraph::batch::{Batcher, Debounce, Push};
//!
//! let quiet = Duration::from_millis(500);
//! let start = Instant::now();
//!
//! let mut debounce = Debounce::<u64>::new(quiet);
//! let mut batcher = Batcher::<u64>::new(
//! NonZeroUsize::new(10).expect("ten is not zero"),
//! Duration::from_millis(500),
//! );
//!
//! // A burst on ONE key: a create and two modifies, 10 ms apart.
//! debounce.touch(7, start);
//! debounce.touch(7, start + Duration::from_millis(10));
//! debounce.touch(7, start + Duration::from_millis(20));
//!
//! // What the loop parks until — the LAST touch plus the window, not the first.
//! assert_eq!(debounce.deadline(), Some(start + Duration::from_millis(520)));
//! assert!(debounce.ripe(start + Duration::from_millis(519)).is_empty());
//!
//! // One intake for the whole burst, and nothing left pending.
//! assert_eq!(debounce.ripe(start + Duration::from_millis(520)), vec![7]);
//! assert_eq!(debounce.deadline(), None);
//!
//! // The intake feeds the batch, which flushes on whichever of the two comes first.
//! assert_eq!(batcher.push(7, start), Push::Queued);
//! assert_eq!(batcher.deadline(), Some(start + Duration::from_millis(500)));
//! assert!(!batcher.ready(start));
//! assert!(batcher.ready(start + Duration::from_millis(500)));
//!
//! // END punctuation BEATS the timer, and `drain` is the door that says so: it asks nothing about
//! // size and nothing about time.
//! assert_eq!(batcher.drain(), vec![7]);
//! assert_eq!(batcher.deadline(), None);
//! ```
pub use ;
pub use Debounce;