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
//! The BY-KEY JOIN: where a keyed group's members wait for each other, and what a complete one
//! carries with it.
//!
//! # Complete or not at all
//!
//! A `subscribe(…)` container's keyed group is delivered as ONE input — the emitted `Paired(A, B)`
//! variant — and it is delivered only when every member has arrived for that key. A message whose
//! counterparts are not there yet waits HERE; the straights beside it never touch this buffer,
//! because an independent flow has nothing to wait for.
//!
//! # There is no deadline, and that is the ruling rather than an omission
//!
//! A half-arrived group waits indefinitely. No timeout, no policy: the member that did arrive is
//! still in its sender's ack window — its [`Owing`](super::Owing) stays open while a
//! [`Share`] of it sits here — so the sender's watermark sticks, and the upstream's own lag sweep
//! re-pulls the flow that stopped. That is the safety net the design names, and a knob here would
//! be one before there was a case for one. Dropping the buffer is the other end of it: the shares
//! go, the tokens disconnect, and every sender reads that as held.
//!
//! # What the framework holds and what the declaration writes
//!
//! The members carry DIFFERENT message types, so the slots a partial group keeps are a struct only
//! that node's own expansion can spell. This module holds the part that is the same for every
//! group — the keyed table, the shares that accumulate against a key, and the completion — and
//! [`Group`] is the seam the spelled part meets it at.
use Hash;
use HashMap;
use ;
/// How a member of a keyed group states the key it JOINS ON.
///
/// # Why it is a value and not a trait on the message
///
/// The obvious seat is the message type — `impl Joins for Frame` — and it is the wrong one for
/// [`Sink`](super::Sink)'s reason: two nodes joining the same upstream on different fields would be
/// two impls for one app-owned type, which is `E0119` and unfixable. A projection INSTALLED at the
/// wiring has no such question, and it is the shape
/// [`Attributes`](super::Attributes) already takes for the same kind of read.
///
/// One value answers for every member — `impl Joins<Frame>` and `impl Joins<Segment>` on one
/// projection, with one `Key` — which is what "joined by key" means: the members meet at a type
/// they all produce.
/// A keyed group's PARTIAL state: one slot per member, and what a full set becomes.
///
/// Written by the node's own expansion, because the slots are one `Option` per member and the
/// members are different types. The framework only ever asks the one question below.
///
/// # `complete` gives the group BACK
///
/// `Result<Complete, Self>` rather than `Option<Complete>` on `&mut self`, so that a group which is
/// not ready cannot be half-emptied by the asking: an implementation that takes a member out and
/// then finds another missing has already lost the first. Taking the whole value and handing it
/// back is the shape where that mistake is not expressible.
/// One key's half-arrived group: the members that came, and what they are owed on.
/// The by-key join buffer of ONE keyed group.
///
/// One per node, because a container has one group: `key` on a `upstream(…)` entry JOINS the group
/// rather than opening one, so there is nothing here to tell two of them apart.