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
//! Tokio-native receiver for one claimed inbox lane.
use std::sync::Arc;
use crate::{LinkSegment, Result};
/// What [`InboxReceiver::next`] observed.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Received {
/// A downstream frame was copied out of the lane.
Frame,
/// A frame carrying one receiver-owned work admission.
Work(crate::WorkTicket),
/// Interested capacity changed; recheck before submitting work.
Capacity(u64),
/// An orbit-link event frame was copied out of the lane; hand it to
/// `LinkEvents::accept` (the `events` feature). Its first byte is in
/// [`crate::RESERVED_FRAME_TAGS`], so a downstream decoder never sees it
/// as one of its own.
Event,
/// The lane directory moved to this generation: a lane was claimed or
/// released. Read [`crate::Inbox::serving`] or the lane identities to see
/// which.
Directory(u64),
}
/// One lane's async reader.
///
/// The socket is a wake source, not a message source. [`Self::recv`] always
/// checks the shared-memory lane before arming and checks the lane generation
/// again before awaiting the descriptor, so a coalesced or stale datagram
/// cannot lose a frame.
///
/// A writer rings only after taking the lane's arm, so every arm this
/// receiver finds taken is exactly one bell sent. It reads those and no more:
/// the socket is not asked whether it is empty.
pub struct InboxReceiver {
segment: Arc<LinkSegment>,
lane: usize,
socket: Option<tokio::net::UnixDatagram>,
/// The directory generation this receiver last reported.
directory: u64,
capacity: u64,
/// Whether this receiver raised the lane's arm and has not taken it back.
armed: bool,
/// Bells sent for arms a writer took, and not read yet.
owed: u32,
#[cfg(feature = "probe")]
observation: crate::probe::LaneObservation,
}
impl InboxReceiver {
pub(crate) fn bind(
segment: Arc<LinkSegment>,
lane: usize,
) -> Result<Self> {
let socket = segment.inbox().bind_receiver(lane)?;
let directory = segment.inbox().directory();
let capacity = segment.inbox().capacity_generation(lane)?;
Ok(Self {
segment,
lane,
socket: Some(socket),
directory,
capacity,
armed: false,
owed: 0,
#[cfg(feature = "probe")]
observation: Default::default(),
})
}
/// Read probe counters for this receiver from the benchmark driver.
#[cfg(feature = "probe")]
pub fn lane_probe(&self) -> crate::LaneProbe {
self.observation.probe.clone()
}
/// Wait for and copy the next frame from this lane, of either kind.
///
/// Cancellation leaves the frame in SHM. A later call first reads the
/// lane and therefore observes it even if the cancelled future had
/// already consumed the coalescing descriptor wake.
pub async fn recv(
&mut self,
out: &mut Vec<u8>,
) -> Result<()> {
loop {
match self.next(out).await? {
Received::Directory(_) | Received::Capacity(_) => {}
Received::Work(ticket) => {
self.segment.inbox().cancel_work(ticket);
return Err(crate::Error::Malformed(
"work frames require an admission-aware receiver",
));
}
Received::Frame | Received::Event => return Ok(()),
}
}
}
/// Wait for the next frame or the next directory change, whichever comes
/// first. A change is reported as the generation the directory moved to;
/// several claims or releases between two looks arrive as one, so compare
/// the directory itself to learn each of them. Cancellation loses
/// neither: a frame stays in SHM, and an unreported change is reported
/// next.
pub async fn next(
&mut self,
out: &mut Vec<u8>,
) -> Result<Received> {
Ok(self.next_inner(Some(out), None).await?.expect("no read boundary"))
}
/// Read as usual until the cursor reaches a captured reservation boundary.
/// Report progress even if reaching it only consumed cancelled turns.
pub async fn next_until_read(
&mut self,
out: &mut Vec<u8>,
boundary: u64,
) -> Result<Option<Received>> {
self.next_inner(Some(out), Some(boundary)).await
}
/// Drive lane notifications after intake has stopped, without consuming
/// work or control frames still in the inbox.
pub async fn next_notification(&mut self) -> Result<Received> {
Ok(self.next_inner(None, None).await?.expect("no read boundary"))
}
async fn next_inner(
&mut self,
mut out: Option<&mut Vec<u8>>,
boundary: Option<u64>,
) -> Result<Option<Received>> {
// A wait that was cancelled left its arm raised.
self.lower();
loop {
let inbox = self.segment.inbox();
let directory = inbox.directory();
if directory != self.directory {
self.directory = directory;
#[cfg(feature = "probe")]
self.observation.notification();
return Ok(Some(Received::Directory(directory)));
}
let seen = inbox.receiver_generation(self.lane)?;
let capacity = inbox.capacity_generation(self.lane)?;
if capacity != self.capacity {
self.capacity = capacity;
#[cfg(feature = "probe")]
self.observation.notification();
return Ok(Some(Received::Capacity(capacity)));
}
if let Some(out) = out.as_deref_mut()
&& let Some(work) =
inbox.read_frame_before(self.lane, out, boundary)?
{
let received = if let Some(ticket) = work {
Received::Work(ticket)
} else if crate::frame::is_event(out) {
Received::Event
} else {
Received::Frame
};
#[cfg(feature = "probe")]
match received {
Received::Frame | Received::Work(_) => {
self.observation.frame()
}
_ => self.observation.notification(),
}
return Ok(Some(received));
}
if let Some(boundary) = boundary
&& inbox.read_position(self.lane)? >= boundary
{
return Ok(None);
}
// Only the empty-to-wait transition touches the socket, and
// only for bells known to have been sent: one from an earlier
// arm must be read before another arm can bring a second.
self.settle()?;
let inbox = self.segment.inbox();
inbox.arm_receiver(self.lane)?;
self.armed = true;
if inbox.receiver_generation(self.lane)? != seen
|| inbox.directory() != self.directory
{
self.lower();
continue;
}
#[cfg(not(feature = "probe"))]
self.socket().readable().await?;
#[cfg(feature = "probe")]
{
self.observation.finish();
let mut pending = false;
{
let mut readiness =
std::pin::pin!(self.socket().readable());
use std::future::Future;
std::future::poll_fn(|cx| {
let result = readiness.as_mut().poll(cx);
pending |= result.is_pending();
result
})
.await?;
}
self.observation.begin(pending);
}
self.lower();
if self.owed == 0 {
// Woken with the arm still raised: a bell this receiver did
// not account for. Read until the socket says it is empty.
crate::bell::drain(self.socket())?;
}
}
}
/// Take the arm back if it is raised. One a writer took first is one
/// bell sent.
fn lower(&mut self) {
if std::mem::take(&mut self.armed)
&& !self.segment.inbox().take_receiver_arm(self.lane)
{
self.owed += 1;
}
}
/// Read the bells known to have been sent, and no more. One that is not
/// there yet is on its way and stays owed.
fn settle(&mut self) -> std::io::Result<()> {
if self.owed == 0 {
return Ok(());
}
while self.owed > 0 && crate::bell::take_one(self.socket())? {
self.owed -= 1;
}
crate::bell::forget_readiness(self.socket());
Ok(())
}
fn socket(&self) -> &tokio::net::UnixDatagram {
self.socket.as_ref().expect("a live receiver owns its socket")
}
fn close(
&mut self,
release: impl FnOnce(&LinkSegment, usize),
) {
let Some(socket) = self.socket.take() else {
return;
};
self.segment.inbox().unbind_receiver(self.lane);
// The sender may still be connected to this socket. Close it before
// another receiver can take the registry entry and arm the same lane.
drop(socket);
release(&self.segment, self.lane);
}
pub fn lane(&self) -> usize {
self.lane
}
}
#[cfg(test)]
#[path = "../tests/unit/receiver.rs"]
mod tests;
impl Drop for InboxReceiver {
fn drop(&mut self) {
self.close(LinkSegment::release_receiver);
}
}