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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
//! THE ENGINE SUBSTRATE: where an async body's runtime comes from, and where its clock does.
//!
//! The thread engine needs nothing from this module. It owns an OS thread, parks in a blocking
//! receive and times itself with `recv_timeout` — a machine `std` already ships — which is why it is
//! the default per engine-follows-mobility and why a `!Send` node is an ordinary node on it.
//!
//! The ASYNC engine has no such luck. A task needs a runtime to be spawned onto, and a task that
//! parks in `recv_async` cannot time itself, so its clock has to be somebody's timer. Both were open
//! questions this layer answered by handing work back to the caller: a composed body for whoever
//! held a runtime, and a [`Sweeper`](super::Sweeper) — one thread, one hand-written timer wheel —
//! for the cadences. This module is what closes them.
//!
//! # ONE runtime, named ONCE, at the door
//!
//! [`agnostic_lite`] is the substrate. An app names its runtime at the ignition door
//! ([`Assembly::ignite_on`](super::Assembly::ignite_on)) and nowhere else, and everything downstream
//! of that reads what it needs off the same `R`. What that buys over a launch-time handle is a
//! COMPILE-TIME fact where there was a start-up refusal: a deployment with an async node and no
//! runtime does not build, because the method that spawns one exists only on an
//! [`Ignition`](super::Ignition) whose runtime has been named.
//!
//! # BUNDLE AT THE DOOR, NARROW INSIDE
//!
//! The door's bound is [`RuntimeLite`](agnostic_lite::RuntimeLite) — one name for an app to write.
//! Every organ below it binds exactly what it spends and no more: [`engage`] takes an
//! [`AsyncSpawner`], [`after_clock`] takes an [`AsyncAfterSpawner`]. So this module's own surface
//! says what the async engine actually uses, and a reader of it does not have to take a runtime
//! trait's whole vocabulary on trust to see that the clock spawns nothing but timers.
//!
//! # THE `!Send` LAW
//!
//! The async engine requires `Send` bodies, because [`AsyncSpawner::spawn`] does: a task may be
//! stolen by another worker thread, and a value that cannot cross one cannot be spawned. That is not
//! a restriction this crate adds — it is the mobility the engine choice already declares, and PIN 5's
//! sentence read from the runtime's side.
//!
//! The `!Send` home is the THREAD engine, and it is a first-class one: a model context, an FFI
//! session, anything whose handle is pinned to the thread that made it, is constructed on its own
//! resident thread and never migrates.
//!
//! [`AsyncLocalSpawner`](agnostic_lite::AsyncLocalSpawner) is the named seat for the lane that would
//! change that — a `!Send` body on a thread-pinned executor — and it is REFUSED UNTIL there is
//! something to measure it against. Nothing here writes it: a local spawn needs an ambient
//! thread-local executor that not every runtime has (smol panics, embassy panics, tokio panics
//! outside a `LocalSet`), so a lane built on it would be a lane that works on one backend and
//! panics on the next. The seat is named so the widening has an address, and left empty so nobody
//! mistakes an unmeasured hope for a supported posture.
use ;
use ;
use ;
use ;
/// The absence of an async runtime, as a type.
///
/// [`Unpolled`](super::Unpolled)'s sibling one layer up: a marker whose whole job is to be the
/// default nobody writes. An [`Ignition`](super::Ignition) is `Ignition<Unruntimed>` unless a
/// deployment named a runtime, so a THREAD-ONLY graph — the shape most arrangements have — spells
/// nothing at all, and the async-only surface is simply not there to call.
///
/// It is what makes *a missing runtime* a compile-time fact rather than a start-up refusal, and it
/// is why that fact reads well: rustc's *no method named `spawn` found for struct
/// `Ignition<Unruntimed>`* names both halves of what went wrong — what was reached for, and the
/// absence that explains it.
;
/// One async body's JOIN, as the launch holds it.
///
/// The handle a spawn answers is `<R::Spawner as AsyncSpawner>::JoinHandle<()>` — a different type
/// per runtime — and the world that has to await it at shutdown is [`App`](super::App), which is
/// generic over the generated root and not over the runtime. So the typed handle is erased HERE, at
/// the one site that knows which runtime spawned it, exactly as the teardown chain's hand-back is
/// boxed by the one party that knows the value's type.
///
/// It stays a FUTURE rather than becoming a `dyn Any`, which is the whole point: the join step can
/// still await it, and dropping one detaches the task the way dropping a thread's handle detaches a
/// thread.
pub type Join = ;
/// Spawn `body` on `S`, and hand back the join the shutdown will await.
///
/// The narrow half of the door's bound: spawning is all this does, so [`AsyncSpawner`] is all it
/// asks for.
pub
/// How a deployment's cadences are DRIVEN.
///
/// A function pointer rather than a stored closure, because what it carries is a TYPE and not a
/// value: [`after_clock`] instantiated at the runtime the door named, or [`hand_timer`] where no
/// runtime was. Both answer the erased handle that STOPS the clock, which is the same shape every
/// other source's start answers — see [`Ignition::source`](super::Ignition::source).
pub type Clock = fn ;
/// The R-LESS clock: one thread, one hand-written timer wheel.
///
/// What this layer had before it had a runtime, kept as the fallback for the world that still has
/// none — a hand-wired arrangement spawning its own async bodies with
/// [`Ignition::task`](super::Ignition::task) has cadences to ring and nothing to ring them with.
pub
/// The RUNTIME's clock: every cadence on the After family, and not a thread of our own.
pub
/// The ASYNC engine's clock: one self-re-arming timer per cadence, on the runtime's own After
/// family.
///
/// [`Sweeper`](super::Sweeper)'s twin, and the reason it has one: a sweeper is a thread running a
/// timer wheel somebody here wrote, which is a runtime this crate built rather than a runtime it
/// was given. Where an app has named one, its `spawn_after` is that machine — Go's `time.AfterFunc`
/// as a trait — and the wheel becomes what it always was, a stand-in.
///
/// # A cadence is a REPEAT and the After family fires ONCE, so the fire re-arms
///
/// [`AsyncAfterSpawner::spawn_after`] runs a future after a duration and is done. A cadence rings
/// forever, so each fire rings and then arms the next one — the interval measured from the fire and
/// never from the deadline it may have missed, which is the same *one look, never a burst of
/// catch-up* posture the sweeper's wheel and the thread engine's arithmetic both spell.
///
/// The cost of that is stated rather than hidden: ONE SPAWN PER FIRE PER CADENCE, which is what a
/// repeat costs on a family whose primitive fires once. `reset` cannot buy it back — it adjusts a
/// delay that has not elapsed, and a fired timer's task has returned — so the alternative would be
/// the runtime's interval family, one task per cadence looping a stream. That is a real option and
/// it is not taken here: what rides this clock is a schedule (a sweep floor, a reaper's ten minutes,
/// a compactor's hour), so the spawn rate is the cadence rate, and the After family is what the
/// design record names. A deployment that ever makes a cadence hot enough for the difference to
/// register is the measurement that would move it.
///
/// # Dropping this must release the ringers AT ONCE, and that is what shapes it
///
/// A ringer holds a full sender into a node's inbox, and that sender is often the last thing keeping
/// a poll-only node alive — so the clock's drop is a step of the shutdown wave rather than
/// housekeeping. An armed timer holding the ringer would release it one interval late, and an
/// interval can be an hour.
///
/// So the timers hold a HAND rather than a ringer: dropping the clock empties every hand — the
/// senders are gone as the drop returns — and the fire that follows finds an empty one and stops
/// re-arming. What is left running is one timer per cadence with nothing in it, for at most one
/// interval, which is a task the runtime reaps and not a sender anybody is waiting on.
/// One cadence as the clock holds it: the interval, and the ringer BEHIND A LATCH the clock's drop
/// can open.
///
/// The latch is what separates the two lifetimes this design has to keep apart — the timer's, which
/// ends at the next fire, and the sender's, which must end when the clock is dropped.
/// Arm `hand`'s next fire.
///
/// Recursive, and it costs nothing: `arm` is an ordinary function called from inside the spawned
/// future rather than awaited by it, so the future's own type never contains itself — what recurses
/// is one call at the end of one timer, which is what a repeating clock IS.