Skip to main content

astrs_node_api/output/
sample.rs

1//! [`OutputSample`] — a write buffer that is a ring slot when it can be.
2//!
3//! Blueprint §9.1 promises `allocate(len) → SampleMut`, and §6.2 says what
4//! that means: *"`node.allocate(len)` hands the producer a `SampleMut`
5//! pointing into the next FREE slot; `send` flips WRITING→READY. No copy ever
6//! happens for the fast path."*
7//!
8//! This type is that buffer, plus the one thing a bare `SampleMut` cannot do:
9//! fall back. A node writes the same code whether or not its route has been
10//! upgraded yet, because [`RawOutput::allocate`](super::RawOutput::allocate)
11//! hands back the same type either way —
12//! [`SampleBuffer::Shm`] when the ring is available and
13//! [`SampleBuffer::Heap`] when it is not.
14//!
15//! # Committing is consuming
16//!
17//! [`OutputSample::send`] takes `self`, so a window cannot be published twice
18//! and cannot be written to after publication. Dropping one without sending
19//! aborts it, which returns the slot to the pool *without consuming its
20//! sequence number* — an aborted write leaves no gap for consumers to wait on.
21
22use std::sync::Arc;
23
24use astrs_shm::SampleMut;
25use astrs_wire::{DataId, Metadata, NodeRequest, OutputPayload};
26
27use crate::error::Result;
28use crate::session::SessionShared;
29
30/// Where an [`OutputSample`]'s bytes live.
31pub enum SampleBuffer<'a> {
32    /// A shared-memory ring slot: writing here copies nothing (§6.2).
33    Shm(SampleMut<'a>),
34    /// An owned heap buffer, published inline on the daemon path.
35    Heap(Vec<u8>),
36}
37
38impl core::fmt::Debug for SampleBuffer<'_> {
39    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
40        match self {
41            Self::Shm(window) => f
42                .debug_struct("Shm")
43                .field("slot", &window.slot_index())
44                .field("seq", &window.seq())
45                .field("len", &window.len())
46                .finish(),
47            Self::Heap(bytes) => f.debug_struct("Heap").field("len", &bytes.len()).finish(),
48        }
49    }
50}
51
52/// A reserved write buffer for one message.
53#[derive(Debug)]
54pub struct OutputSample<'a> {
55    /// The bytes.
56    buffer: SampleBuffer<'a>,
57    /// The session this publishes through.
58    shared: Arc<SessionShared>,
59    /// The output this belongs to.
60    output: DataId,
61    /// The segment name and generation, when the buffer is a ring slot.
62    segment: Option<(String, u64)>,
63}
64
65impl<'a> OutputSample<'a> {
66    /// A sample backed by a ring slot.
67    #[must_use]
68    pub fn shm(
69        window: SampleMut<'a>,
70        shared: Arc<SessionShared>,
71        output: DataId,
72        segment: Option<(String, u64)>,
73    ) -> Self {
74        Self {
75            buffer: SampleBuffer::Shm(window),
76            shared,
77            output,
78            segment,
79        }
80    }
81
82    /// A sample backed by an owned heap buffer.
83    #[must_use]
84    pub fn heap(bytes: Vec<u8>, shared: Arc<SessionShared>, output: DataId) -> Self {
85        Self {
86            buffer: SampleBuffer::Heap(bytes),
87            shared,
88            output,
89            segment: None,
90        }
91    }
92
93    /// Whether writing here copies nothing.
94    #[must_use]
95    pub const fn is_zero_copy(&self) -> bool {
96        matches!(self.buffer, SampleBuffer::Shm(_))
97    }
98
99    /// The buffer's length in bytes.
100    #[must_use]
101    pub fn len(&self) -> usize {
102        match &self.buffer {
103            SampleBuffer::Shm(window) => window.len(),
104            SampleBuffer::Heap(bytes) => bytes.len(),
105        }
106    }
107
108    /// Whether the buffer is empty.
109    #[must_use]
110    pub fn is_empty(&self) -> bool {
111        self.len() == 0
112    }
113
114    /// The writable bytes.
115    ///
116    /// On the zero-copy plane the slice base is 128-byte aligned (§6.1), so an
117    /// Arrow IPC message serialised straight into it is directly usable as a
118    /// SIMD source by every consumer.
119    #[must_use]
120    pub fn as_mut_slice(&mut self) -> &mut [u8] {
121        match &mut self.buffer {
122            SampleBuffer::Shm(window) => window.as_mut_slice(),
123            SampleBuffer::Heap(bytes) => bytes.as_mut_slice(),
124        }
125    }
126
127    /// The bytes written so far.
128    #[must_use]
129    pub fn as_slice(&self) -> &[u8] {
130        match &self.buffer {
131            SampleBuffer::Shm(window) => window.as_slice(),
132            SampleBuffer::Heap(bytes) => bytes.as_slice(),
133        }
134    }
135
136    /// The output this sample belongs to.
137    #[must_use]
138    pub const fn output(&self) -> &DataId {
139        &self.output
140    }
141
142    /// The sequence number this window will publish, on the zero-copy plane.
143    #[must_use]
144    pub fn sequence(&self) -> Option<u64> {
145        match &self.buffer {
146            SampleBuffer::Shm(window) => Some(window.seq()),
147            SampleBuffer::Heap(_) => None,
148        }
149    }
150
151    /// Shortens the buffer to `len` bytes.
152    ///
153    /// The encoder that reserved a generous window and produced less keeps the
154    /// zero-copy path rather than falling back to a copy.
155    ///
156    /// # Errors
157    ///
158    /// [`crate::NodeError::Shm`] when `len` is longer than the window.
159    pub fn truncate(&mut self, len: usize) -> Result<()> {
160        match &mut self.buffer {
161            SampleBuffer::Shm(window) => Ok(window.truncate(len)?),
162            SampleBuffer::Heap(bytes) => {
163                if len <= bytes.len() {
164                    bytes.truncate(len);
165                }
166                Ok(())
167            }
168        }
169    }
170
171    /// Publishes the message.
172    ///
173    /// # Errors
174    ///
175    /// [`crate::NodeError::DaemonGone`] once the session has ended, and
176    /// [`crate::NodeError::Wire`] when the metadata cannot be encoded.
177    pub fn send(self, metadata: Metadata) -> Result<()> {
178        let Self {
179            buffer,
180            shared,
181            output,
182            segment,
183        } = self;
184        match buffer {
185            SampleBuffer::Shm(window) => {
186                let slot = window.slot_index();
187                let len = window.len() as u64;
188                let meta_bytes = super::encode_metadata(&metadata)?;
189                match window.commit(&meta_bytes) {
190                    Ok(_seq) => {
191                        let (name, generation) = segment.unwrap_or_default();
192                        shared.count_zero_copy_send();
193                        shared.send_request(NodeRequest::SendMessage {
194                            output,
195                            metadata,
196                            payload: OutputPayload::Shm {
197                                segment: name,
198                                slot,
199                                len,
200                                generation,
201                            },
202                        })
203                    }
204                    Err(error) => {
205                        // The commit could only fail because the segment
206                        // closed underneath us; §6.2 says fall back rather
207                        // than retry, but the bytes are gone with the slot,
208                        // so the honest answer is the error.
209                        shared.count_shm_fallback();
210                        Err(error.into())
211                    }
212                }
213            }
214            SampleBuffer::Heap(bytes) => {
215                shared.count_inline_send();
216                shared.send_request(NodeRequest::SendMessage {
217                    output,
218                    metadata,
219                    payload: OutputPayload::inline(bytes),
220                })
221            }
222        }
223    }
224
225    /// Discards the reservation.
226    ///
227    /// A ring slot returns to the pool without consuming its sequence number.
228    pub fn abort(self) {
229        if let SampleBuffer::Shm(window) = self.buffer {
230            window.abort();
231        }
232    }
233}
234
235#[cfg(test)]
236mod tests {
237    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
238
239    use super::*;
240    use crate::events::EventSource;
241    use crate::runtime::NodeRuntime;
242    use crate::session::{OUTGOING_CAPACITY, Outgoing};
243    use astrs_wire::{DataflowId, FrameLimits, NodeId, NodeSource, NodeSpawnSpec, SessionId};
244    use tokio::sync::mpsc;
245
246    fn session() -> (Arc<SessionShared>, mpsc::Receiver<Outgoing>) {
247        let (sender, receiver) = mpsc::channel(OUTGOING_CAPACITY);
248        let spec = Arc::new(NodeSpawnSpec::new(
249            DataflowId::from_u128(1),
250            NodeId::new("camera").unwrap(),
251            0,
252            NodeSource::Dynamic,
253        ));
254        let shared = Arc::new(SessionShared::new(
255            spec,
256            SessionId::from_u128(1),
257            sender,
258            Arc::new(EventSource::new()),
259            NodeRuntime::acquire().unwrap(),
260            4096,
261            FrameLimits::uds(),
262        ));
263        (shared, receiver)
264    }
265
266    #[test]
267    fn a_heap_sample_publishes_inline() {
268        let (shared, mut receiver) = session();
269        let output = DataId::new("image").unwrap();
270        let mut sample = OutputSample::heap(vec![0; 4], Arc::clone(&shared), output.clone());
271        assert!(!sample.is_zero_copy());
272        assert_eq!(sample.len(), 4);
273        assert!(!sample.is_empty());
274        assert_eq!(sample.output(), &output);
275        assert_eq!(sample.sequence(), None);
276        sample.as_mut_slice().copy_from_slice(&[1, 2, 3, 4]);
277        assert_eq!(sample.as_slice(), &[1, 2, 3, 4]);
278
279        sample.send(Metadata::default()).unwrap();
280        let Ok(Outgoing::Request(request)) = receiver.try_recv() else {
281            panic!("expected a send");
282        };
283        let NodeRequest::SendMessage { payload, .. } = *request else {
284            panic!("expected a SendMessage");
285        };
286        assert_eq!(payload.bytes(), Some(&[1, 2, 3, 4][..]));
287        assert_eq!(shared.stats().sends_inline, 1);
288    }
289
290    #[test]
291    fn truncating_a_heap_sample_shortens_the_payload() {
292        let (shared, mut receiver) = session();
293        let mut sample = OutputSample::heap(
294            vec![9; 8],
295            Arc::clone(&shared),
296            DataId::new("image").unwrap(),
297        );
298        sample.truncate(3).unwrap();
299        assert_eq!(sample.len(), 3);
300        sample.truncate(99).unwrap();
301        assert_eq!(sample.len(), 3, "a longer truncate is a no-op");
302        sample.send(Metadata::default()).unwrap();
303
304        let Ok(Outgoing::Request(request)) = receiver.try_recv() else {
305            panic!("expected a send");
306        };
307        let NodeRequest::SendMessage { payload, .. } = *request else {
308            panic!("expected a SendMessage");
309        };
310        assert_eq!(payload.len(), 3);
311    }
312
313    #[test]
314    fn aborting_a_heap_sample_publishes_nothing() {
315        let (shared, mut receiver) = session();
316        let sample = OutputSample::heap(
317            vec![0; 4],
318            Arc::clone(&shared),
319            DataId::new("image").unwrap(),
320        );
321        sample.abort();
322        assert!(receiver.try_recv().is_err());
323        assert_eq!(shared.stats().sends_inline, 0);
324    }
325
326    #[test]
327    fn a_zero_length_sample_is_empty() {
328        let (shared, _receiver) = session();
329        let sample = OutputSample::heap(Vec::new(), shared, DataId::new("image").unwrap());
330        assert!(sample.is_empty());
331        assert_eq!(sample.as_slice(), &[] as &[u8]);
332        assert!(format!("{sample:?}").contains("Heap"));
333    }
334}