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
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
//! The compute unit, its faces, and its emission organ.
//!
//! A unit transforms `In` into `Out`. Because both are the
//! declared struct an edge moves, an edge (`subscribe`) that requires
//! `downstream::In == upstream::Out` compile-checks the one type the two
//! ends have to agree on. An `accept` call buffers its outputs in a typed
//! [`Emitter<Out>`]; the runtime drains and routes them.
//!
//! The face is which of [`Operator`] and [`AsyncOperator`] the body wears — whether `accept`
//! answers or has to be awaited — and everything below the pair is written once over [`Driven`], the
//! shape they share. [`Word`] is where a DECLARED mode crosses the wall between two macro
//! expansions, and [`Drives`](crate::Drives) is where the two faces meet the two engines.
//!
//! # THREE KINDS, and what the NODE has to own is what picks between them
//!
//! The BUFFERED pair above is the whole of the seam for a body whose per-item fan-out is bounded in
//! its input, which is every body in this tree. [`StreamOperator`] / [`AsyncStreamOperator`] is the
//! seam's second pair, for the case [`Emitter`]'s own note calls catastrophic: a fan-out that GROWS
//! WITH THE INPUT, streamed out through a bounded [`Feed`] over one delivery's whole life instead of
//! held in a buffer until the call returns.
//!
//! [`AutonomousOperator`] / [`AsyncAutonomousOperator`] is the THIRD, and it divides on a different
//! question: both pairs above are PER-DELIVERY faces where the framework runs the loop, and this one
//! hands the loop over. [`AutonomousOperator`]'s own docs carry the three-row selection law, the
//! lifecycle its by-value `self` implies, and the operational space that is the whole reason a third
//! kind exists rather than a widened first.
//!
//! # FACE and MODE are two words for two things, and the division is defined HERE
//!
//! A **face** is the noun for one half of a trait pair — [`Operator`] and [`AsyncOperator`] are the
//! two faces of the buffered compute seam, exactly as `Lands`/`AsyncLands` are of the landing one and
//! as [`StreamOperator`]/[`AsyncStreamOperator`] are of the streaming seam. It names a TRAIT, and an
//! author picks one by writing an `impl`.
//!
//! A **mode** is the SEAT that says which half a type or a declaration chose: [`Block`] and
//! [`Async`] are its two values, [`Driven<M>`] is the row indexed by one, and
//! [`Declared::Mode`](crate::Declared::Mode) is where a declaration states its own. It names a TYPE,
//! and it is what a bound can select on — which is the whole reason it exists beside the faces
//! rather than instead of them.
//!
//! [`Driven`] and [`Drives`](crate::Drives) are the family's pair, one verb apart: a `Drives` cell
//! DRIVES the unit whose mode it was built on, and a `Driven<M>` row is what that unit IS on the
//! mode `M`. Four cells, two rows, one word between them.
use smol_bytes::Utf8Bytes;
use crate::{
Context, Delivery, ReasonName,
drive::{Downstream, Upstreams, Wanted},
source::{Feed, Fin},
};
/// Why a message was intentionally not emitted (a recorded gap, not an error).
///
/// A vocabulary of built-in reasons plus [`Custom`](Self::Custom), an open escape
/// for an operator-authored label. `#[non_exhaustive]` because more built-in
/// reasons may be added — an external match must carry a wildcard arm.
#[derive(Debug, Clone, PartialEq, Eq, derive_more::Display, derive_more::IsVariant)]
#[display("{}", self.as_str())]
#[non_exhaustive]
pub enum SkipReason {
/// An operator filtered it out (a filter-gate dropped it).
Filtered,
/// An emission reached no consumers (the producer has no outgoing edge).
NoConsumers,
/// The destination consumer's conduit had hung up.
ServiceInactive,
/// An operator-authored reason label — the lossless escape, and the WIRE FORM of an
/// operator's own reason vocabulary.
///
/// A `FateTap` is the only vantage an app has on a refusal, so this label is meant to be READ
/// BACK. Read it through the typed round-trip ([`SkipLabel`] + [`encode`](Self::encode) /
/// [`decode`](Self::decode)) rather than by matching the string at the tap: the label stays the
/// wire form, and the operator's own enum is the authority at both ends.
Custom(Utf8Bytes),
}
impl SkipReason {
/// Build a [`Custom`](Self::Custom) reason from an operator-authored label. The untyped door —
/// [`encode`](Self::encode) is the one that survives a rename, because it derives the label from
/// a [`SkipLabel`] impl the decoding end also reads.
#[inline]
pub fn custom(reason: impl Into<Utf8Bytes>) -> Self {
Self::Custom(reason.into())
}
/// ENCODE an operator's own reason into the erased wire form — the outbound half of the
/// [`SkipLabel`] round-trip.
///
/// Allocation-free, and the `&'static` on a label is what buys it: the wire form takes the
/// static through [`Utf8Bytes::from_static`], which inlines a short label and otherwise points at
/// the string already in the binary. This door is the only one that can — the untyped
/// [`custom`](Self::custom) takes a label of any lifetime and has to copy it.
#[inline]
pub fn encode<R>(reason: &R) -> Self
where
R: SkipLabel,
{
Self::Custom(Utf8Bytes::from_static(reason.label()))
}
/// DECODE this reason back into an operator's own vocabulary — the inbound half, and the only
/// supported way for a tap to act on a refusal it recognises.
///
/// `None` when the label is outside `R`'s vocabulary: another operator's reason (one tap
/// observes many, each with its own enum) or a built-in `R` chooses not to model. The whole
/// reason is offered, not just [`Custom`](Self::Custom)'s payload — [`as_str`](Self::as_str) is
/// the one spelling — so an `R` that wants `filtered` may claim it.
#[inline]
pub fn decode<R>(&self) -> Option<R>
where
R: SkipLabel,
{
R::from_label(ReasonName::new(self.as_str()))
}
/// A stable name for the fate tap / logs: the built-in spelling, or a custom
/// reason's label verbatim.
#[inline]
pub fn as_str(&self) -> &str {
match self {
Self::Filtered => "filtered",
Self::NoConsumers => "no_consumers",
Self::ServiceInactive => "service_inactive",
Self::Custom(reason) => reason.as_str(),
}
}
}
/// An operator's OWN skip vocabulary, made round-trippable across the erased tap boundary.
///
/// An operator refuses items for reasons core has no name for, and a `FateTap` is the only place an
/// app learns of a refusal — so the app must be able to act on the reason, and acting on a bare
/// string is exactly what this crate refuses elsewhere (a boundary string earns a type). Implement
/// this on the enum the operator already has, encode with [`SkipReason::encode`], decode with
/// [`SkipReason::decode`]: the enum is then the single authority at BOTH ends, and a renamed
/// variant moves both sides at once.
///
/// # The round-trip law
///
/// `R::from_label(r.label()) == Some(r)` for every `r`, hence
/// `SkipReason::encode(&r).decode::<R>() == Some(r)`. [`label`](Self::label) is `&'static` because
/// a reason vocabulary is closed and spelled in the source: a per-item detail belongs in the
/// content a skip names ([`Skip::about`]), never in a formatted label that no `from_label` could
/// parse back.
///
/// A [`ReasonName`] rather than a `&str`, on both ends, because a label and that per-item detail
/// are otherwise one type on one path — see the name's own note for what the compiler could not
/// check while they were. It is a `#[repr(transparent)]` view, so passing the erased wire spelling
/// through it costs nothing, and it is where a label that a tap eventually STORES joins this
/// crate's other names instead of arriving as the one loose string among them.
///
/// # Why the wire form stays erased
///
/// [`SkipReason::Custom`] keeps its `Utf8Bytes` and `FateTap` stays object-safe over one `Fate`.
/// That is deliberate: ONE tap observes every operator in the graph, and those operators carry
/// DIFFERENT reason vocabularies, so a tap generic over the reason type could observe only one of
/// them — strictly less flexible. The erasure is load-bearing; the typing belongs at the ends.
pub trait SkipLabel {
/// This reason's stable wire label. Must be unique within `R` and stable across releases — it
/// is what [`from_label`](Self::from_label) matches on the other side of the tap.
fn label(&self) -> &'static ReasonName;
/// Recover the reason a `label` names, or `None` when the label is not one of this
/// vocabulary's. REQUIRED, with no default: a defaulted `None` would make every decode silently
/// unreachable, which is a wrong answer rather than a missing one.
fn from_label(label: &ReasonName) -> Option<Self>
where
Self: Sized;
}
/// One intentional refusal, as the operator states it: WHY, and — where the operator can say so —
/// WHICH content it was about.
///
/// The two facts are independent, so they compose rather than multiplying the verbs: build from a
/// [`SkipReason`] (`emitter.skip(SkipReason::Filtered)` still reads as it always did, through
/// [`From`]), or name the content with [`about`](Self::about).
///
/// # Why the content is here at all
///
/// A tap sees the refusal and the node, and until now nothing else — so "which item did we drop?"
/// was answerable only when the lane happened to have ONE candidate. An operator holds the answer
/// at the moment it refuses; nothing downstream can reconstruct it, because a skip emits
/// nothing.
///
/// # Why the framework never fills it in
///
/// Core would have to name app content to derive it, and it never does: what an edge moves is the
/// app's own declared struct, so reading an identity out of one means naming a type core does not
/// know. So the operator supplies it, the driver's own refusals ([`SkipReason::NoConsumers`],
/// [`SkipReason::ServiceInactive`]) honestly carry `None`, and `None` means "not stated", never
/// "no content".
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Skip {
reason: SkipReason,
content: Option<Utf8Bytes>,
}
impl Skip {
/// A refusal for `reason`, naming no content.
#[inline]
pub const fn new(reason: SkipReason) -> Self {
Self {
reason,
content: None,
}
}
/// Name the content this refusal is ABOUT — the answer to "which item?".
///
/// RENDERED, eagerly: the content is held as the text the operator gave, because its whole
/// audience is human — a tap prints it, a dead-letter carries it, and nothing in the framework
/// interprets it. Taking [`Display`](core::fmt::Display) rather than a storage value is also what
/// keeps this layer free of the store's: an operator names content, and whether that content is
/// also a key field is the app's business, not core's.
///
/// Name the most precise identity the operator holds — the content root where that IS the answer,
/// or the finer field where the root is coarser than the thing refused. Rendering is the caller's:
/// a key type's own [`Display`](core::fmt::Display) is what a tap correlates against a row, so an
/// app that wants a refusal to be look-up-able renders the identity the same way its keys do.
#[inline]
#[must_use]
pub fn about(mut self, content: impl core::fmt::Display) -> Self {
self.content = Some(Utf8Bytes::from(content.to_string()));
self
}
/// Why the item was refused.
#[inline]
pub const fn reason(&self) -> &SkipReason {
&self.reason
}
/// The content the operator named, or `None` when it named none (see the type docs — `None` is
/// "not stated").
#[inline]
pub fn content(&self) -> Option<&str> {
self.content.as_deref()
}
}
impl From<SkipReason> for Skip {
#[inline]
fn from(reason: SkipReason) -> Self {
Self::new(reason)
}
}
/// One buffered output from an `accept` call: a typed emit or an intentional
/// skip. Typed in `Out` — no erasure is needed because an operator has exactly one
/// output type. A processing failure is *not* an emission: it is the `Err` of
/// [`Operator::accept`], which the driver turns into a `DeadLettered` fate.
#[derive(Debug, derive_more::IsVariant, derive_more::Unwrap, derive_more::TryUnwrap)]
#[unwrap(ref, ref_mut)]
#[try_unwrap(ref, ref_mut)]
pub enum Emission<Out> {
/// Emit `Out` downstream.
Emit(Out),
/// Record an intentional refusal.
Skip(Skip),
}
/// The EMISSION ORGAN handed to each `accept` call: the typed buffer an operator states its
/// outputs into.
///
/// It is named for the one thing it does — `emitter.emit(item)` conjugates the organ's own name —
/// and it does THAT ONE THING. What a body reaches the deployment through is the [`Context`] beside
/// it: the resource door lived here while the emitter was the only seat a call was handed, and it
/// moved the moment a real one existed. This organ carries no borrow, no map and no wind-down line.
///
/// `emit`/`skip` append to an in-order buffer the runtime drains after the call.
///
/// # The buffering obligation (an operator author's contract)
///
/// EVERY emission of one `accept` call is held here until the call returns —
/// the driver drains afterwards, never during. That is exactly right for a
/// fan-out of dozens per item, and catastrophic for a fan-out that grows with
/// the input: a 2 GB log chunked into ~200-character windows is ~10 million
/// buffered emissions inside ONE call, i.e. an out-of-memory abort rather than
/// the dead-letter the failure lane funds.
///
/// So an operator whose per-item fan-out is unbounded in input size MUST bound
/// it. One supported way is to read through a documented cap and refuse the
/// overflow on the intentional-skip channel — emit nothing and
/// `emitter.skip(SkipReason::custom("oversize"))`, which is what
/// [`Emission::Skip`] exists for.
///
/// THE OTHER IS TO WEAR THE OTHER FACE. This paragraph read *or to stream, once an un-buffered
/// execution contract exists (it does not yet)* until that contract was written:
/// [`StreamOperator`] is it, and a body whose fan-out grows with its input belongs there rather than
/// behind a cap here. The cap remains the right answer where the bound is real — an operator that
/// genuinely refuses oversize input — and the face is the right answer where the work is real and
/// only the buffer was the problem. What has NOT changed is that this organ never streams: a body
/// holding this `&mut Emitter` is on the buffered face and pays the obligation above.
///
/// The source-side `Dispatch` buffer is this same shape with its emissions
/// addressed to subscribers, so it inherits this obligation verbatim: a `run`
/// whose batch grows with its input bounds the batch and returns `Flow::Open`
/// for the remainder.
///
/// # THIS ORGAN CANNOT MAKE AN ACKED GIVE, and the obligation above is why
///
/// [`Feed::give_acked`](crate::Feed::give_acked) is a give whose producer WAITS for its consumer's
/// answer. There is no counterpart of it here, and there cannot be one: nothing this organ buffers
/// leaves the node until `accept` has returned and the driver drains, so a future awaited on an
/// emission from inside `accept` could only be resolved by work that this call is itself blocking.
/// It is a DEADLOCK BY CONSTRUCTION rather than a door somebody forgot to write, and it is refused
/// by not existing.
///
/// A body that has to await its consumer's answer is on one of the OWNED producer faces — a
/// [`Feed`], where `give` already leaves the node the moment it is called, or an
/// [`AutonomousOperator`]'s own [`Downstream`](crate::Downstream), where the node holds the loop and
/// its own ack timing. A body on THIS face is on the other end of that protocol: it does not wait
/// for a receipt, it STATES one, through [`receipt`](Self::receipt).
pub struct Emitter<Out> {
emissions: Vec<Emission<Out>>,
wanted: Wanted,
receipt: Option<Box<dyn core::any::Any + Send + Sync>>,
}
impl<Out> Emitter<Out> {
/// An empty buffer with nothing downstream declared.
///
/// What the DRIVER hands an operator is this with the connection state filled in — see
/// [`wanting`](Self::wanting), which is also how an author drives their own operator in a test.
#[inline]
pub const fn new() -> Self {
Self {
emissions: Vec::new(),
wanted: Wanted::none(),
receipt: None,
}
}
/// Declare which of this node's products anything downstream wants.
///
/// [`Wanted::sole`] is the one-product spelling, and what a hand-driven test of a single-product
/// operator writes.
#[inline]
#[must_use]
pub const fn wanting(mut self, wanted: Wanted) -> Self {
self.wanted = wanted;
self
}
/// Whether anything downstream wants ANYTHING this call would emit.
///
/// The connection state, read off the node's own downstream set ([`Sink::connected`](crate::Sink::connected))
/// and carried in here for one call. It is a question worth asking BEFORE the expensive half of a
/// body runs: a product nobody subscribes to is work with no destination, and the honest response
/// is to skip it rather than to emit into a downstream set that has nowhere to put it.
///
/// A node with ONE product has nothing further to ask, and this is its whole read. A node that
/// declared several asks [`wants`](Self::wants) per product — same fact, with the product's
/// identity in hand — and this stays the cheap "is any of it worth doing at all" question above
/// it.
#[inline]
#[must_use]
pub const fn wanted(&self) -> bool {
self.wanted.any()
}
/// Buffer a downstream emit of `item`.
#[inline]
pub fn emit(&mut self, item: Out) {
self.emissions.push(Emission::Emit(item));
}
/// Buffer an intentional refusal: a bare [`SkipReason`], or a [`Skip`] that also names the
/// content it refused.
#[inline]
pub fn skip(&mut self, skip: impl Into<Skip>) {
self.emissions.push(Emission::Skip(skip.into()));
}
/// ANSWER THIS ITEM'S PRODUCER with `receipt` — the value it is waiting for, carried out on the ack.
///
/// # What it is for
///
/// A producer that gave this item through
/// [`Feed::give_acked`](crate::Feed::give_acked) is parked on this delivery's answer, and what it
/// is parked for is usually a DURABLE IDENTITY: a seat upserts the row, the natural key it matched
/// keeps the id it already had, and only the seat knows what that id is. Nothing downstream of
/// here could reconstruct it and nothing upstream could have guessed it, so the answer rides back
/// on the one channel that already goes to exactly the right party.
///
/// # WHEN the producer sees it, and it is not when this is called
///
/// This STAGES, exactly as [`emit`](Self::emit) does. The ack is sent by the driver after the
/// whole landing half has run — the write lane committed, the journal row recorded, the survivors
/// handed to the edges — so a receipt stated here reaches its producer AFTER the row it names is
/// durable. That ordering is the reason a receipt is worth anything: an id the producer stamped onto
/// its own outputs before the row landed would be an id pointing at nothing.
///
/// A body on the buffered face therefore states a receipt and does NOT wait for anything: the
/// waiting is the producer's, one edge over.
///
/// # It does not release, and it does not fail
///
/// Whether this item's key is released is decided by what `accept` ANSWERS, unchanged — a body
/// that states a receipt and then returns `Err` holds the item, and the receipt travels beside a
/// [`Failed`](crate::Lifecycle::Failed) station that says so. The two facts are independent on
/// purpose; see [`Ack::receipting`](crate::Ack::receipting), which is the same law at the transport.
///
/// Calling it twice in one call REPLACES: an answer is stated once per item, and the last word is
/// what the item means.
#[inline]
pub fn receipt<R>(&mut self, receipt: R)
where
R: core::any::Any + Send + Sync,
{
self.receipt = Some(Box::new(receipt));
}
/// [`receipt`](Self::receipt) AT THE TYPE THE MESSAGE DECLARED — the door with teeth.
///
/// `emitter.receipt_of::<SceneOpen>(id)` inside an `accept` body, and the type is not written: it
/// is read off the MESSAGE's own [`Receipts`] impl, which the `receipt = "…"` word on that
/// message's declaration emitted or its author wrote. A value of any OTHER type is `E0308` at the
/// argument, HERE, rather than a [`Unreceipted::Mismatched`](crate::Unreceipted::Mismatched) the
/// producer discovers one edge and one thread away.
///
/// # It names the MESSAGE and not `Self`, which is what the re-key moved
///
/// The seat used to be the consumer's, so this door was written `receipt_of::<Self>` and read the
/// node's own declaration. It reads the item's now — usually `Self::In`, and always the type a
/// producer gave — because the answer belongs to the question, and every seat over one message
/// answers the same question. The turbofish stays because an [`Emitter<Out>`](Emitter) is typed at
/// what this node PRODUCES and carries no trace of what it was handed; the door that could infer
/// is [`Acked::receipt`](crate::Acked::receipt), where the message is in the type.
///
/// It is the same staging as [`receipt`](Self::receipt) and stages the same box — what the
/// declaration buys is the CHECK, not a different value on the wire. A message with no
/// [`Receipts`] impl cannot be named here at all, which is the honest reading of *undeclared*: the
/// open door is still there, and what it still costs is the runtime fate.
#[inline]
pub fn receipt_of<M>(&mut self, receipt: M::Receipt)
where
M: Receipts,
M::Receipt: core::any::Any + Send + Sync,
{
self.receipt(receipt);
}
/// Whether this call has staged a receipt — the read a body with a branch of its own asks, and what
/// a hand-driven test asserts against.
#[inline]
#[must_use]
pub const fn receipted(&self) -> bool {
self.receipt.is_some()
}
/// Take the staged receipt, leaving none — the RUNTIME's own drain of this slot, spent exactly once
/// per `accept` call beside [`drain`](Self::drain).
///
/// `pub(crate)` for [`drain`](Self::drain)'s reason, and only that reason: what privacy protects
/// here is who TAKES, not who looks, and [`receipted`](Self::receipted) is the look.
#[inline]
pub(crate) fn take_receipt(&mut self) -> Option<Box<dyn core::any::Any + Send + Sync>> {
self.receipt.take()
}
/// Read what has been buffered so far, without draining it — every emission staged by this call,
/// in order.
///
/// The BORROW half of the public read: what an external test asserts against after driving an
/// `accept`, with no per-operator side door required. `Emitter::new().wanting(…)`, one `accept`
/// call, then this — the whole shape a hand-driven test needs, and [`Emission`]'s own variants
/// ([`is_emit`](Emission::is_emit), [`unwrap_emit_ref`](Emission::unwrap_emit_ref), and their
/// `Skip` counterparts) are already public, so nothing else had to widen to make it readable.
///
/// # Why a read is safe where [`drain`](Self::drain) stays `pub(crate)`
///
/// What privacy protected here was never WHO LOOKS — it is WHO DRAINS. The driver owns the
/// `Emitter` value for the call's duration and an operator holds only `&mut Emitter<Out>`
/// inside `accept`, so a shared read crosses no discipline the buffering obligation depends on:
/// nothing downstream of `accept` can observe a different buffer than the one the driver drains
/// next. Only the CONSUMING move — taking the buffer out of the driver's hands before it drains —
/// is the runtime's own, which is exactly what `drain` still is and this is not.
///
/// See [`into_emissions`](Self::into_emissions) for the same read, taken by value.
#[inline]
#[must_use]
pub fn emissions(&self) -> &[Emission<Out>] {
&self.emissions
}
/// Consume the organ and return its buffered emissions in order — the PUBLIC counterpart of the
/// driver's own [`drain`](Self::drain).
///
/// Same buffer, same order, same value `drain` would have produced: this is how code outside the
/// crate takes ownership of the result of a hand-driven `accept` without a per-operator side door.
/// See [`emissions`](Self::emissions) — and that method's own docs — for the borrowing half of the
/// same read, and for why a public read costs the buffering discipline nothing even though `drain`
/// itself stays `pub(crate)`.
#[inline]
#[must_use]
pub fn into_emissions(self) -> Vec<Emission<Out>> {
self.emissions
}
/// Consume the organ and return its buffered emissions in order. Called by
/// [`Resident`](crate::Resident) after each `accept`, on the `Ok` and `Err` paths alike.
///
/// Stays `pub(crate)`: this is the RUNTIME's own drain, spent exactly once per `accept` call. A
/// caller outside the crate wants [`into_emissions`](Self::into_emissions) (owned) or
/// [`emissions`](Self::emissions) (borrowed) instead — see the former's docs for why a public read
/// crosses no discipline this one depends on.
#[inline]
pub(crate) fn drain(self) -> Vec<Emission<Out>> {
self.emissions
}
}
/// The per-product read, and it exists only where there ARE several products.
///
/// The bound is the whole of the type safety: `Out::Kind` is the emitted `<Node>OutKind` of THIS
/// node, so another node's product vocabulary is not spellable here — the wrong word is `E0308` at
/// the call, not a mask read at an index that means something else.
impl<Out> Emitter<Out>
where
Out: Products,
{
/// Whether anything downstream wants the product `kind` names.
///
/// [`wanted`](Self::wanted) is the same read over every product at once; this is the one a body
/// with an expensive branch per product asks before it takes the branch.
#[inline]
#[must_use]
pub fn wants(&self, kind: Out::Kind) -> bool {
self.wanted.at(kind.index())
}
}
impl<Out> Default for Emitter<Out> {
#[inline]
fn default() -> Self {
Self::new()
}
}
/// A node's product FAMILY: the emitted `<Node>Out` enum, and the vocabulary naming its arms.
///
/// Implemented by the emission and by nothing else — a node that declares several products gets
/// `<Node>Out` (the value on the edge's near side) and `<Node>OutKind` (the identity), and this is
/// the link between them. A one-product node has no family: its `Out` is the product, and
/// [`Emitter::wanted`] is the whole of its connection state.
pub trait Products {
/// The product identity — the emitted `<Node>OutKind`.
type Kind: ProductKind;
}
/// One node's product vocabulary: a closed set of identities, ordered as the declaration wrote
/// them.
///
/// [`index`](Self::index) is the position `emits` put the product at, and it is the ONE
/// numbering the whole system uses — the [`Wanted`] bit, the downstream set's edge, the
/// [`Emits`] projection a downstream subscription is spelled through. The variant is what an author
/// writes; the index is what the machinery counts on; the emission is the only party that maps
/// between them.
pub trait ProductKind: Copy + Eq {
/// How many products the node declared.
const COUNT: usize;
/// This product's position in declaration order, counting from zero.
fn index(self) -> usize;
}
/// The Nth product a node emits, in declaration order — the projection a SUBSCRIPTION is spelled
/// through.
///
/// Two derives cannot see each other, so a downstream declaration naming `media::Frame` cannot know
/// what a `Frame` puts on the wire. This is where it asks: the upstream's own expansion states the
/// answer, and the downstream's emitted `In` enum carries `<media::Frame as Emits>::Out` — the
/// compiler meets the two at the string the author wrote.
///
/// The default index is zero, so a node with one product is `Emits` unadorned. A node with several
/// implements one row per product, and a downstream selecting among them writes the index its
/// `<Node>OutKind` already names:
///
/// ```text
/// <vision::Detector as Emits<{ vision::DetectorOutKind::Boxes as usize }>>::Out
/// ```
///
/// The variant is what the declaration wrote (`out = "Boxes"`) and stays rename-proof; the ordinal
/// is what crosses the wall between the two expansions.
pub trait Emits<const N: usize = 0> {
/// The message this product puts on an edge.
type Out;
}
/// A node that emits exactly ONE product — the audit an unselected subscription discharges.
///
/// A subscription that names no product is only well formed where there is one product to name.
/// The upstream's expansion carries this marker exactly when that is true, so a declaration
/// subscribing to a multi-product node without `out = "…"` is `E0277` at the string it wrote,
/// rather
/// than a silent binding to whichever product happened to be declared first.
#[diagnostic::on_unimplemented(
message = "`{Self}` does not emit ONE product, so a subscription cannot leave the product unsaid",
label = "this node declares several products",
note = "name the one this edge carries: `upstream(node = \"…\", out = \"<Variant>\")`",
note = "the products are the variants of that node's emitted `…OutKind`"
)]
pub trait SoleProduct: Emits {}
/// **WHAT THIS MESSAGE'S RECEIPT IS** — the type a consumer hands back for one item of it, declared
/// once by the message that is GIVEN.
///
/// The ack says the item LANDED; the receipt says what it landed AS. A seat upserts the row, the
/// natural key it matched keeps the id it already had, and only the seat knows what that id is — so
/// the value rides back on the one channel that already goes to exactly the right party
/// ([`Emitter::receipt`], [`Ack::receipting`](crate::Ack::receipting), and the producer's
/// [`Acked`](crate::Acked)). This trait is where the two ends of that channel learn to name the
/// SAME type without either of them writing it twice.
///
/// ```ignore
/// impl Receipts for SceneOpen {
/// type Receipt = SceneId;
/// }
/// ```
///
/// # The self type is the MESSAGE, and that is the whole ruling
///
/// The seat shipped keyed on the NODE — `impl Receipts for Scene`, the consumer stating what IT
/// hands back — and the subject was wrong. A receipt answers the item that was GIVEN, so the
/// question belongs to what was given: one message asks one question, and every seat on the far end
/// of that edge answers the same one. Keyed on the node, two seats over one message each declared
/// the answer's type and the two could disagree about a question neither of them asked; keyed on
/// the message there is one declaration and nothing to keep in step.
///
/// What it buys the PRODUCER is the inference, and the inference is the point:
/// `feed.give_acked(open)?.receipt()` projects `<SceneOpen as Receipts>::Receipt` off the message it
/// just gave — no turbofish, no node named, and it reads the same from any [`Feed`](crate::Feed)
/// whatever is mounted downstream. A producer cannot name the consumer of its own edge. It always
/// knows what it gave.
///
/// # It is a SIBLING trait and not a member of anything
///
/// A `type Receipt = ();` seat on [`Operator`] itself was the first shape tried, and the language
/// refuses it: **associated-type defaults are unstable (`E0658`)**, so the seat could not be
/// defaulted — and an undefaulted member is a line every declaration in this tree would have to
/// write to say a thing almost none of them does. The same wall is written down one layer over at
/// [`Declared::Pair`](crate::Declared), where the cost was accepted because a pair is a fact EVERY
/// declaration has; a receipt is a fact almost none has, and the two answers differ for exactly
/// that reason.
///
/// The three roads that were refused, and why:
///
/// - **the defaulted member** — `E0658`, above. It is not a matter of taste;
/// - **an undefaulted member** — every declaration pays a line for a seat it leaves empty, and a
/// seat every author fills with the same nothing is ceremony rather than a declaration;
/// - **a runtime registry** — a map from message to receipt type, filled at launch. It moves the
/// mistake from compile time to start-up and gives the compiler nothing to check.
///
/// What is left is the OPT-IN SIBLING: a message that is waited on states one impl, a message that
/// is not writes nothing at all, and the seat still lands in the type system where a projection can
/// read it. Zero ceremony for every message nobody waits on is not a side effect of this shape — it
/// is the whole of why the shape was chosen.
///
/// # Two roads to the impl, and both are first class
///
/// The `receipt = "…"` word on a MESSAGE-MINTING declaration — `#[ingraph::entity(receipt = "…")]`,
/// with `record` and `aggregate` beside it — emits exactly the impl above, and it is the DEFAULT
/// road. Writing the impl by hand is equally legal and equally complete, and it is the road a
/// GENERIC framework message has to take: a message carrying a parameter of its own — a scene handle
/// whose type the mounting application chooses — has no concrete path a quoted word could name, and
/// says `impl<S> Receipts for SceneOpen<S> { type Receipt = S; }` instead. The word reaches every
/// message whose answer is a type somebody wrote down; the hand impl reaches the rest.
///
/// The word is a DECLARATION rather than a restatement — there is no other place a declaration could
/// state its receipt — so it does not fall under the rule that bars a macro word from repeating a
/// fact an impl already carries. It is refused by name on a declaration that mints no message: an
/// operator computes and puts its `Out` on the edge rather than itself, and a derived index carries
/// an upstream's key, so neither has an item a producer could be parked on.
///
/// # WHAT THE SEAT BUYS: five doors that stop guessing, and one that no longer needs a door
///
/// Each is the `_of` twin of a door that already existed, and every one of them names the MESSAGE
/// where its sibling named a TYPE. Same slot, same box, same wire — the declaration replaces a
/// turbofish the caller invented with a projection the compiler resolves:
///
/// | side | open door | declared twin |
/// |---|---|---|
/// | buffered body | [`Emitter::receipt`] | [`Emitter::receipt_of`] |
/// | transport answer | [`Ack::receipting`](crate::Ack::receipting) | [`Ack::receipting_of`](crate::Ack::receipting_of) |
/// | obligation | [`Owed::receipt`](crate::Owed::receipt) | [`Owed::receipt_of`](crate::Owed::receipt_of) |
/// | whole answer | [`Settled::receipt`](crate::Settled::receipt) | [`Settled::receipt_of`](crate::Settled::receipt_of) |
/// | harvest | [`Answered::receipt`](crate::Answered::receipt) | [`Answered::receipt_of`](crate::Answered::receipt_of) |
///
/// **FIVE and not six, and the missing row is the producer's.** [`Acked<M>`](crate::Acked) carries
/// the message it was opened with, so [`Acked::receipt`](crate::Acked::receipt) IS the declared door
/// — there is no turbofish left for an `_of` twin to remove, and the three that existed
/// (`receipt_of`, `receipt_of_within`, `receipt_of_async`) are gone rather than kept as aliases. The
/// five above keep theirs for the opposite reason: each hangs off a `K`-keyed answer that names no
/// message type at all, so the one door that COULD infer is the one that does.
///
/// The three STATING doors span both faces on purpose: a buffered body reaches `Emitter`, and a
/// [`StreamOperator`] body — which is handed its delivery's custody and never sees an `Emitter` —
/// reaches `Ack` or `Owed`. A seat only the buffered face could use would have left the streamed
/// half of the framework unable to be checked at all.
///
/// # WHAT IT DOES NOT BUY, stated so nothing here is read as more than it is
///
/// **The wire is still `dyn Any`.** The box crosses erased whatever any declaration says — that is
/// [`Settled`](crate::Settled)'s own law, and it is what lets one edge's consumers each name their
/// own type — so [`Unreceipted::Mismatched`](crate::Unreceipted::Mismatched) is still reachable and
/// is still the right answer. What the seat removes is the GUESS, not the erasure: the type is no
/// longer something either end invents, so the two ends can no longer disagree by typo. Where a
/// message declared nothing, the open doors are exactly what they were.
///
/// **And a seat still has to STATE its answer.** The declaration says what the answer's type is; it
/// does not make a consumer produce one. A seat that stays silent over a message that declares a
/// receipt is [`Unreceipted::Silent`](crate::Unreceipted::Silent) at the producer, by name and
/// without hanging — which is the honest report of a graph whose landing seat is not wired.
///
/// # [`Notified`](crate::Notified) is a DIFFERENT AXIS, not a restatement
///
/// [`Notified`](crate::Notified) is the DOWNSTREAM's choice — whether a consumer's edge carries the
/// whole message or only the landed key — and it is spelled `notify` in the grammar, matching its
/// own name. This is the UPSTREAM's answer, travelling backward along the ack of a give that asked
/// for one. Nothing reads both.
pub trait Receipts {
/// The value a consumer hands back to the producer of an acked give OF THIS MESSAGE.
type Receipt;
}
/// A compute unit: turns the messages it is DELIVERED into the ones it produces.
///
/// # The contract is `accept`, and this face is SYNCHRONOUS
///
/// TWO MODES, one per face. This trait is the blocking one and [`AsyncOperator`] is the other, which
/// is the framework's naming axis read at the compute seam — `Async*` is the asynchronous face, the
/// BARE name is the blocking one, exactly as [`Lands`](crate::Lands) /
/// [`AsyncLands`](crate::AsyncLands) and [`Tick`](crate::Tick) / [`AsyncTick`](crate::AsyncTick)
/// already read one layer down.
///
/// This trait once carried the async signature alone, with a note recording that a sync-looking dual
/// face had been *measured and refused*. THAT MEASUREMENT WAS TAKEN AGAIN AND IT REFUTES THE NOTE:
/// **105 `accept` bodies in this tree, and not one of them contains an `.await`.** The count that
/// ruled the split found 87 `impl Operator` sites on a smaller tree — 48 in `src`, 39 in tests — at
/// the same ratio of zero, so the tree grew and the ratio did not. The async face was therefore not
/// a shared contract at all; it was ceremony every unit paid and no unit spent. The single mode is
/// retired, and what replaced it is a PAIR: an author writes the face the body actually has, and the
/// driver spends it four ways — see [the matrix](crate::Drives).
///
/// Neither face carries a **`Send` bound**, deliberately. Mobility belongs to the engines: a `!Send`
/// unit is an ordinary citizen on the thread engine, and the async engine's own door is where
/// `Send` is asked for. An author declares nothing about it; the type answers.
///
/// # What a call is handed
///
/// A [`Delivery`] of the messages to process and an [`Emitter`] to state the results into. The
/// driver hands ONE item per call today — the release protocol is per item, so a failed item holds
/// its own key while its neighbours are released, and the walk over a batch is therefore the
/// driver's. A body written as a walk over its delivery is what keeps compiling when the ruled
/// full-custody contract hands the whole batch across:
///
/// ```
/// use ingraph::{Context, Delivery, Emitter, Item, Operator};
///
/// struct Doubling;
///
/// impl Operator for Doubling {
/// type In = u64;
/// type Out = u64;
/// type Error = core::convert::Infallible;
///
/// fn accept(
/// &mut self,
/// ctx: &Context,
/// delivery: Delivery<u64>,
/// emitter: &mut Emitter<u64>,
/// ) -> Result<(), Self::Error> {
/// for item in delivery.into_items() {
/// emitter.emit(item.into_value() * 2);
/// }
/// Ok(())
/// }
/// }
/// ```
///
/// The answer is a `Result` and NOT a future, which is the whole of what this face buys: the thread
/// engine calls it and takes the answer, minting nothing for a driver to poll.
///
/// ```compile_fail
/// use ingraph::{Delivery, Emitter, Operator};
/// # struct Doubling;
/// # impl Operator for Doubling {
/// # type In = u64;
/// # type Out = u64;
/// # type Error = core::convert::Infallible;
/// # fn accept(&mut self, ctx: &Context, _: Delivery<u64>, _: &mut Emitter<u64>) -> Result<(), Self::Error> { Ok(()) }
/// # }
/// # async fn awaited(unit: &mut Doubling, delivery: Delivery<u64>, emitter: &mut Emitter<u64>) {
/// let _ = unit.accept(delivery, ctx).await; // a `Result` is not a future
/// # }
/// ```
///
/// # Failure
///
/// `accept` returns `Result<(), Self::Error>`, and `Err` is the *single* failure
/// channel: it dead-letters the item being processed. Emissions already
/// buffered into `ctx` before the error are still delivered — the driver drains the
/// buffer first, exactly as on the `Ok` path — then records a `DeadLettered` fate at
/// this node and CONTINUES with the next item: one bad frame must not kill a
/// pipeline. A fatal, can't-continue condition is deliberately NOT expressible
/// through `Err`; that escalation belongs to the future supervision layer.
///
/// The semantics are the pair's and not this face's: [`AsyncOperator`] states the same failure
/// channel, the same buffering obligation and the same per-item walk, because the only difference
/// between the two is whether the answer has to be awaited.
pub trait Operator {
/// The message this unit consumes — the declared struct an edge moves.
type In;
/// The message this unit produces — the declared struct an edge moves.
type Out;
/// This operator's per-item failure. Bound-free here: the runtime driver bounds
/// it (`Error + Send + Sync + 'static`) at its own call site, and it is not part
/// of edge compatibility — errors flow to fates, never along edges.
type Error;
/// Take `delivery`, stating any outputs into `ctx`; return `Err` to dead-letter it
/// (see the trait docs for the failure semantics).
///
/// `ctx.emit` STAGES — it is a push into a buffer and never awaits — and the driver drains
/// that buffer into the downstream set afterwards. So an operator cannot deadlock on its own full output:
/// the wait for room belongs to the party that owns the loop.
///
/// It keeps the BARE name that [`AsyncOperator::accept`] also carries, for
/// [`Lands::land`](crate::Lands::land)'s measured reason: a body that imports one face calls
/// `accept` with no ceremony, and a type wearing BOTH is `E0034` naming the two candidates and
/// offering the disambiguating spelling. A suffixed second name would buy silence at that one
/// site and charge every other site a word the trait's own name already says.
fn accept(
&mut self,
ctx: &Context,
delivery: Delivery<Self::In>,
emitter: &mut Emitter<Self::Out>,
) -> Result<(), Self::Error>;
}
/// [`Operator`]'s ASYNCHRONOUS face — the same compute unit, for a body that has an `.await` to
/// spend.
///
/// Everything [`Operator`] states holds here verbatim: the same [`Delivery`], the same [`Emitter`]
/// and its buffering obligation, the same one-item-per-call walk, the same single failure channel,
/// the same absence of a `Send` bound. THE ONLY DIFFERENCE IS THAT THE ANSWER IS A FUTURE.
///
/// # It ships with no implementor in this tree, and that is the honest state
///
/// The census that split the pair found 105 `accept` bodies and zero `.await`s among them, so every
/// unit here is on the blocking face and this one carries the contract for the bodies that are
/// coming — a lane that awaits a socket, a model behind an async client — rather than for a body
/// that is already written. Naming a consumer it does not have would be an invention; the four
/// driving cells are proved instead ([`Drives`](crate::Drives)), which is what a face needs to be
/// usable.
///
/// # Why a PAIR and not a defaulted second verb
///
/// The dual-mode law: an author implements EXACTLY ONE face, and the bound is what says which. A
/// single trait carrying both verbs would make every unit answer a question it has no body for, and
/// a blanket bridge from one face to the other would hand every blocking unit an async face and
/// blind the bound that selects — the driver could no longer tell, from a type, whether a call
/// mints a future. The framework-internal exemption that lets [`Intake`](crate::Intake) carry two
/// verbs on one trait does not reach here: an intake's implementor must serve both engines at once
/// and cannot know which will drive it, while a unit's body is written one way and knows.
///
/// ```
/// use ingraph::{Context, AsyncOperator, Delivery, Emitter, Item};
///
/// struct Doubling;
///
/// impl AsyncOperator for Doubling {
/// type In = u64;
/// type Out = u64;
/// type Error = core::convert::Infallible;
///
/// async fn accept(
/// &mut self,
/// ctx: &Context,
/// delivery: Delivery<u64>,
/// emitter: &mut Emitter<u64>,
/// ) -> Result<(), Self::Error> {
/// for item in delivery.into_items() {
/// emitter.emit(item.into_value() * 2);
/// }
/// Ok(())
/// }
/// }
/// ```
#[diagnostic::on_unimplemented(
message = "`{Self}` has no AWAITED `accept`",
label = "this face is not the one this unit wears",
note = "the `async` word on a declaration names the face its body has, so the impl beside it \
must be `AsyncOperator`; an `Operator` impl is the BLOCKING face, which is what a bare \
declaration asks for",
note = "either give the body an `AsyncOperator` impl, or drop the word and keep the blocking one"
)]
pub trait AsyncOperator {
/// The message this unit consumes — the declared struct an edge moves.
type In;
/// The message this unit produces — the declared struct an edge moves.
type Out;
/// This operator's per-item failure. Bound-free here, for [`Operator::Error`]'s reason.
type Error;
/// [`Operator::accept`], answering a future the engine drives — the thread engine to completion
/// on the thread the node owns, the async engine by awaiting it.
fn accept(
&mut self,
ctx: &Context,
delivery: Delivery<Self::In>,
emitter: &mut Emitter<Self::Out>,
) -> impl Future<Output = Result<(), Self::Error>>;
}
/// A compute unit whose ONE DELIVERY IS A WHOLE LIFE: it streams its outputs through a bounded
/// [`Feed`] as it produces them, for as long as that delivery lasts.
///
/// # THE FACE-SELECTION LAW — this pair's own row, and what divides it from its neighbours
///
/// There are THREE kinds and the law reads on two questions rather than one.
/// [`AutonomousOperator`] is where the whole three-row table is written; what this section states is
/// the question that divides THESE TWO — the per-delivery pairs, where the framework runs the loop
/// and keeps the books — from each other, which is the FAN-OUT.
///
/// [`Operator`] BUFFERS, and [`Emitter`]'s own note is where the wall is named: every emission of one
/// `accept` call is held until the call returns. That is exactly right for a fan-out of dozens per
/// item, and CATEGORICALLY wrong for one that grows with the input — a two-hour container demuxed to
/// packets, a 2 GB log chunked into ~200-character windows, which is millions of emissions held
/// inside ONE call, i.e. an out-of-memory abort rather than the dead-letter the failure lane funds.
/// It is wrong at any price, so no capacity tuning is the answer and a second face is.
///
/// The law is therefore a question about the FAN-OUT, and never about a body's size or its cost:
///
/// | the fan-out one delivered item produces | the face its body wears |
/// |---|---|
/// | BOUNDED in the input — one, a handful, dozens | [`Operator`] / [`AsyncOperator`] |
/// | GROWS with the input's length — a demux, a chunker, a whole-track session | `StreamOperator` / [`AsyncStreamOperator`] |
///
/// Every body already in this tree is on the first row and not one of them moves: a face is chosen
/// PER NODE, and the kinds are peers rather than a ladder. A body that needs neither answer — one
/// that has to own its select order, its intake gating or its ack timing — is on the third kind, and
/// [`AutonomousOperator`] is where that row is stated.
///
/// # The PER-DELIVERY life, and residency is the POOL's
///
/// `run` is one delivery's whole life — the first item to the last — and then it returns and the next
/// delivery gets its own call. That is the whole of what separates it from an origin's
/// [`run`](crate::Source::run), which is the LINE's whole life: this face takes `&mut self` where
/// that one takes `self`, because here there IS something after it.
///
/// What the face does NOT carry is residency. N warm instances, an admission bound on how many
/// deliveries are in flight at once, which thread does the heavy half — all of it is the POOL's
/// property, arranged by the lane that drives this face, and none of it is spelled here. A body keeps whatever
/// state it likes across deliveries (a decoder, an open handle, a scratch buffer) and learns nothing
/// about how many of itself there are: there is no `Intake` seat, no per-instance identity, and no
/// ordering promise between two concurrent deliveries beyond what the lane's own routing states.
///
/// # The ENDINGS are the origin layer's, reused verbatim
///
/// The origin layer's own words, reused with NOTHING added: [`Fin`] is the enum
/// [`Source::run`](crate::Source::run) answers with, and [`Unfed`](crate::Unfed) is the refusal
/// [`give`](Feed::give) hands back there. A run that reached the end of its delivery is
/// [`Fin::Spent`]; one that heard [`ShutdownSignal`] and wound down is [`Fin::Stopped`]; an item the drain
/// would not take comes back inside an [`Unfed`](crate::Unfed), which a body usually reads as the
/// second ending — nothing is left to stream to. A stream-specific endings enum was drafted and
/// REFUSED: its one extra fact is one the fate payload already carries, and a second vocabulary is a
/// `match` arm every deployment would have to learn twice.
///
/// | what happened | what `run` answers |
/// |---|---|
/// | streamed the delivery to its end | `Ok(`[`Fin::Spent`]`)` |
/// | heard the stop, or the drain hung up, and wound down | `Ok(`[`Fin::Stopped`]`)` |
/// | FAILED — it neither finished nor was stopped | `Err(Self::Error)` |
///
/// # What `Err` COSTS, and what it does not
///
/// `Err` dead-letters THE DELIVERY — the whole of it, with the error and the identity aboard. That is
/// the same granularity [`Operator::accept`]'s `Err` has, read at this face's own item: a stream
/// item simply IS a whole delivery. So, in the four parts an author has to be able to count on:
///
/// - the POOL IS NOT POISONED and the node does not stop. The next delivery proceeds, exactly as the
/// next item does one face over — one bad file must not kill a pipeline.
/// - EVERYTHING ALREADY GIVEN STANDS. Those products crossed the feed before the failure and are
/// valid independently of it; nothing recalls them, because a run that died halfway made real
/// outputs for the half it got through.
/// - THE FAILURE SCENE rides `Self::Error` — how far the read got, which positions were reached —
/// into the fate payload. That is why no ending arm was minted for it: the author's own error type
/// already says more than an arm could.
/// - RETRY IS THE APP'S. Nothing here re-runs a dead-lettered delivery, and what a retry would even
/// mean is a question only the app that minted the identity can answer.
///
/// A fatal, can't-continue condition is deliberately NOT expressible through `Err`, exactly as at
/// [`Operator::accept`]: that escalation belongs to the supervision layer.
///
/// # BACKPRESSURE IS THE CONTRACT — `give` blocking is the feature
///
/// [`Feed`] is bounded and [`give`](Feed::give) WAITS for room, so a body producing faster than the
/// graph consumes is slowed by its own next `give` and by no bookkeeping of its own. That is the
/// entire mechanism, and it is why this signature carries no capacity knob: the wait reaches back
/// through the drain to the read, which is [`Feed`]'s own note one layer down.
///
/// A body that would rather do something else than wait has [`try_give`](Feed::try_give), and the
/// choice is the caller's because only the caller knows what that something else is. What a body
/// must NOT do is buffer the overflow itself — that reinstates, one level up, the exact wall this
/// face exists to get past.
///
/// # `type Out: 'static`, which is what the [`Feed`] costs
///
/// [`Source::Yield`](crate::Source::Yield)'s bound, stated where this face's author meets it: a fed
/// item crosses a channel into a party scheduled independently of the one that made it, so it cannot
/// borrow from the run's own stack. `In` and `Error` stay bound-free, per [`Operator`]'s discipline.
///
/// # `Send`, and this face asks for nothing
///
/// [`Operator`]'s law verbatim: mobility belongs to the engines. A `!Send` body is an ordinary
/// citizen wherever the lane can place it, and the lane's own door is where `Send` is asked for. An
/// author declares nothing about it; the type answers.
///
/// # The honest state: THE FACE, THE LANE, THE WORD AND THE ROOT ARE ALL HERE — the ENGINE is not
///
/// Four rounds built this contract, each shipping one piece in the order that let the piece before
/// it be read on its own:
///
/// | piece | what it is |
/// |---|---|
/// | the FACE | this trait and [`AsyncStreamOperator`], with nothing driving them |
/// | the LANE | [`StreamLane`](crate::StreamLane) — the warm set, the admission bound, a [`Feed`] cut per delivery, the projection drain — over [`Streams`](crate::Streams), which is [`Driven`]'s shape one seam over |
/// | the WORD | `#[ingraph::operator(stream, …)]`, which demands this face at the declaration, seats [`Declared::Pair`](crate::Declared::Pair) at [`Streaming`](crate::Streaming), and puts the node at [`Blueprint::stream`](crate::Blueprint::stream) and [`Wiring::lane`](crate::Wiring::lane) rather than at the buffered pair's two doors |
/// | the ROOT | [`Mount`](crate::Mount) — the cell a declaration's two words select, so that the ONE line `#[ingraph::graph]` emits per field mounts either pair, and a stream node stands in a root beside the buffered ones |
///
/// So a declared stream node is MOUNTED by the framework, and by the converged `Root::launch` too:
/// the arrangement is joined from the node's own declared facts, and the wiring walk builds its lane
/// against the declared downstream set, at the node's own name and effect, under the seats its
/// deployment's section states, observing through the deployment's taps.
///
/// **What is still open is the ENGINE.** No ignition door puts a loop under a mounted lane, so the
/// party that holds one drives it — [`admit`](crate::StreamLane::admit) per delivery, then
/// [`tend`](crate::StreamLane::tend) and [`drain`](crate::StreamLane::drain) — which is the launch
/// floor's own standing posture for everything whose type it cannot name. A root therefore HANDS the
/// lane over rather than starting it: [`App::lane`](crate::App::lane) is where a deployment takes
/// the mounted lane, its inbox and its enrolment, and drives the cycle itself.
///
/// Shipping the contract first is [`AsyncOperator`]'s shape and it is deliberate: a face is what an
/// author writes against, and one that arrived welded to its machinery would never have been read on
/// its own.
///
/// # Examples
///
/// ```
/// use ingraph::{Context, Delivery, Feed, Fin, Item, ItemId, Payload, ShutdownSignal, StreamOperator};
///
/// /// A chunker: one delivered document becomes as many windows as it has room for — a fan-out that
/// /// grows with the input, which is what puts it on this face.
/// struct Windows {
/// width: usize,
/// }
///
/// impl StreamOperator for Windows {
/// type In = String;
/// type Out = String;
/// type Error = core::convert::Infallible;
///
/// fn run(
/// &mut self,
/// ctx: &Context,
/// delivery: Delivery<String>,
/// feed: Feed<String>,
/// ) -> Result<Fin, Self::Error> {
/// for item in delivery.into_items() {
/// for window in item.into_value().into_bytes().chunks(self.width) {
/// if ctx.shutdown().is_shutdown() {
/// return Ok(Fin::Stopped);
/// }
/// // `give` WAITS for room — that wait IS the backpressure — and refuses only where the
/// // drain has hung up, which is nothing left to stream to.
/// if feed.give(String::from_utf8_lossy(window).into_owned()).is_err() {
/// return Ok(Fin::Stopped);
/// }
/// }
/// }
/// Ok(Fin::Spent)
/// }
/// }
///
/// let (feed, yielded) = ingraph::feed(8);
/// let (_stopper, stop) = ingraph::shutdown_signal();
/// let ctx = Context::new("windows").halting(stop);
/// let delivery = Delivery::in_custody(Payload::One(Item::new(ItemId::new(0), "abcdefg".to_owned())));
///
/// assert_eq!(Windows { width: 3 }.run(&ctx, delivery, feed), Ok(Fin::Spent));
/// assert_eq!(yielded.drain().collect::<Vec<_>>(), ["abc", "def", "g"]);
/// ```
///
/// The answer is a [`Fin`] and NOT a future, which is what this half of the pair buys — the same
/// fact [`Operator`] states one trait up:
///
/// ```compile_fail
/// use ingraph::{Delivery, Feed, Fin, ShutdownSignal, StreamOperator};
/// # struct Windows;
/// # impl StreamOperator for Windows {
/// # type In = String;
/// # type Out = String;
/// # type Error = core::convert::Infallible;
/// # fn run(&mut self, ctx: &Context, _: Delivery<String>, _: Feed<String>) -> Result<Fin, Self::Error> {
/// # Ok(Fin::Spent)
/// # }
/// # }
/// # async fn awaited(unit: &mut Windows, ctx: &Context, delivery: Delivery<String>, feed: Feed<String>) {
/// let _ = unit.run(ctx, delivery, feed).await; // a `Result` is not a future
/// # }
/// ```
#[diagnostic::on_unimplemented(
message = "`{Self}` has no streaming `run`",
label = "this face is not the one this unit wears",
note = "the `stream` word on a declaration names the PAIR its body wears, so the impl beside a \
streaming declaration must be `StreamOperator` — one `run` per delivery, streaming its \
outputs through a bounded `Feed` for that delivery's whole life",
note = "the face is chosen by the FAN-OUT one delivered item produces: bounded in the input is \
`Operator` / `AsyncOperator`, which is what a declaration without the word asks for, and \
growing with the input's length is this pair",
note = "write `async` beside `stream` where the body is the awaited one, which is \
`AsyncStreamOperator`"
)]
pub trait StreamOperator {
/// The message this unit consumes — the declared struct an edge moves.
type In;
/// The message this unit streams out — the declared struct an edge moves.
///
/// `'static`, per the trait's own note: what the [`Feed`] carries outlives the call that made it.
type Out: 'static;
/// This unit's per-DELIVERY failure. Bound-free here, for [`Operator::Error`]'s reason, and it is
/// also the carrier of the failure scene — see the trait docs.
type Error;
/// STREAM `delivery` out through `feed`, until it is spent or `stop` says wind down.
///
/// `feed.give` WAITS — it is the backpressure and never a buffer — and the line CLOSES when this
/// call returns, because the `Feed` was taken by value and is dropped with the run. So a drain
/// reading the far end sees the end of one delivery's stream without being told about it
/// separately.
///
/// It keeps the BARE name that [`AsyncStreamOperator::run`] also carries, for
/// [`Operator::accept`]'s measured reason: a body that imports one face writes `run` with no
/// ceremony, and a type wearing BOTH is `E0034` naming the two candidates and offering the
/// disambiguating spelling. The name is [`Source::run`](crate::Source::run)'s too, and that costs
/// nothing — they are different traits, and a type wearing one of each is disambiguated by the
/// same `E0034` spelling.
///
/// # Errors
///
/// Whatever this unit's own life refuses with — a run that DIED rather than ending. Both endings
/// are `Ok`, and the trait's own table is where the three outcomes are set beside each other.
fn run(
&mut self,
ctx: &Context,
delivery: Delivery<Self::In>,
feed: Feed<Self::Out>,
) -> Result<Fin, Self::Error>;
}
/// [`StreamOperator`]'s ASYNCHRONOUS face — the same per-delivery life, for a body that has an
/// `.await` to spend.
///
/// Everything [`StreamOperator`] states holds here verbatim: the same [`Delivery`], the same bounded
/// [`Feed`] and the backpressure that IS its contract, the same [`ShutdownSignal`], the same [`Fin`] endings
/// reused from the origin layer, the same whole-delivery `Err` with the pool left unpoisoned and the
/// already-given products standing, the same pool-owned residency, the same `'static` on `Out` and
/// the same absence of a `Send` bound. THE ONLY DIFFERENCE IS THAT THE ANSWER IS A FUTURE — and
/// [`give_async`](Feed::give_async) is the door a body parks the wait for room on, where the blocking
/// face blocks a thread on [`give`](Feed::give).
///
/// # It ships with no implementor in this tree, and that is the honest state
///
/// [`AsyncOperator`]'s state exactly, and for its reason rather than a sharper one: BOTH halves of
/// this pair are mountable now — `#[ingraph::operator(stream, async, …)]` selects this half,
/// [`Wiring::lane`](crate::Wiring::lane) builds the lane that drives it, and a
/// `#[ingraph::graph]` root mounts one beside its buffered nodes — and what this face still
/// has no example of is a real BODY. The census that split the compute pair found 105 `accept`
/// bodies and zero `.await`s among them, and this face carries the contract for the bodies that are
/// coming — a demux over an awaited reader, a chunker pulling from an async client — rather than for
/// one already written. Naming a consumer it does not have would be an invention; the lane's own
/// awaited row is proved instead, which is what a face needs to be usable.
///
/// # Why a PAIR and not a defaulted second verb
///
/// The dual-mode law, stated in full at [`AsyncOperator`]: an author implements EXACTLY ONE face, and
/// the bound is what says which. A single trait carrying both verbs would make every unit answer a
/// question it has no body for, and a blanket bridge from one face to the other would hand every
/// blocking unit an async face and blind the bound that selects — the driver could no longer tell,
/// from a type, whether a call mints a future.
///
/// ```
/// use ingraph::{Context, AsyncStreamOperator, Delivery, Feed, Fin, ShutdownSignal};
///
/// struct Windows {
/// width: usize,
/// }
///
/// impl AsyncStreamOperator for Windows {
/// type In = String;
/// type Out = String;
/// type Error = core::convert::Infallible;
///
/// async fn run(
/// &mut self,
/// ctx: &Context,
/// delivery: Delivery<String>,
/// feed: Feed<String>,
/// ) -> Result<Fin, Self::Error> {
/// for item in delivery.into_items() {
/// for window in item.into_value().into_bytes().chunks(self.width) {
/// if ctx.shutdown().is_shutdown() {
/// return Ok(Fin::Stopped);
/// }
/// // The awaited door: the same wait for room, parked on a runtime instead of a thread.
/// if feed
/// .give_async(String::from_utf8_lossy(window).into_owned())
/// .await
/// .is_err()
/// {
/// return Ok(Fin::Stopped);
/// }
/// }
/// }
/// Ok(Fin::Spent)
/// }
/// }
/// ```
#[diagnostic::on_unimplemented(
message = "`{Self}` has no AWAITED `run`",
label = "this face is not the one this unit wears",
note = "the `async` word on a declaration names the face its body has, so the impl beside a \
streaming declaration must be `AsyncStreamOperator`; a `StreamOperator` impl is the \
BLOCKING face, which is what a bare one asks for",
note = "the PAIR is the `stream` word's, and the face is chosen by the FAN-OUT one delivered item \
produces: bounded in the input is `Operator` / `AsyncOperator`, growing with the input's \
length is `StreamOperator` / `AsyncStreamOperator`",
note = "either give the body an `AsyncStreamOperator` impl, or drop the word and keep the \
blocking one"
)]
pub trait AsyncStreamOperator {
/// The message this unit consumes — the declared struct an edge moves.
type In;
/// The message this unit streams out, `'static` for [`StreamOperator::Out`]'s reason.
type Out: 'static;
/// This unit's per-DELIVERY failure. Bound-free here, for [`Operator::Error`]'s reason.
type Error;
/// [`StreamOperator::run`], answering a future the engine drives — the thread engine to completion
/// on the thread the node owns, the async engine by awaiting it.
fn run(
&mut self,
ctx: &Context,
delivery: Delivery<Self::In>,
feed: Feed<Self::Out>,
) -> impl Future<Output = Result<Fin, Self::Error>>;
}
/// A node whose WHOLE LIFE is one call: it owns the loop, selects across its own inbound edges in
/// its own order, and publishes through its own downstream set until it is spent or told to stop.
///
/// # THE FACE-SELECTION LAW — three rows, and each has real residents
///
/// The pair above and the pair before it are both PER-DELIVERY faces: the framework runs the loop,
/// hands the body one delivery at a time and keeps the books. This face hands the loop over. The
/// three rows are one sentence each, and the question is what the NODE has to own:
///
/// | the body | its face | the sentence |
/// |---|---|---|
/// | bounded fan-out, a simple serial unit | [`Operator`] / [`AsyncOperator`] | one delivered item in, a handful of emissions out, and the framework drives every part of it |
/// | one delivery is one WHOLE LIFE where per-delivery parallelism AND fate bookkeeping are the FRAMEWORK's | [`StreamOperator`] / [`AsyncStreamOperator`] | a demux: N warm bodies, an admission bound, a feed cut per delivery, the dead-letter kept by the lane |
/// | the node takes the wheel and KEEPS THE BOOKS | `AutonomousOperator` / [`AsyncAutonomousOperator`] | a decoder, a resampler, a conform, a heavy embedder: select order, arm priority, intake gating, batching, ack timing and internal workers are all the node's |
///
/// The rows are PEERS rather than a ladder, exactly as the first two already are. A face is chosen
/// per node, the `async` axis cuts across all three unchanged, and no body already written moves.
///
/// # What the OPERATIONAL SPACE is, and why a third kind rather than a wider protocol
///
/// [`Operator::accept`] is called once per delivery and returns, so everything about WHEN the next
/// delivery is taken belongs to the driver: which upstream is read first, whether an upstream is
/// read at all this pass, how long the body parks between passes, when an input's ack is released.
/// A body that needs any of those — a decoder holding per-track state that must drain its own
/// workers before admitting more work, a resampler that must not take a second track's frames while
/// the first is mid-flush — cannot express it at that face, and changing `accept`'s protocol was
/// refused long ago on the count that decides it: 105 `accept` bodies in this tree, and a protocol
/// change is a change to every one of them.
///
/// So the answer is a THIRD KIND rather than a widened first. The framework still knows only WHAT
/// nodes exist and HOW they connect, which is its founding division: the threads, the routing and
/// the fan-out inside a node are the node's own, and this face is where a node says so.
///
/// # What a `run` is handed
///
/// ```rust,ignore
/// fn run(self, ctx: Context, upstreams: Upstreams<Self::In>, downstream: Downstream<Self::Out>)
/// -> Result<Fin, Self::Error>;
/// ```
///
/// [`Upstreams`](crate::Upstreams) is the node's inbound edges RAW — one receiving end per edge, in
/// declaration order — so a body puts a framework edge and a channel of its own into ONE select.
/// [`Downstream`](crate::Downstream) is the same out-edge set every other face publishes through,
/// handed whole. [`ShutdownSignal`] is the one thing the framework ever says to a body that is inside `run`
/// for its whole life.
///
/// # `self` BY VALUE, which is [`Source::run`](crate::Source::run)'s shape and its reason
///
/// There is nothing after it. A node of this kind is started ONCE and what it owns it owns until it
/// answers, so the value is MOVED into the call rather than borrowed for it — exactly as an origin's
/// life takes its own. [`StreamOperator::run`] takes `&mut self` because there genuinely IS
/// something after it: the instance stays warm for the next delivery. Here there is no next.
///
/// **The dividend is the prologue.** A body that owns `self` can take itself APART into its workers
/// — a model handle onto one thread, a scratch arena onto another, a decoder table split by track —
/// which a `&mut self` body could only clone or lock. The parts move; nothing is shared that does
/// not have to be.
///
/// # THE LIFECYCLE, and every phase of it belongs to somebody nameable
///
/// | phase | whose | what happens |
/// |---|---|---|
/// | **construction** | the launch's create walk | PURE DATA. No thread, no channel, no worker: a built-and-unignited node holds no live resource, so dropping one in its slot is a no-op |
/// | **the slot** | the launch | the value sits in the mount, moved nowhere, until an engine is put under it |
/// | **ignition** | the launch | the value MOVES onto the thread that hosts it — one move, one owner, for the node's whole life |
/// | **startup** | the node | `run`'s PROLOGUE: spawn the workers, open the internal queues, destructure `self`'s parts into them |
/// | **the loop** | the node | select, gate, batch, route, publish, answer acks — all of it |
/// | **teardown** | the node | `run`'s EPILOGUE, and it is EXPLICIT: close the in-queues, let the workers drain their session tails, join them, then answer the [`Fin`] |
/// | **the backstop** | [`Drop`] | idempotent, and it is there so a PANIC-unwind cannot deadlock — see below |
///
/// **Construction being pure data is a CONTRACT and not an observation.** The launch builds every
/// node before it wires any of them and may refuse in between; a construction that had already
/// spawned a thread would leave one running behind a refusal nothing could unwind, because the
/// pre-ignition unwind consumes values and cannot join threads. So the threads start in `run` and
/// nowhere else, and a node in its slot is a bag of options and handles.
///
/// **The teardown is the epilogue and the [`Drop`] is the backstop.** An orderly wind-down is
/// spelled by the body: closing the in-queue senders is what tells a worker parked on a receive
/// that its stream is over, so it drains whatever session tail it holds, returns, and is joined. A
/// [`Drop`] impl that closes those same senders is what makes the same thing happen when the body
/// does NOT reach its epilogue — a panic unwinding through `run` drops the node's parts, the
/// senders go, the parked workers wake and return, and a join on that path terminates instead of
/// waiting forever on a queue nobody will ever fill. **Close before you join, in both places**, and
/// the two paths agree.
///
/// **`Err` DRAINS THE SAME WAY.** A death is not a licence to abandon a worker mid-session: the
/// epilogue runs, the tails are drained, the workers are joined, and only then does the error go
/// back to be dead-lettered. What differs between the two exits is which arm of the `Result` is
/// answered and nothing else.
///
/// **A respawn is a FACTORY REBUILD.** Nothing reuses the husk of a node that ended — the value was
/// consumed by `run` and its workers are gone — so what a supervisor would restart is a fresh
/// construction from the same options. That is what makes the pure-data contract above worth
/// keeping: a rebuild is cheap exactly because construction touches nothing live.
///
/// # The ACK VOCABULARY IS UNCHANGED, and the only novelty is WHO answers
///
/// A [`Delivery`] taken off an edge carries its [`Custody`](crate::Custody) exactly as it does
/// anywhere else, and the node answers it with an [`Ack`](crate::Ack) exactly as a
/// [`Resident`](crate::Resident) does — under the same [`AckMode`](crate::AckMode) its declaration
/// stated, with the same healing window behind [`Local`](crate::AckMode::Local). Nothing about the
/// protocol changes at this face. What changes is that the node's own code says when.
///
/// # The ENDINGS are the origin layer's, reused verbatim
///
/// | what happened | what `run` answers |
/// |---|---|
/// | every upstream hung up and drained | `Ok(`[`Fin::Spent`]`)` |
/// | heard the stop and wound down | `Ok(`[`Fin::Stopped`]`)` |
/// | DIED — it neither finished nor was stopped | `Err(Self::Error)` |
///
/// `Err` is a WHOLE-NODE death and not a per-delivery one, which is this face's item read honestly:
/// the node's item is its life. The party settles either way — a dead body is a finished body — and
/// the ending reaches the arrangement's taps as [`Processed`](crate::Lifecycle::Processed) for both
/// endings and [`Failed`](crate::Lifecycle::Failed) for the death. Nothing restarts it, for the
/// reason the origin layer's own note gives: a restart policy is a real design and every one of its
/// questions is answered differently by a decoder, a socket loop and a directory walk.
///
/// # `Send`, and this face asks for nothing
///
/// [`Operator`]'s law verbatim: mobility belongs to the engines. An autonomous node runs on a
/// thread of its own — the awaited half PINNED there, exactly as an origin's is — so a `!Send` body
/// is an ordinary citizen here and no bound is written at the contract.
///
/// # Examples
///
/// ```
/// use ingraph::{Context,
/// Ack, AutonomousOperator, Downstream, Fin, Lifecycle, ShutdownSignal, Upstreams, Wake, conduit,
/// };
///
/// /// A node that keeps its own books and its own crew: it spawns a worker in the prologue, feeds
/// /// it, answers each delivery's custody at a time of its own choosing, and winds the crew down
/// /// in the epilogue.
/// struct Counting {
/// /// Handed to the worker in the prologue — the by-value dividend, moved rather than shared.
/// label: String,
/// }
///
/// /// Closing the in-queue is what wakes a parked worker, so the drop is the idempotent backstop
/// /// under the epilogue: a panic unwinding through `run` still lets the join terminate.
/// struct Crew {
/// jobs: Option<conduit::Sender<u64>>,
/// hand: Option<std::thread::JoinHandle<usize>>,
/// }
///
/// impl Crew {
/// /// Close, THEN join — the one order both the epilogue and the drop keep.
/// fn wind_down(&mut self) -> usize {
/// drop(self.jobs.take());
/// self.hand.take().map_or(0, |hand| hand.join().unwrap_or(0))
/// }
/// }
///
/// impl Drop for Crew {
/// fn drop(&mut self) {
/// let _ = self.wind_down();
/// }
/// }
///
/// impl AutonomousOperator for Counting {
/// type In = u64;
/// type Out = u64;
/// type Error = core::convert::Infallible;
///
/// fn run(
/// self,
/// ctx: Context,
/// upstreams: Upstreams<u64>,
/// _downstream: Downstream<u64>,
/// ) -> Result<Fin, Self::Error> {
/// // THE PROLOGUE: the queues are opened and `self`'s parts move INTO the crew.
/// let (jobs, to_do) = conduit::bounded::<u64>(8);
/// let label = self.label;
/// let hand = std::thread::spawn(move || {
/// let mut seen = 0;
/// while to_do.recv().is_some() {
/// seen += 1;
/// }
/// let _ = label;
/// seen
/// });
/// let mut crew = Crew { jobs: Some(jobs), hand: Some(hand) };
///
/// // THE LOOP, and every decision in it is this node's.
/// let fin = loop {
/// if ctx.shutdown().is_shutdown() {
/// break Fin::Stopped;
/// }
/// for wake in upstreams.drain(0) {
/// let Wake::Delivered(delivery) = wake else {
/// continue;
/// };
/// let (payload, custody) = delivery.into_parts();
/// let released = payload.keys().copied().collect();
/// for item in payload {
/// let _ = crew.jobs.as_ref().map(|jobs| jobs.send(item.into_value()));
/// }
/// // The books, kept by the node: the keys it is done with, released when it says so.
/// if let Some(custody) = custody {
/// custody.send(Ack::new(released, "counting", Lifecycle::Processed(())));
/// }
/// }
/// if upstreams.is_spent() {
/// break Fin::Spent;
/// }
/// };
///
/// // THE EPILOGUE: close the in-queue, let the worker drain its tail, join it, THEN answer.
/// let _counted = crew.wind_down();
/// Ok(fin)
/// }
/// }
/// ```
///
/// The answer is a [`Fin`] and NOT a future, which is what this half of the pair buys — the same
/// fact [`Operator`] states two traits up:
///
/// ```compile_fail
/// use ingraph::{AutonomousOperator, Downstream, Fin, ShutdownSignal, Upstreams};
/// # struct Counting;
/// # impl AutonomousOperator for Counting {
/// # type In = u64;
/// # type Out = u64;
/// # type Error = core::convert::Infallible;
/// # fn run(self, ctx: Context, _: Upstreams<u64>, _: Downstream<u64>) -> Result<Fin, Self::Error> {
/// # Ok(Fin::Spent)
/// # }
/// # }
/// # async fn awaited(unit: Counting, ctx: Context, up: Upstreams<u64>, down: Downstream<u64>) {
/// let _ = unit.run(ctx, up, down).await; // a `Result` is not a future
/// # }
/// ```
#[diagnostic::on_unimplemented(
message = "`{Self}` has no autonomous `run`",
label = "this face is not the one this unit wears",
note = "the `autonomous` word on a declaration names the KIND its body wears, so the impl beside \
an autonomous declaration must be `AutonomousOperator` — one `run` for the node's whole \
life, owning its own loop over `Upstreams`, `Downstream` and `ShutdownSignal`",
note = "the kind is chosen by WHAT THE NODE HAS TO OWN: the framework drives a bounded body \
(`Operator` / `AsyncOperator`), the lane drives a whole-file one and keeps its books \
(`StreamOperator` / `AsyncStreamOperator`), and a node that needs select order, arm \
priority, intake gating or ack timing takes the wheel here",
note = "write `async` beside `autonomous` where the body is the awaited one, which is \
`AsyncAutonomousOperator`"
)]
pub trait AutonomousOperator: Sized {
/// The message this node consumes — the declared struct an edge moves.
type In;
/// The message it publishes — the declared struct an edge moves.
///
/// `'static`, per [`StreamOperator::Out`]'s reason read at this kind: what a downstream set
/// carries outlives the call that made it, and this call is the node's whole life.
type Out: 'static;
/// What a life that DIED refuses with. Bound-free here, for [`Operator::Error`]'s reason, and it
/// is the carrier of the failure scene — the node's own account of what killed it.
type Error;
/// RUN — the node's whole life, owning the loop.
///
/// It keeps the BARE name [`AsyncAutonomousOperator::run`] also carries, for
/// [`Operator::accept`]'s measured reason: a body that imports one face writes `run` with no
/// ceremony, and a type wearing BOTH is `E0034` naming the two candidates and offering the
/// disambiguating spelling. The name is [`StreamOperator::run`]'s and
/// [`Source::run`](crate::Source::run)'s too, and that costs nothing — they are different traits,
/// disambiguated by the same spelling.
///
/// # Errors
///
/// Whatever this node's own life refuses with — a body that DIED rather than ending. Both endings
/// are `Ok`, and the trait's own table is where the three outcomes are set beside each other.
fn run(
self,
ctx: Context,
upstreams: Upstreams<Self::In>,
downstream: Downstream<Self::Out>,
) -> Result<Fin, Self::Error>;
}
/// [`AutonomousOperator`]'s ASYNCHRONOUS face — the same owned loop, for a body that has an
/// `.await` to spend.
///
/// Everything [`AutonomousOperator`] states holds here verbatim: the same three seats with the same
/// types, `self` taken BY VALUE and its whole lifecycle table with it, the same [`Fin`] endings
/// reused from the origin layer, the same whole-node `Err` draining before it is answered, the same
/// unchanged ack vocabulary, the same absence of a `Send` bound. THE ONLY DIFFERENCE IS THAT THE
/// ANSWER IS A FUTURE — and the future is PINNED on the node's own thread rather than spawned, which
/// is what keeps a `!Send` body an ordinary citizen here.
///
/// The prologue and the epilogue are the same two phases with awaited spellings: an awaited body's
/// crew may be tasks rather than threads, and what it closes and awaits are its own — but the
/// ORDER is the one the blocking face's table states, and [`Drop`] is the same idempotent backstop
/// under it.
///
/// # Why a PAIR and not a defaulted second verb
///
/// The dual-mode law, stated in full at [`AsyncOperator`]: an author implements EXACTLY ONE face,
/// and the bound is what says which. A single trait carrying both verbs would make every node answer
/// a question it has no body for, and a blanket bridge would blind the bound that selects.
///
/// ```
/// use ingraph::{Context, AsyncAutonomousOperator, Downstream, Fin, ShutdownSignal, Upstreams};
///
/// struct Waiting {
/// /// Moved into the loop by the prologue — `self` is this call's, so nothing is borrowed.
/// budget: usize,
/// }
///
/// impl AsyncAutonomousOperator for Waiting {
/// type In = u64;
/// type Out = u64;
/// type Error = core::convert::Infallible;
///
/// async fn run(
/// self,
/// ctx: Context,
/// upstreams: Upstreams<u64>,
/// _downstream: Downstream<u64>,
/// ) -> Result<Fin, Self::Error> {
/// let mut left = self.budget;
/// let Some(edge) = upstreams.edge(0) else {
/// return Ok(Fin::Spent);
/// };
/// while left > 0 {
/// if ctx.shutdown().is_shutdown() {
/// return Ok(Fin::Stopped);
/// }
/// // The awaited door: the same wait, parked on a runtime instead of a thread.
/// if edge.park_async().await.is_none() {
/// return Ok(Fin::Spent);
/// }
/// left -= 1;
/// }
/// Ok(Fin::Spent)
/// }
/// }
/// ```
#[diagnostic::on_unimplemented(
message = "`{Self}` has no AWAITED autonomous `run`",
label = "this face is not the one this unit wears",
note = "the `async` word on a declaration names the face its body has, so the impl beside an \
autonomous declaration must be `AsyncAutonomousOperator`; an `AutonomousOperator` impl is \
the BLOCKING face, which is what a bare `autonomous` asks for",
note = "the KIND is the `autonomous` word's, and it is chosen by what the node has to own: select \
order, arm priority, intake gating, batching, ack timing and internal workers",
note = "either give the body an `AsyncAutonomousOperator` impl, or drop the word and keep the \
blocking one"
)]
pub trait AsyncAutonomousOperator: Sized {
/// The message this node consumes — the declared struct an edge moves.
type In;
/// The message it publishes, `'static` for [`AutonomousOperator::Out`]'s reason.
type Out: 'static;
/// What a life that DIED refuses with. Bound-free here, for [`Operator::Error`]'s reason.
type Error;
/// [`AutonomousOperator::run`], answering a future the engine drives — pinned on the thread this
/// node owns.
///
/// # Errors
///
/// [`AutonomousOperator::run`]'s, unchanged.
fn run(
self,
ctx: Context,
upstreams: Upstreams<Self::In>,
downstream: Downstream<Self::Out>,
) -> impl Future<Output = Result<Fin, Self::Error>>;
}
/// The BLOCKING MODE — the [`Driven`] row [`Operator`] fills, and a [`Resident`](crate::Resident)'s
/// default.
///
/// Named for what the body does rather than for what the driver does to it: it BLOCKS, answering
/// where an awaited one would yield. A bare declaration is in this mode, which is why it is the
/// default nobody writes.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct Block;
/// The ASYNCHRONOUS MODE — [`Block`]'s partner, and what an `async` declaration buys.
///
/// The [`Driven`] row [`AsyncOperator`] fills: a body whose answer is a future, driven on the async
/// engine directly and on the thread engine through the same `block_on` every other async seam is
/// driven by.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct Async;
/// WHAT A UNIT IS, in a mode `M`: the three types both faces declare, said once so the driver can
/// be written once.
///
/// # Why the shape is a trait of its own
///
/// A [`Resident`](crate::Resident) is ~500 lines of plumbing that name only `In` and `Out` —
/// collect, reconcile, fan out, dispatch, harvest — and none of it cares whether the body it wraps
/// answers a value or a future. Bounding that plumbing on either face would fork it in two; making
/// the faces share a supertrait would force every unit to write two `impl` blocks. So the shape is
/// stated HERE and both faces are projected onto it by blanket impls, which cost an author nothing:
/// implementing [`Operator`] IS implementing `Driven<Block>`.
///
/// The two blankets do not overlap because their TRAIT REFS differ — `Driven<Block>` and
/// `Driven<Async>` are two traits as far as coherence is concerned — which is the one mechanism in
/// stable Rust that gives conditional existence over a mode. Bounds SELECT; that is this trait's
/// whole job.
///
/// A type wearing BOTH faces implements both rows, and nothing here objects: which one a resident
/// drives is decided by the mode it was built on, not by what the type happens to offer.
#[diagnostic::on_unimplemented(
message = "`{Self}` is not a unit in the `{M}` mode",
label = "no `accept` of this mode's shape",
note = "a unit implements exactly ONE of `Operator` (the blocking face, mode `Block`) and \
`AsyncOperator` (the awaited face, mode `Async`), and implementing either IS implementing \
this trait's row for it",
note = "where a declaration is mounted, the mode is the one its own word selected and its \
`Declared::Mode` states: a bare declaration asks for `Block` and the `async` word asks \
for `Async`, so a body whose face differs from its word is refused here",
note = "if `{Self}` has no `accept` at all, give it one — a node the graph runs is an operator"
)]
pub trait Driven<M> {
/// Whether THIS mode's `accept` answers without a future.
///
/// Set by the blanket impl and by nothing else, which is what makes it a proof rather than a
/// claim: an author cannot write a row of this trait, so no unit can state a syncness its mode
/// does not have. It aggregates — see [`Drives::SYNC`](crate::Drives::SYNC) for a node's own and
/// the emitted root's `ALL_SYNC` for a whole deployment's — and it PROVES rather than selects:
/// stable Rust cannot dispatch on a const, so every fork in the driver is taken by a bound.
const SYNC: bool;
/// The message this unit consumes.
type In;
/// The message this unit produces.
type Out;
/// Its per-item failure.
type Error;
}
/// The BLOCKING row: implementing [`Operator`] is implementing this.
impl<T> Driven<Block> for T
where
T: Operator,
{
const SYNC: bool = true;
type In = <T as Operator>::In;
type Out = <T as Operator>::Out;
type Error = <T as Operator>::Error;
}
/// The ASYNCHRONOUS row: implementing [`AsyncOperator`] is implementing this.
impl<T> Driven<Async> for T
where
T: AsyncOperator,
{
const SYNC: bool = false;
type In = <T as AsyncOperator>::In;
type Out = <T as AsyncOperator>::Out;
type Error = <T as AsyncOperator>::Error;
}
/// A DECLARED mode word, as a type — the bridge two macro expansions meet at.
///
/// A node's mode is written on the node's own declaration and the LAUNCH is emitted by the root's,
/// and the two expansions cannot see each other. What crosses the wall is
/// [`Declared::Mode`](crate::Declared::Mode), a type — and the const-shaped reading of it,
/// [`Driven::SYNC`], is what a root's `ALL_SYNC` folds. Stable Rust cannot select a bound with a
/// const, so a const on that road is lifted back into a TYPE here, which the launch's per-node
/// predicate then spends: `#node: Driven<Selected<{ <#node as Driven<<#node as Declared>::Mode>>::SYNC }>>`.
///
/// That is the whole reason the crossing is worth its machinery: it makes the word and the impl
/// AGREE OR NOT COMPILE. A declaration that stayed bare over a body on the awaited face is
/// `Driven<Block>` unsatisfied at the launch, naming `Operator` as the trait the type does not
/// implement — so the const that says a deployment is all-sync cannot be a const that lied.
///
/// It is the CONST's bridge and not the mode seat itself: a declaration states its mode directly as
/// [`Declared::Mode`](crate::Declared::Mode), and this is what the const-shaped half of the same
/// fact is spent through.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct Word<const SYNC: bool>;
/// Which mode a [`Word`] names. Implemented for the two words and by nothing else — the vocabulary
/// is closed because the axis has exactly two ends.
pub trait Selects {
/// [`Block`] or [`Async`].
type Mode;
}
/// The BLOCKING word.
impl Selects for Word<true> {
type Mode = Block;
}
/// The ASYNCHRONOUS word.
impl Selects for Word<false> {
type Mode = Async;
}
/// The mode a declared `SYNC` names — what a launch predicate is spelled through.
pub type Selected<const SYNC: bool> = <Word<SYNC> as Selects>::Mode;
/// Declare an edge `upstream → downstream`.
///
/// The bound `D: Driven<N, In = <U as Driven<M>>::Out>` is the **compile-time edge guard**:
/// it accepts the pair only when the downstream's input type is exactly the
/// upstream's output type — i.e. when the two ends name the same message. It
/// declares the edge and checks the types; it does not wire the channel.
///
/// # The MODES are free, and independently so
///
/// `M` and `N` are the two ends' own modes and nothing here relates them: an edge carries a
/// MESSAGE, and which of the pair awaits its body says nothing about what it puts on the wire. So a
/// blocking producer feeding an awaited consumer is an ordinary edge, and each mode is inferred
/// from the trait its end implements.
///
/// A graph builder's `edge` supersedes this for building a whole DAG (it carries
/// the same bound and records the edge as data); `subscribe` remains valid as a
/// standalone edge check.
///
/// Wiring a producer to a consumer expecting a different message is a **compile
/// error** — e.g. an audio-segment producer into a keyframe consumer:
///
/// ```compile_fail
/// use ingraph::{Delivery, Emitter, Operator, subscribe};
/// struct Start; struct AudioSegment; struct Keyframe;
/// struct AudioProd; impl Operator for AudioProd {
/// type In = Start; type Out = AudioSegment; type Error = core::convert::Infallible;
/// fn accept(&mut self, ctx: &Context, _: Delivery<Self::In>, _: &mut Emitter<Self::Out>)
/// -> Result<(), Self::Error> { Ok(()) }
/// }
/// struct VideoCons; impl Operator for VideoCons {
/// type In = Keyframe; type Out = Keyframe; type Error = core::convert::Infallible;
/// fn accept(&mut self, ctx: &Context, _: Delivery<Self::In>, _: &mut Emitter<Self::Out>)
/// -> Result<(), Self::Error> { Ok(()) }
/// }
/// subscribe(&AudioProd, &VideoCons); // AudioSegment != Keyframe → In != Out → rejected
/// ```
pub fn subscribe<U, D, M, N>(_upstream: &U, _downstream: &D)
where
U: Driven<M>,
D: Driven<N, In = <U as Driven<M>>::Out>,
{
}
#[cfg(test)]
mod tests;