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        Ok(Arc::new(Self {
27            inner: MemoryOutputInner::new(PacketQueue::new(capacity(capacity_bytes)?, policy)),
28        }))
29    }
30
31    /// Blocks until one output payload, orderly EOF, or abort.
32    pub fn recv_shared(&self) -> Result<Option<Arc<[u8]>>> {
33        self.inner.queue().recv_shared("MemoryOutput")
34    }
35
36    /// Returns one output payload if immediately available.
37    pub fn try_recv_shared(&self) -> Result<Option<Arc<[u8]>>> {
38        self.inner.queue().try_recv_shared("MemoryOutput")
39    }
40
41    /// Blocks until one output payload, orderly EOF, or abort, copying it into a vector.
42    pub fn recv(&self) -> Result<Option<Vec<u8>>> {
43        self.recv_shared()
44            .map(|data| data.map(|data| data.to_vec()))
45    }
46
47    /// Returns one output payload if immediately available, copying it into a vector.
48    pub fn try_recv(&self) -> Result<Option<Vec<u8>>> {
49        self.try_recv_shared()
50            .map(|data| data.map(|data| data.to_vec()))
51    }
52
53    /// Closes output after currently queued packets are received.
54    pub fn close(&self) {
55        self.inner.queue().close();
56    }
57    /// Aborts output, discarding queued payloads and waking blocked operations.
58    pub fn abort(&self) {
59        self.inner.queue().abort();
60    }
61    /// Returns queued output bytes.
62    pub fn queued_bytes(&self) -> usize {
63        self.inner.queue().queued_bytes()
64    }
65    /// Returns bytes rejected by the drop policy.
66    pub fn dropped_bytes(&self) -> usize {
67        self.inner.queue().dropped_bytes()
68    }
69    /// Takes the latest private callback error.
70    pub fn take_callback_error(&self) -> Option<CallbackError> {
71        take(self.inner.state())
72    }
73
74    pub(crate) fn bind(&self) -> Result<MemoryOutputBinding> {
75        acquire(self.inner.state(), "MemoryOutput")?;
76        Ok(MemoryOutputBinding::new(Arc::clone(&self.inner)))
77    }
78}