rustduck-core 1.1.0

Safe typed TSDuck core bindings for rustduck
Documentation
//! Public bounded memory-output endpoint API.

use std::num::NonZeroUsize;
use std::sync::Arc;

use crate::{MemoryQueuePolicy, Result};

use super::binding::MemoryOutputBinding;
use super::inner::MemoryOutputInner;
use super::state::{acquire, take};
use super::validation::capacity;
use super::{CallbackError, PacketQueue};

/// Thread-safe bounded output endpoint for a TSDuck `memory` plugin.
///
/// Native callback data is copied once into `Arc<[u8]>`; `recv_shared` moves
/// that allocation without a second payload copy. `close` drains queued data;
/// `abort` discards it and wakes blocked receivers/callbacks.
pub struct MemoryOutput {
    pub(crate) inner: Arc<MemoryOutputInner>,
}

impl MemoryOutput {
    /// Creates a bounded output endpoint with a capacity in complete TS packets.
    pub fn new(capacity_bytes: NonZeroUsize, policy: MemoryQueuePolicy) -> Result<Arc<Self>> {
        let inner = MemoryOutputInner::new(PacketQueue::new(capacity(capacity_bytes)?, policy))?;
        Ok(Arc::new(Self { inner }))
    }

    /// Blocks until one output payload, orderly EOF, or abort.
    pub fn recv_shared(&self) -> Result<Option<Arc<[u8]>>> {
        self.inner.queue().recv_shared("MemoryOutput")
    }

    /// Returns one output payload if immediately available.
    pub fn try_recv_shared(&self) -> Result<Option<Arc<[u8]>>> {
        self.inner.queue().try_recv_shared("MemoryOutput")
    }

    /// Blocks until one output payload, orderly EOF, or abort, copying it into a vector.
    pub fn recv(&self) -> Result<Option<Vec<u8>>> {
        self.recv_shared()
            .map(|data| data.map(|data| data.to_vec()))
    }

    /// Returns one output payload if immediately available, copying it into a vector.
    pub fn try_recv(&self) -> Result<Option<Vec<u8>>> {
        self.try_recv_shared()
            .map(|data| data.map(|data| data.to_vec()))
    }

    /// Closes output after currently queued packets are received.
    pub fn close(&self) {
        self.inner.queue().close();
    }
    /// Aborts output, discarding queued payloads and waking blocked operations.
    pub fn abort(&self) {
        self.inner.queue().abort();
    }
    /// Returns queued output bytes.
    pub fn queued_bytes(&self) -> usize {
        self.inner.queue().queued_bytes()
    }
    /// Returns bytes rejected by the drop policy.
    pub fn dropped_bytes(&self) -> usize {
        self.inner.queue().dropped_bytes()
    }
    /// Takes the latest private callback error.
    pub fn take_callback_error(&self) -> Option<CallbackError> {
        take(self.inner.state())
    }

    pub(crate) fn bind(&self) -> Result<MemoryOutputBinding> {
        acquire(self.inner.state(), "MemoryOutput")?;
        Ok(MemoryOutputBinding::new(Arc::clone(&self.inner)))
    }
}