1use 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
30pub enum SampleBuffer<'a> {
32 Shm(SampleMut<'a>),
34 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#[derive(Debug)]
54pub struct OutputSample<'a> {
55 buffer: SampleBuffer<'a>,
57 shared: Arc<SessionShared>,
59 output: DataId,
61 segment: Option<(String, u64)>,
63}
64
65impl<'a> OutputSample<'a> {
66 #[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 #[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 #[must_use]
95 pub const fn is_zero_copy(&self) -> bool {
96 matches!(self.buffer, SampleBuffer::Shm(_))
97 }
98
99 #[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 #[must_use]
110 pub fn is_empty(&self) -> bool {
111 self.len() == 0
112 }
113
114 #[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 #[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 #[must_use]
138 pub const fn output(&self) -> &DataId {
139 &self.output
140 }
141
142 #[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 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 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 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 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}