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
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
//! Per-subscription fan-out **outside** the actor: a [`Demux`] task consumes one
//! [`Tributaries`] handle as the shared stream's sole drainer and routes every event to
//! its subscription's own bounded [`Lane`] — stalling, never shedding, when a lane is
//! full. The full public contract (loss authority stays in the actor; sole drainer;
//! lane/rest routing; end-of-stream fan-in) lives on [`Demux`], the crate-root-exported
//! entry point.
use ;
use Future;
use RuntimeLite;
use FutureExt;
use crate::;
/// The control queue's depth. Small on purpose: control messages are tiny and rare, and
/// a BOUNDED queue is what keeps a stalled routing task from turning registration into
/// an unbounded memory-growth path — while the task is parked on a full
/// lane's awaited send it services no control messages, so registrants must feel
/// backpressure instead of queueing without limit.
const CONTROL_CAPACITY: usize = 16;
/// The release a registered [`Lane`] owes on drop: its subscription, its registration
/// brand, and the control queue to notify.
/// A control message into the routing task.
/// The per-subscription fan-out layer **outside** the actor: a routing task that
/// consumes one [`Tributaries`] handle as the shared stream's sole drainer and delivers
/// every event into its subscription's own bounded [`Lane`] — stalling, never shedding,
/// when a lane is full.
///
/// [`Tributaries`] clones share ONE MPMC event stream: competing
/// [`next`](Tributaries::next) callers steal from each other, so "each subscription its
/// own task" cannot be built by cloning the handle. The demux is the supported shape —
/// one routing task drains the shared stream and fans events out by their
/// [`Subscription`] token. A `Demux` is the *control* handle over that task:
/// [`lane`](Self::lane) registers per-subscription lanes with the routing task
/// [`spawn`](Self::spawn) started. Dropping it only closes the control channel — the
/// routing task keeps routing until the shared stream ends.
///
/// # Loss authority stays in the actor
///
/// The demux never drops a known event, and it never synthesizes or mints events or
/// `Rescan`s of its own. Its **only** backpressure move is to *stop receiving* from the
/// shared stream: delivery into a full lane is an awaited send, and while that send
/// waits the shared channel fills behind it — where the **actor's** own overflow
/// machinery sheds, minting genuine parked, epoch-dominating
/// [`Rescan`](crate::EventKind::Rescan)s. Every loss therefore remains a contract-grade,
/// actor-minted `Rescan`; nothing is lost at this layer. The cost, stated plainly: this
/// buys **loss-isolation, not latency-isolation** — a stalled lane head-of-line delays
/// the other lanes' *delivery*, never their loss accounting.
///
/// # Sole drainer
///
/// [`spawn`](Self::spawn) **consumes** a `Tributaries` handle and drains its stream from
/// the spawned routing task. The consumed handle's stream must not be drained by any
/// other clone: clones the caller kept are for `watch`/`unwatch`/`close` (and the read
/// plane) ONLY — a second `next()` caller steals events out from under the demux and
/// voids routing. This is convention-enforced; it cannot be made static, because every
/// clone carries the same `next()`.
///
/// # Lanes, and the rest lane
///
/// [`lane`](Self::lane) registers a bounded per-subscription lane over a **bounded**
/// control channel into the routing task; the registration send is awaited, so while
/// the routing task is stalled on a full lane, registrants feel backpressure instead of
/// growing an unbounded control queue. Events whose subscription has no
/// registered lane land on the **rest** lane returned by [`spawn`](Self::spawn). A
/// registration is applied before the routing of any event that enters the shared
/// stream after it returns, so events emitted after `lane` returns reach the lane;
/// events already in flight may still land on rest — register the lane before its
/// events flow, or drain rest.
///
/// # Dropped lanes release their subscription back to unclaimed
///
/// A dropped [`Lane`] sends a best-effort release to the routing task, a delivery
/// that observes the dropped receiver reclaims the slot on the spot (recovering that
/// very event), and — the structural backstop — every registration first sweeps all
/// entries whose receiver is gone before installing (registration being the table's
/// only growth site; a release lost to a full control queue on an idle
/// subscription is reclaimed at the latest by the next registration). All three paths
/// REMOVE the entry, so the lane table is bounded by *peak-concurrent* lanes, never by
/// lifetime registrations. From the
/// release onward the subscription is unclaimed again: its late stragglers surface on
/// the rest lane exactly like pre-registration traffic — while a lane is registered it
/// exclusively owns its subscription's events; there is no split delivery. A consumer
/// that wants zero stragglers unwatches first and drains its lane before dropping it.
/// Once the rest receiver is dropped, unrouted events are discarded from then on.
/// Registering a fresh lane for the subscription re-claims it from that point onward.
///
/// # End of stream, and who owns which lifecycle
///
/// When the shared stream ends — the actor is gone and the tail is drained, `next()`
/// returning `None` — the routing task drops every lane sender and exits: each
/// [`Lane::recv`] then drains its buffered tail and returns `None`. Dropping the
/// `Demux` handle only closes the control channel — the task keeps routing; it just
/// accepts no new lanes. The underlying watcher lifecycle stays entirely with the
/// caller's own clones: `close()`/`unwatch` there — a closed watcher ends the stream,
/// which ends the lanes. Note that the routing task's consumed handle keeps the actor's
/// command mailbox open, so dropping the caller's clones alone does not tear the
/// watcher down; ask for it with [`close`](Tributaries::close) (or let the source
/// drain). The task holds the consumed handle for `next()` only — it never calls
/// `watch`/`unwatch`/`close` itself.
///
/// # Example
///
/// ```rust,no_run
/// # #[cfg(all(feature = "tokio", feature = "fs"))]
/// # async fn demo() -> Result<(), Box<dyn std::error::Error>> {
/// use std::{ffi::OsString, path::Path};
///
/// use tributaries::{Demux, TokioTributaries, TributariesOptions, WatchOptions, WatcherOptions};
///
/// fn key(path: &str) -> Vec<OsString> {
/// Path::new(path)
/// .components()
/// .map(|c| c.as_os_str().to_os_string())
/// .collect()
/// }
///
/// let w = TokioTributaries::new(WatcherOptions::new(), TributariesOptions::new())?;
/// let project = key("/path/to/project");
/// let sub = w.watch(project.clone(), (), WatchOptions::new()).await?;
///
/// // The demux CONSUMES one handle (the sole drainer); `w` stays behind for
/// // watch/unwatch/close only — never for next().
/// let (demux, rest) = Demux::spawn(w.clone(), 64);
/// let lane = demux.lane(sub, 64).await;
///
/// // One independent task per lane; a full lane stalls the demux (latency), while the
/// // actor keeps the loss accounting (a dominating Rescan on overflow).
/// let consumer = tokio::spawn(async move {
/// while let Some(event) = lane.recv().await {
/// if event.reaches(&project) {
/// // re-enumerate / re-read below `event.key()`
/// }
/// }
/// // None: the watcher closed and the lane's buffered tail is drained.
/// });
/// // Unclaimed subscriptions' events arrive on the rest lane.
/// tokio::spawn(async move { while let Some(_event) = rest.recv().await {} });
///
/// // Teardown: retire the subscription (queued stragglers still drain through the
/// // lane), then close the watcher — the ended stream ends every lane, and the lane
/// // task drops its Lane on exit.
/// w.unwatch(sub).await?;
/// w.close().await?;
/// consumer.await?;
/// # Ok(())
/// # }
/// ```
/// One bounded per-subscription event stream fed by a [`Demux`] routing task — either a
/// claimed subscription's own lane ([`Demux::lane`]) or the rest lane
/// ([`Demux::spawn`]).
///
/// Deliberately not `Clone`: a lane has a single consumer. [`recv`](Self::recv) yields
/// the lane's events in delivery order and `None` at end-of-stream (the watcher closed
/// and the buffered tail is drained).
/// The routing loop: drain the consumed `watcher` stream, deliver each event to its
/// subscription's lane (an **awaited** send — the deliberate stall that pushes
/// backpressure into the shared channel, where the actor keeps the loss authority), or
/// to `rest` when unclaimed. Exits when the stream ends, dropping every lane sender so
/// each [`Lane`] drains then reads `None`.
async
/// The routing task's lane table: each claimed subscription's registration generation
/// and bounded send side.
type LaneTable<C, V> = ;
/// One delivery: route `event` to its subscription's lane — THE deliberate stall
/// (stall-not-shed): the bounded lane send is awaited, so a full lane parks the caller
/// while the shared channel fills and the ACTOR's overflow machinery mints the genuine
/// dominating Rescans; the demux itself never sheds. A send that observes the lane's
/// receiver dropped reclaims the slot on the spot (send-time reclamation, /// covers a lost drop-release) and RECOVERS the very event the failed send handed
/// back: the subscription is unclaimed again, and the recovered event flows to rest
/// like any unclaimed traffic. A dropped rest receiver discards unrouted events from
/// then on.
async