Skip to main content

rustduck_core/memory/endpoint/
output.rs

1//! Public bounded memory-output endpoint API.
2
3use std::num::NonZeroUsize;
4use std::sync::Arc;
5
6use crate::{MemoryQueuePolicy, Result};
7
8use super::binding::MemoryOutputBinding;
9use super::inner::MemoryOutputInner;
10use super::state::{acquire, take};
11use super::validation::capacity;
12use super::{CallbackError, PacketQueue};
13
14/// Thread-safe bounded output endpoint for a TSDuck `memory` plugin.
15///
16/// Native callback data is copied once into `Arc<[u8]>`; `recv_shared` moves
17/// that allocation without a second payload copy. `close` drains queued data;
18/// `abort` discards it and wakes blocked receivers/callbacks.
19pub struct MemoryOutput {
20    pub(crate) inner: Arc<MemoryOutputInner>,
21}
22
23impl MemoryOutput {
24    /// Creates a bounded output endpoint with a capacity in complete TS packets.
25    pub fn new(capacity_bytes: NonZeroUsize, policy: MemoryQueuePolicy) -> Result<Arc<Self>> {
26        let inner = MemoryOutputInner::new(PacketQueue::new(capacity(capacity_bytes)?, policy))?;
27        Ok(Arc::new(Self { inner }))
28    }
29
30    /// Blocks until one output payload, orderly EOF, or abort.
31    pub fn recv_shared(&self) -> Result<Option<Arc<[u8]>>> {
32        self.inner.queue().recv_shared("MemoryOutput")
33    }
34
35    /// Returns one output payload if immediately available.
36    pub fn try_recv_shared(&self) -> Result<Option<Arc<[u8]>>> {
37        self.inner.queue().try_recv_shared("MemoryOutput")
38    }
39
40    /// Blocks until one output payload, orderly EOF, or abort, copying it into a vector.
41    pub fn recv(&self) -> Result<Option<Vec<u8>>> {
42        self.recv_shared()
43            .map(|data| data.map(|data| data.to_vec()))
44    }
45
46    /// Returns one output payload if immediately available, copying it into a vector.
47    pub fn try_recv(&self) -> Result<Option<Vec<u8>>> {
48        self.try_recv_shared()
49            .map(|data| data.map(|data| data.to_vec()))
50    }
51
52    /// Closes output after currently queued packets are received.
53    pub fn close(&self) {
54        self.inner.queue().close();
55    }
56    /// Aborts output, discarding queued payloads and waking blocked operations.
57    pub fn abort(&self) {
58        self.inner.queue().abort();
59    }
60    /// Returns queued output bytes.
61    pub fn queued_bytes(&self) -> usize {
62        self.inner.queue().queued_bytes()
63    }
64    /// Returns bytes rejected by the drop policy.
65    pub fn dropped_bytes(&self) -> usize {
66        self.inner.queue().dropped_bytes()
67    }
68    /// Takes the latest private callback error.
69    pub fn take_callback_error(&self) -> Option<CallbackError> {
70        take(self.inner.state())
71    }
72
73    pub(crate) fn bind(&self) -> Result<MemoryOutputBinding> {
74        acquire(self.inner.state(), "MemoryOutput")?;
75        Ok(MemoryOutputBinding::new(Arc::clone(&self.inner)))
76    }
77}