1use crate::format::*;
3use crate::{pixels::Pixels, CameraError, CameraResult, StreamStats, SubscriptionOptions};
4use parking_lot::Mutex;
5use std::{
6 collections::VecDeque,
7 sync::{
8 atomic::{AtomicBool, AtomicU64, Ordering},
9 Arc, Weak,
10 },
11 time::{Duration, Instant, SystemTime, UNIX_EPOCH},
12};
13use tokio::sync::watch;
14static NEXT_SESSION: AtomicU64 = AtomicU64::new(1);
15const MAX_FRAME_BYTES: usize = 128 * 1024 * 1024;
16pub(crate) const FRAME_ERROR_RECOVERY_THRESHOLD: u64 = 8;
17
18#[derive(Clone, Copy, Debug, PartialEq, Eq)]
19pub(crate) enum RecoveryTrigger {
20 SourceStopped,
21 SourceStalled,
22 FrameErrors { consecutive: u64 },
23}
24#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
25pub struct FrameKey {
27 pub session: u64,
29 pub sequence: u64,
31}
32#[derive(Clone, Debug)]
33enum Storage {
34 Rgb(Arc<Pixels<u8>>),
35 Bytes(Arc<Vec<u8>>),
36}
37impl Storage {
38 fn bytes(&self) -> &[u8] {
39 match self {
40 Self::Rgb(p) => p.as_slice().expect("packed RGB"),
41 Self::Bytes(p) => p,
42 }
43 }
44 fn bytes_mut(&mut self) -> &mut [u8] {
45 match self {
46 Self::Rgb(p) => Arc::get_mut(p)
47 .expect("leased RGB")
48 .as_slice_mut()
49 .expect("packed RGB"),
50 Self::Bytes(p) => Arc::get_mut(p).expect("leased bytes"),
51 }
52 }
53 fn unique(&mut self) -> bool {
54 fn detach<T: Default>(p: &mut Arc<T>) -> bool {
55 if Arc::get_mut(p).is_some() {
56 return true;
57 }
58 if Arc::strong_count(p) != 1 {
59 return false;
60 }
61 let old = std::mem::replace(p, Arc::new(T::default()));
62 match Arc::try_unwrap(old) {
63 Ok(data) => {
64 *p = Arc::new(data);
65 true
66 }
67 Err(shared) => {
68 *p = shared;
69 false
70 }
71 }
72 }
73 match self {
74 Self::Rgb(p) => {
75 if Arc::get_mut(p).is_some() {
76 return true;
77 }
78 if Arc::strong_count(p) != 1 {
79 return false;
80 }
81 let old = std::mem::replace(p, Arc::new(Pixels::zeros((0, 0, 3))));
82 match Arc::try_unwrap(old) {
83 Ok(data) => {
84 *p = Arc::new(data);
85 true
86 }
87 Err(shared) => {
88 *p = shared;
89 false
90 }
91 }
92 }
93 Self::Bytes(p) => detach(p),
94 }
95 }
96 fn retained(&self) -> bool {
97 match self {
98 Self::Rgb(p) => Arc::strong_count(p) > 1,
99 Self::Bytes(p) => Arc::strong_count(p) > 1,
100 }
101 }
102}
103#[derive(Debug)]
105pub struct CapturedFrame {
106 pub key: FrameKey,
108 storage: Storage,
109 layout: FrameLayout,
110 pub captured_at: Instant,
112 pub timestamp_ns: u64,
114 pub source_timestamp_ns: Option<i64>,
116 source_clock: ClockDomain,
117 pub source_sequence: Option<u64>,
119}
120pub type Frame = Arc<CapturedFrame>;
122impl CapturedFrame {
123 pub fn age(&self) -> Duration {
125 self.captured_at.elapsed()
126 }
127 pub fn layout(&self) -> &FrameLayout {
129 &self.layout
130 }
131 pub fn bytes(&self) -> &[u8] {
133 self.storage.bytes()
134 }
135 pub fn plane(&self, index: usize) -> Option<&[u8]> {
137 let p = self.layout.planes.get(index)?;
138 self.bytes().get(p.offset..p.offset + p.length)
139 }
140 pub fn rgb_view(&self) -> CameraResult<RgbView<'_>> {
142 if self.layout.format != PixelFormat::Rgb8 || self.layout.planes.len() != 1 {
143 return Err(CameraError::unsupported_format(
144 "Frame layout is not packed RGB8".into(),
145 ));
146 }
147 let plane = self.layout.planes[0];
148 if plane.pixel_stride != 3 {
149 return Err(CameraError::invalid_frame(
150 "RGB8 pixel stride must be three bytes".into(),
151 ));
152 }
153 let bytes = self
154 .bytes()
155 .get(plane.offset..plane.offset + plane.length)
156 .ok_or_else(|| CameraError::invalid_frame("RGB plane is outside the frame".into()))?;
157 Ok(RgbView {
158 bytes,
159 width: self.layout.width as usize,
160 height: self.layout.height as usize,
161 row_stride: plane.row_stride,
162 })
163 }
164 pub fn source_timestamp(&self) -> Option<SourceTimestamp> {
166 self.source_timestamp_ns.map(|nanoseconds| SourceTimestamp {
167 nanoseconds,
168 clock: self.source_clock,
169 })
170 }
171 pub fn copy_to(&self, out: &mut [u8]) -> CameraResult<()> {
173 if out.len() != self.bytes().len() {
174 return Err(CameraError::invalid_frame(
175 "Destination length differs from frame".into(),
176 ));
177 }
178 out.copy_from_slice(self.bytes());
179 Ok(())
180 }
181 pub fn to_owned_bytes(&self) -> Vec<u8> {
183 self.bytes().to_vec()
184 }
185 #[allow(dead_code)]
186 pub(crate) fn rgb_pixels(&self) -> CameraResult<&Arc<Pixels<u8>>> {
187 match &self.storage {
188 Storage::Rgb(p) => Ok(p),
189 _ => Err(CameraError::unsupported_format(
190 "Frame is native; request RGB or convert explicitly".into(),
191 )),
192 }
193 }
194 #[cfg(feature = "ndarray")]
195 pub fn ndarray_view(&self) -> CameraResult<ndarray::ArrayView3<'_, u8>> {
197 use ndarray::ShapeBuilder;
198 let view = self.rgb_view()?;
199 ndarray::ArrayView3::from_shape(
200 (view.height, view.width, 3).strides((view.row_stride, 3, 1)),
201 view.bytes,
202 )
203 .map_err(|error| CameraError::invalid_frame(error.to_string()))
204 }
205}
206
207#[derive(Clone, Copy, Debug)]
208pub struct RgbView<'a> {
210 bytes: &'a [u8],
211 width: usize,
212 height: usize,
213 row_stride: usize,
214}
215
216impl<'a> RgbView<'a> {
217 pub fn width(&self) -> usize {
219 self.width
220 }
221
222 pub fn height(&self) -> usize {
224 self.height
225 }
226
227 pub fn row_stride(&self) -> usize {
229 self.row_stride
230 }
231
232 pub fn row(&self, index: usize) -> Option<&'a [u8]> {
234 if index >= self.height {
235 return None;
236 }
237 let start = index.checked_mul(self.row_stride)?;
238 self.bytes
239 .get(start..start.checked_add(self.width.checked_mul(3)?)?)
240 }
241
242 pub fn bytes(&self) -> &'a [u8] {
244 self.bytes
245 }
246}
247#[derive(Clone, Default, Debug)]
248pub struct FrameMetrics {
250 pub received: u64,
252 pub published: u64,
254 pub pool_drops: u64,
256 pub conversion_errors: u64,
258 pub consecutive_conversion_errors: u64,
260 pub max_consecutive_conversion_errors: u64,
262 pub allocated_buffers: usize,
264 pub allocated_bytes: usize,
266 pub retained_buffers: usize,
268 pub conversion_total_ns: u64,
270 pub conversion_max_ns: u64,
272 pub conversion_p50_ns: u64,
274 pub conversion_p95_ns: u64,
276}
277#[derive(Clone, Default)]
278struct Snapshot {
279 session: u64,
280 active: bool,
281 recovering: bool,
282 reconnect_enabled: bool,
283 latest: Option<Frame>,
284}
285struct Publication {
286 session: u64,
287 layout: FrameLayout,
288 timestamp: Option<SourceTimestamp>,
289 source_sequence: Option<u64>,
290 captured_at: Instant,
291 elapsed: u64,
292}
293struct Slot {
294 data: Option<Storage>,
295 bytes: usize,
296}
297struct Pool {
298 slots: Vec<Slot>,
299 budget: MemoryBudget,
300 metrics: FrameMetrics,
301 started: Option<Instant>,
302 stopped: Option<Instant>,
303 last_source_activity: Option<Instant>,
304 recent: VecDeque<Instant>,
305 conversion_samples: VecDeque<u64>,
306 last_error_report: Option<Instant>,
307 suppressed_error_reports: u64,
308}
309struct Subscriber {
310 queue: Mutex<VecDeque<Frame>>,
311 delivery: DeliveryPolicy,
312 dropped: AtomicU64,
313 max_rate: Option<FrameRate>,
314 last_enqueued: Mutex<Option<Instant>>,
315 owner: std::sync::OnceLock<Arc<AtomicBool>>,
316}
317#[derive(Clone)]
319pub struct FrameHub {
320 state: watch::Sender<Snapshot>,
321 pool: Arc<Mutex<Pool>>,
322 subscribers: Arc<Mutex<Vec<Weak<Subscriber>>>>,
323 native_output: Arc<AtomicBool>,
324 events: Arc<Mutex<Option<tokio::sync::broadcast::Sender<crate::SessionEvent>>>>,
325 recovery_wake: watch::Sender<u64>,
326}
327impl Default for FrameHub {
328 fn default() -> Self {
329 Self::new(6)
330 }
331}
332impl FrameHub {
333 pub fn new(capacity: usize) -> Self {
335 let (state, _) = watch::channel(Snapshot::default());
336 let (recovery_wake, _) = watch::channel(0);
337 Self {
338 state,
339 pool: Arc::new(Mutex::new(Pool {
340 slots: vec![],
341 budget: MemoryBudget {
342 buffers: capacity.max(2),
343 ..Default::default()
344 },
345 metrics: FrameMetrics::default(),
346 started: None,
347 stopped: None,
348 last_source_activity: None,
349 recent: VecDeque::new(),
350 conversion_samples: VecDeque::with_capacity(256),
351 last_error_report: None,
352 suppressed_error_reports: 0,
353 })),
354 subscribers: Arc::new(Mutex::new(vec![])),
355 native_output: Arc::new(AtomicBool::new(false)),
356 events: Arc::new(Mutex::new(None)),
357 recovery_wake,
358 }
359 }
360 pub(crate) fn configure(&self, r: &StreamRequest) -> CameraResult<()> {
361 if self.is_streaming() {
362 return Err(CameraError::invalid_state(
363 "Stop before configuring buffers".into(),
364 ));
365 }
366 let mut pool = self.pool.lock();
367 if pool.slots.iter().any(|s| s.data.is_none() && s.bytes > 0) {
368 return Err(CameraError::invalid_state(
369 "Frame conversion is still finishing".into(),
370 ));
371 }
372 pool.slots
373 .retain_mut(|s| s.data.as_mut().is_none_or(|d| !d.unique()));
374 if pool.slots.len() > r.memory.buffers
375 || pool.slots.iter().map(|s| s.bytes).sum::<usize>() > r.memory.bytes
376 {
377 return Err(CameraError::invalid_config(
378 "Retained frames exceed the new budget".into(),
379 ));
380 }
381 pool.budget = r.memory;
382 self.native_output
383 .store(r.output == OutputFormat::Native, Ordering::Release);
384 Ok(())
385 }
386 pub fn start(&self) -> u64 {
388 let mut pool = self.pool.lock();
389 pool.metrics = FrameMetrics::default();
390 pool.started = Some(Instant::now());
391 pool.stopped = None;
392 pool.last_source_activity = Some(Instant::now());
393 pool.recent.clear();
394 pool.conversion_samples.clear();
395 pool.last_error_report = None;
396 pool.suppressed_error_reports = 0;
397 let session = NEXT_SESSION.fetch_add(1, Ordering::Relaxed);
398 self.clear_queues();
399 let current = self.state.borrow();
400 let recovering = current.recovering;
401 let reconnect_enabled = current.reconnect_enabled;
402 drop(current);
403 self.state.send_replace(Snapshot {
404 session,
405 active: true,
406 recovering,
407 reconnect_enabled,
408 latest: None,
409 });
410 session
411 }
412 pub(crate) fn set_event_sender(
413 &self,
414 sender: tokio::sync::broadcast::Sender<crate::SessionEvent>,
415 ) {
416 *self.events.lock() = Some(sender);
417 }
418
419 fn report_resource_pressure(&self, dropped_frames: u64) {
420 if let Some(sender) = self.events.lock().as_ref() {
421 let _ = sender.send(crate::SessionEvent::ResourcePressure { dropped_frames });
422 }
423 }
424 fn clear_queues(&self) {
425 self.subscribers.lock().retain(|s| {
426 if let Some(s) = s.upgrade() {
427 s.queue.lock().clear();
428 true
429 } else {
430 false
431 }
432 });
433 }
434 pub(crate) fn begin_recovery(&self) {
435 self.state.send_modify(|s| s.recovering = true);
436 }
437 pub(crate) fn end_recovery(&self) {
438 self.state.send_modify(|s| s.recovering = false);
439 }
440 pub(crate) fn enable_recovery(&self) {
441 self.state.send_modify(|s| s.reconnect_enabled = true);
442 }
443 pub(crate) fn disable_recovery(&self) {
444 self.state.send_modify(|s| {
445 s.reconnect_enabled = false;
446 s.recovering = false;
447 });
448 }
449 pub fn stop(&self) {
451 self.pool.lock().stopped = Some(Instant::now());
452 self.clear_queues();
453 self.state.send_modify(|s| {
454 s.active = false;
455 s.latest = None;
456 });
457 self.wake_recovery();
458 }
459 pub fn session(&self) -> u64 {
461 self.state.borrow().session
462 }
463 pub fn is_streaming(&self) -> bool {
465 self.state.borrow().active
466 }
467 pub fn latest(&self) -> Option<Frame> {
469 self.state.borrow().latest.clone()
470 }
471 #[cfg(test)]
472 pub(crate) fn source_activity_is_stale(&self, timeout: Duration) -> bool {
473 self.pool
474 .lock()
475 .last_source_activity
476 .is_none_or(|activity| activity.elapsed() > timeout)
477 }
478 fn wake_recovery(&self) {
479 self.recovery_wake
480 .send_modify(|generation| *generation = generation.wrapping_add(1));
481 }
482 pub(crate) fn recovery_trigger(&self, stall_timeout: Duration) -> Option<RecoveryTrigger> {
483 if !self.state.borrow().active {
484 return Some(RecoveryTrigger::SourceStopped);
485 }
486 let pool = self.pool.lock();
487 if pool.metrics.consecutive_conversion_errors >= FRAME_ERROR_RECOVERY_THRESHOLD {
488 return Some(RecoveryTrigger::FrameErrors {
489 consecutive: pool.metrics.consecutive_conversion_errors,
490 });
491 }
492 pool.last_source_activity
493 .is_none_or(|activity| activity.elapsed() >= stall_timeout)
494 .then_some(RecoveryTrigger::SourceStalled)
495 }
496 fn source_stall_remaining(&self, timeout: Duration) -> Duration {
497 self.pool
498 .lock()
499 .last_source_activity
500 .map_or(Duration::ZERO, |activity| {
501 timeout.saturating_sub(activity.elapsed())
502 })
503 }
504 pub(crate) async fn wait_for_recovery_trigger(
505 &self,
506 stall_timeout: Duration,
507 ) -> RecoveryTrigger {
508 let mut wake = self.recovery_wake.subscribe();
509 loop {
510 if let Some(trigger) = self.recovery_trigger(stall_timeout) {
511 return trigger;
512 }
513 let remaining = self.source_stall_remaining(stall_timeout);
514 tokio::select! {
515 result = wake.changed() => {
516 if result.is_err() {
517 return RecoveryTrigger::SourceStopped;
518 }
519 }
520 _ = tokio::time::sleep(remaining) => {}
521 }
522 }
523 }
524 fn record_conversion_error(&self, session: u64, source_activity: bool) {
525 {
526 let state = self.state.borrow();
527 if !state.active || state.session != session {
528 return;
529 }
530 }
531 let notify = {
532 let mut pool = self.pool.lock();
533 if source_activity {
534 pool.metrics.received += 1;
535 pool.last_source_activity = Some(Instant::now());
536 }
537 pool.metrics.conversion_errors += 1;
538 pool.metrics.consecutive_conversion_errors += 1;
539 pool.metrics.max_consecutive_conversion_errors = pool
540 .metrics
541 .max_consecutive_conversion_errors
542 .max(pool.metrics.consecutive_conversion_errors);
543 pool.metrics.consecutive_conversion_errors == FRAME_ERROR_RECOVERY_THRESHOLD
544 };
545 if notify {
546 self.wake_recovery();
547 }
548 }
549 #[allow(dead_code)]
550 pub(crate) fn record_input_error(&self, session: u64) {
551 self.record_conversion_error(session, true);
552 }
553 #[allow(dead_code)]
554 pub(crate) fn log_frame_error(&self, backend: &str, error: &CameraError) {
555 let now = Instant::now();
556 let report = {
557 let mut pool = self.pool.lock();
558 if pool.last_error_report.is_some_and(|previous| {
559 now.saturating_duration_since(previous) < Duration::from_secs(1)
560 }) {
561 pool.suppressed_error_reports += 1;
562 None
563 } else {
564 let suppressed = std::mem::take(&mut pool.suppressed_error_reports);
565 pool.last_error_report = Some(now);
566 Some(suppressed)
567 }
568 };
569 if let Some(suppressed) = report {
570 if suppressed == 0 {
571 log::warn!("{backend} frame rejected: {error}");
572 } else {
573 log::warn!(
574 "{backend} frame rejected: {error} ({suppressed} similar errors suppressed)"
575 );
576 }
577 }
578 }
579 pub(crate) fn wants_native(&self) -> bool {
580 self.native_output.load(Ordering::Acquire)
581 }
582 #[allow(dead_code)]
583 pub(crate) fn record_input_drop(&self, session: u64) {
584 if self.session() == session {
585 let mut pool = self.pool.lock();
586 pool.last_source_activity = Some(Instant::now());
587 pool.metrics.received += 1;
588 pool.metrics.pool_drops += 1;
589 let dropped = pool.metrics.pool_drops;
590 drop(pool);
591 self.report_resource_pressure(dropped);
592 }
593 }
594 #[doc(hidden)]
595 pub fn subscribe_with(&self, options: SubscriptionOptions) -> CameraResult<FrameReceiver> {
596 let budget = self.pool.lock().budget;
597 options.validate(budget)?;
598 let subscriber = Arc::new(Subscriber {
599 queue: Mutex::new(VecDeque::new()),
600 delivery: options.delivery,
601 dropped: AtomicU64::new(0),
602 max_rate: options.max_rate,
603 last_enqueued: Mutex::new(None),
604 owner: std::sync::OnceLock::new(),
605 });
606 let state = self.state.subscribe();
607 {
608 let snapshot = state.borrow();
609 let mut subs = self.subscribers.lock();
610 if let Some(f) = snapshot.latest.clone() {
611 *subscriber.last_enqueued.lock() = Some(f.captured_at);
612 subscriber.queue.lock().push_back(f);
613 }
614 subs.push(Arc::downgrade(&subscriber));
615 }
616 Ok(FrameReceiver {
617 state,
618 subscriber,
619 last: None,
620 })
621 }
622 pub async fn wait_after(
624 &self,
625 after: Option<FrameKey>,
626 timeout: Duration,
627 ) -> CameraResult<Frame> {
628 let mut rx = self.subscribe_with(SubscriptionOptions::latest())?;
629 rx.last = after.or_else(|| rx.state.borrow().latest.as_ref().map(|frame| frame.key));
630 rx.next_timeout(timeout).await
631 }
632
633 pub(crate) async fn wait_first_in(
634 &self,
635 session: u64,
636 timeout: Duration,
637 ) -> CameraResult<Frame> {
638 if self.session() != session {
639 return Err(CameraError::stream_stopped());
640 }
641 let mut rx = self.subscribe_with(SubscriptionOptions::latest())?;
642 let frame = rx.next_timeout(timeout).await?;
643 if frame.key.session != session {
644 return Err(CameraError::stream_stopped());
645 }
646 Ok(frame)
647 }
648 pub fn publish_rgb(
650 &self,
651 session: u64,
652 width: u32,
653 height: u32,
654 source_timestamp_ns: Option<i64>,
655 convert: impl FnOnce(&mut [u8]) -> CameraResult<()>,
656 ) -> CameraResult<bool> {
657 self.publish(
658 session,
659 FrameLayout::rgb(width, height),
660 source_timestamp_ns.map(|nanoseconds| SourceTimestamp {
661 nanoseconds,
662 clock: ClockDomain::Unknown,
663 }),
664 None,
665 true,
666 convert,
667 )
668 }
669 #[allow(dead_code)]
670 pub(crate) fn publish_rgb_metadata(
671 &self,
672 session: u64,
673 width: u32,
674 height: u32,
675 timestamp: Option<SourceTimestamp>,
676 sequence: Option<u64>,
677 convert: impl FnOnce(&mut [u8]) -> CameraResult<()>,
678 ) -> CameraResult<bool> {
679 self.publish(
680 session,
681 FrameLayout::rgb(width, height),
682 timestamp,
683 sequence,
684 true,
685 convert,
686 )
687 }
688 pub(crate) fn publish_native_into(
689 &self,
690 session: u64,
691 layout: FrameLayout,
692 timestamp: Option<SourceTimestamp>,
693 convert: impl FnOnce(&mut [u8]) -> CameraResult<()>,
694 ) -> CameraResult<bool> {
695 let length = layout
696 .planes
697 .iter()
698 .try_fold(0, |n: usize, p| {
699 p.offset.checked_add(p.length).map(|end| n.max(end))
700 })
701 .ok_or_else(|| CameraError::invalid_frame("Native plane extent overflow".into()))?;
702 layout.validate(length)?;
703 self.publish(session, layout, timestamp, None, false, convert)
704 }
705 #[cfg_attr(not(feature = "custom-backend"), allow(dead_code))]
706 pub(crate) fn publish_native(
707 &self,
708 session: u64,
709 layout: FrameLayout,
710 timestamp: Option<SourceTimestamp>,
711 sequence: Option<u64>,
712 parts: &[&[u8]],
713 ) -> CameraResult<bool> {
714 let len = parts
715 .iter()
716 .try_fold(0usize, |n, p| n.checked_add(p.len()))
717 .ok_or_else(|| CameraError::invalid_frame("Native size overflow".into()))?;
718 layout.validate(len)?;
719 let end = layout
720 .planes
721 .iter()
722 .map(|p| p.offset + p.length)
723 .max()
724 .unwrap_or(0);
725 if end != len {
726 return Err(CameraError::invalid_frame(
727 "Native payload contains undescribed trailing data".into(),
728 ));
729 }
730 self.publish(session, layout, timestamp, sequence, false, |out| {
731 let mut offset = 0;
732 for p in parts {
733 out[offset..offset + p.len()].copy_from_slice(p);
734 offset += p.len();
735 }
736 Ok(())
737 })
738 }
739
740 #[cfg_attr(not(feature = "custom-backend"), allow(dead_code))]
741 pub(crate) fn writable_native(
742 &self,
743 session: u64,
744 layout: FrameLayout,
745 ) -> CameraResult<NativeWriteLease> {
746 let length = Self::frame_length(&layout, false)?;
747 layout.validate(length)?;
748 let lease = self
749 .reserve(session, &layout, false)?
750 .ok_or(CameraError::buffer_exhausted())?;
751 Ok(NativeWriteLease {
752 lease: Some(lease),
753 session,
754 layout,
755 timestamp: None,
756 captured_at: Instant::now(),
757 })
758 }
759
760 fn frame_length(layout: &FrameLayout, rgb: bool) -> CameraResult<usize> {
761 let length = if rgb {
762 (layout.width as usize)
763 .checked_mul(layout.height as usize)
764 .and_then(|n| n.checked_mul(3))
765 } else {
766 layout
767 .planes
768 .iter()
769 .filter_map(|plane| plane.offset.checked_add(plane.length))
770 .max()
771 };
772 length
773 .filter(|&length| length > 0 && length <= MAX_FRAME_BYTES)
774 .ok_or_else(|| CameraError::invalid_frame("Frame exceeds size limit".into()))
775 }
776
777 fn reserve(
778 &self,
779 session: u64,
780 layout: &FrameLayout,
781 rgb: bool,
782 ) -> CameraResult<Option<Lease>> {
783 {
784 let state = self.state.borrow();
785 if !state.active || state.session != session {
786 return Ok(None);
787 }
788 }
789 let length = Self::frame_length(layout, rgb)?;
790 let mut pool = self.pool.lock();
791 {
792 let state = self.state.borrow();
793 if !state.active || state.session != session {
794 return Ok(None);
795 }
796 }
797 pool.metrics.received += 1;
798 pool.last_source_activity = Some(Instant::now());
799 let index = pool
800 .slots
801 .iter_mut()
802 .position(|slot| slot.data.as_mut().is_some_and(Storage::unique));
803 let index = match index {
804 Some(index) => index,
805 None if pool.slots.len() < pool.budget.buffers => {
806 pool.slots.push(Slot {
807 data: None,
808 bytes: 0,
809 });
810 pool.slots.len() - 1
811 }
812 _ => {
813 pool.metrics.pool_drops += 1;
814 let dropped = pool.metrics.pool_drops;
815 drop(pool);
816 self.report_resource_pressure(dropped);
817 return Ok(None);
818 }
819 };
820 let used: usize = pool.slots.iter().map(|slot| slot.bytes).sum();
821 if length
822 > pool
823 .budget
824 .bytes
825 .saturating_sub(used - pool.slots[index].bytes)
826 {
827 if pool.slots[index].bytes == 0 {
828 pool.slots.pop();
829 }
830 pool.metrics.pool_drops += 1;
831 let dropped = pool.metrics.pool_drops;
832 drop(pool);
833 self.report_resource_pressure(dropped);
834 return Ok(None);
835 }
836 let available = pool
837 .budget
838 .bytes
839 .saturating_sub(used - pool.slots[index].bytes);
840 let existing = pool.slots[index].data.take();
841 let storage = match existing {
842 Some(Storage::Rgb(pixels))
843 if rgb && pixels.dim() == (layout.height as usize, layout.width as usize, 3) =>
844 {
845 Storage::Rgb(pixels)
846 }
847 Some(Storage::Bytes(mut bytes)) if !rgb => {
848 let buffer = Arc::get_mut(&mut bytes).expect("exclusive native slot");
849 if length > buffer.capacity() {
850 bytes = Arc::new(vec![0; length]);
851 } else {
852 buffer.resize(length, 0);
853 }
854 Storage::Bytes(bytes)
855 }
856 _ if rgb => Storage::Rgb(Arc::new(Pixels::zeros((
857 layout.height as usize,
858 layout.width as usize,
859 3,
860 )))),
861 _ => Storage::Bytes(Arc::new(vec![0; length])),
862 };
863 let allocated = match &storage {
864 Storage::Bytes(bytes) => bytes.capacity(),
865 Storage::Rgb(_) => length,
866 };
867 if allocated > available {
868 pool.slots[index].data = Some(Storage::Bytes(Arc::new(Vec::new())));
869 pool.slots[index].bytes = 0;
870 pool.metrics.pool_drops += 1;
871 let dropped = pool.metrics.pool_drops;
872 drop(pool);
873 self.report_resource_pressure(dropped);
874 return Ok(None);
875 }
876 pool.slots[index].bytes = allocated;
877 drop(pool);
878 Ok(Some(Lease {
879 hub: self.clone(),
880 index,
881 data: Some(storage),
882 }))
883 }
884
885 fn publish(
886 &self,
887 session: u64,
888 layout: FrameLayout,
889 timestamp: Option<SourceTimestamp>,
890 source_sequence: Option<u64>,
891 rgb: bool,
892 convert: impl FnOnce(&mut [u8]) -> CameraResult<()>,
893 ) -> CameraResult<bool> {
894 let now = Instant::now();
895 let Some(mut lease) = self.reserve(session, &layout, rgb)? else {
896 return Ok(false);
897 };
898 let begin = Instant::now();
899 let result = convert(lease.data.as_mut().unwrap().bytes_mut());
900 let elapsed = begin.elapsed().as_nanos().min(u64::MAX as u128) as u64;
901 if let Err(error) = result {
902 self.record_conversion_error(session, false);
903 return Err(error);
904 }
905 self.finish_publish(
906 Publication {
907 session,
908 layout,
909 timestamp,
910 source_sequence,
911 captured_at: now,
912 elapsed,
913 },
914 &lease,
915 )
916 }
917
918 fn finish_publish(&self, publication: Publication, lease: &Lease) -> CameraResult<bool> {
919 let Publication {
920 session,
921 layout,
922 timestamp,
923 source_sequence,
924 captured_at: now,
925 elapsed,
926 } = publication;
927 let timestamp_ns = SystemTime::now()
928 .duration_since(UNIX_EPOCH)
929 .unwrap_or_default()
930 .as_nanos()
931 .min(u64::MAX as u128) as u64;
932 let mut published = false;
933 self.state.send_if_modified(|state| {
934 if !state.active || state.session != session {
935 return false;
936 }
937 let sequence = state.latest.as_ref().map_or(1, |f| f.key.sequence + 1);
938 let frame = Arc::new(CapturedFrame {
939 key: FrameKey { session, sequence },
940 storage: lease.data.as_ref().unwrap().clone(),
941 layout,
942 captured_at: now,
943 timestamp_ns,
944 source_timestamp_ns: timestamp.map(|t| t.nanoseconds),
945 source_clock: timestamp.map_or(ClockDomain::Unknown, |t| t.clock),
946 source_sequence,
947 });
948 self.subscribers.lock().retain(|subscriber| {
949 let Some(subscriber) = subscriber.upgrade() else {
950 return false;
951 };
952 let mut queue = subscriber.queue.lock();
953 if subscriber
954 .owner
955 .get()
956 .is_some_and(|f| f.load(Ordering::Acquire))
957 {
958 queue.clear();
959 return false;
960 }
961 if let Some(rate) = subscriber.max_rate {
962 let mut last = subscriber.last_enqueued.lock();
963 if last.is_some_and(|previous| {
964 frame.captured_at.saturating_duration_since(previous) < rate.interval()
965 }) {
966 subscriber.dropped.fetch_add(1, Ordering::Relaxed);
967 return true;
968 }
969 *last = Some(frame.captured_at);
970 }
971 match subscriber.delivery {
972 DeliveryPolicy::Latest => {
973 subscriber
974 .dropped
975 .fetch_add(queue.len() as u64, Ordering::Relaxed);
976 queue.clear();
977 queue.push_back(frame.clone());
978 }
979 DeliveryPolicy::Buffered { capacity, overflow } => {
980 if queue.len() >= capacity {
981 subscriber.dropped.fetch_add(1, Ordering::Relaxed);
982 if overflow == OverflowPolicy::DropNewest {
983 return true;
984 }
985 queue.pop_front();
986 }
987 queue.push_back(frame.clone());
988 }
989 }
990 true
991 });
992 state.latest = Some(frame);
993 published = true;
994 true
995 });
996 if published {
997 let mut pool = self.pool.lock();
998 if self.session() != session {
999 return Ok(true);
1000 }
1001 pool.metrics.published += 1;
1002 pool.metrics.consecutive_conversion_errors = 0;
1003 pool.metrics.conversion_total_ns =
1004 pool.metrics.conversion_total_ns.saturating_add(elapsed);
1005 pool.metrics.conversion_max_ns = pool.metrics.conversion_max_ns.max(elapsed);
1006 if pool.conversion_samples.len() == 256 {
1007 pool.conversion_samples.pop_front();
1008 }
1009 pool.conversion_samples.push_back(elapsed);
1010 pool.recent.push_back(now);
1011 while pool
1012 .recent
1013 .front()
1014 .is_some_and(|t| now.saturating_duration_since(*t) > Duration::from_secs(1))
1015 {
1016 pool.recent.pop_front();
1017 }
1018 }
1019 Ok(published)
1020 }
1021 pub fn metrics(&self) -> FrameMetrics {
1023 let (mut samples, allocated_buffers, allocated_bytes, retained_buffers, metrics) = {
1024 let p = self.pool.lock();
1025 (
1026 p.conversion_samples.iter().copied().collect::<Vec<_>>(),
1027 p.slots.len(),
1028 p.slots.iter().map(|s| s.bytes).sum(),
1029 p.slots
1030 .iter()
1031 .filter(|s| s.data.as_ref().is_none_or(Storage::retained))
1032 .count(),
1033 p.metrics.clone(),
1034 )
1035 };
1036 samples.sort_unstable();
1037 let quantile = |percent: usize| {
1038 samples
1039 .get((samples.len() * percent).div_ceil(100).saturating_sub(1))
1040 .copied()
1041 .unwrap_or(0)
1042 };
1043 FrameMetrics {
1044 conversion_p50_ns: quantile(50),
1045 conversion_p95_ns: quantile(95),
1046 allocated_buffers,
1047 allocated_bytes,
1048 retained_buffers,
1049 ..metrics
1050 }
1051 }
1052 pub fn stats(&self) -> StreamStats {
1054 let p = self.pool.lock();
1055 StreamStats {
1056 total_frames: p.metrics.received,
1057 dropped_frames: p.metrics.pool_drops + p.metrics.conversion_errors,
1058 current_fps: if self.is_streaming() {
1059 p.recent
1060 .iter()
1061 .filter(|t| t.elapsed() < Duration::from_secs(1))
1062 .count() as f64
1063 } else {
1064 0.0
1065 },
1066 buffer_size: p.budget.buffers,
1067 buffered_frames: usize::from(self.latest().is_some()),
1068 uptime_seconds: p.started.map_or(0, |t| {
1069 p.stopped
1070 .unwrap_or_else(Instant::now)
1071 .saturating_duration_since(t)
1072 .as_secs()
1073 }),
1074 }
1075 }
1076}
1077#[cfg_attr(not(feature = "custom-backend"), allow(dead_code))]
1078pub(crate) struct NativeWriteLease {
1079 lease: Option<Lease>,
1080 session: u64,
1081 layout: FrameLayout,
1082 timestamp: Option<SourceTimestamp>,
1083 captured_at: Instant,
1084}
1085
1086#[cfg_attr(not(feature = "custom-backend"), allow(dead_code))]
1087impl NativeWriteLease {
1088 pub(crate) fn bytes_mut(&mut self) -> &mut [u8] {
1089 self.lease
1090 .as_mut()
1091 .expect("lease is present until commit")
1092 .data
1093 .as_mut()
1094 .expect("reserved storage is present")
1095 .bytes_mut()
1096 }
1097
1098 pub(crate) fn set_timestamp(&mut self, timestamp: SourceTimestamp) {
1099 self.timestamp = Some(timestamp);
1100 }
1101
1102 pub(crate) fn commit(mut self) -> CameraResult<bool> {
1103 let lease = self.lease.take().expect("lease is present until commit");
1104 let hub = lease.hub.clone();
1105 hub.finish_publish(
1106 Publication {
1107 session: self.session,
1108 layout: self.layout,
1109 timestamp: self.timestamp,
1110 source_sequence: None,
1111 captured_at: self.captured_at,
1112 elapsed: 0,
1113 },
1114 &lease,
1115 )
1116 }
1117}
1118
1119struct Lease {
1120 hub: FrameHub,
1121 index: usize,
1122 data: Option<Storage>,
1123}
1124impl Drop for Lease {
1125 fn drop(&mut self) {
1126 self.hub.pool.lock().slots[self.index].data = self.data.take();
1127 }
1128}
1129pub struct FrameReceiver {
1132 state: watch::Receiver<Snapshot>,
1133 subscriber: Arc<Subscriber>,
1134 last: Option<FrameKey>,
1135}
1136impl std::fmt::Debug for FrameReceiver {
1137 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1138 f.debug_struct("FrameReceiver")
1139 .field("last", &self.last)
1140 .field("dropped", &self.dropped_frames())
1141 .finish()
1142 }
1143}
1144impl FrameReceiver {
1145 pub(crate) fn with_stop_flag(self, flag: Arc<AtomicBool>) -> Self {
1146 if flag.load(Ordering::Acquire) {
1147 self.subscriber.queue.lock().clear();
1148 }
1149 let _ = self.subscriber.owner.set(flag);
1150 self
1151 }
1152 pub fn last_key(&self) -> Option<FrameKey> {
1154 self.last
1155 }
1156 pub fn queued_frames(&self) -> usize {
1158 self.subscriber.queue.lock().len()
1159 }
1160 pub fn dropped_frames(&self) -> u64 {
1162 self.subscriber.dropped.load(Ordering::Relaxed)
1163 }
1164 pub async fn next(&mut self) -> CameraResult<Frame> {
1166 loop {
1167 {
1168 let state = self.state.borrow_and_update();
1169 if self
1170 .subscriber
1171 .owner
1172 .get()
1173 .is_some_and(|f| f.load(Ordering::Acquire))
1174 || (!state.active && !state.recovering && !state.reconnect_enabled)
1175 {
1176 return Err(CameraError::stream_stopped());
1177 }
1178 let mut q = self.subscriber.queue.lock();
1179 while let Some(f) = q.pop_front() {
1180 if Some(f.key) != self.last && f.key.session == state.session {
1181 self.last = Some(f.key);
1182 return Ok(f);
1183 }
1184 }
1185 }
1186 self.state
1187 .changed()
1188 .await
1189 .map_err(|_| CameraError::stream_stopped())?;
1190 }
1191 }
1192 pub async fn next_timeout(&mut self, timeout: Duration) -> CameraResult<Frame> {
1194 tokio::time::timeout(timeout, self.next())
1195 .await
1196 .map_err(|_| CameraError::timeout(crate::OperationStage::FrameWait))?
1197 }
1198}