rustduck-core 1.0.0

Safe typed TSDuck core bindings for rustduck
Documentation
use std::collections::VecDeque;
use std::sync::{Arc, Condvar, Mutex, MutexGuard};

use crate::{Error, Result};

use super::{MemoryPushOutcome, MemoryQueuePolicy};

enum Chunk {
    Owned(Vec<u8>),
    Shared { data: Arc<[u8]>, start: usize },
}

impl Chunk {
    fn remaining(&self) -> usize {
        match self {
            Self::Owned(data) => data.len(),
            Self::Shared { data, start } => data.len() - start,
        }
    }
}

pub(crate) struct PacketQueue {
    state: Mutex<State>,
    changed: Condvar,
}

struct State {
    chunks: VecDeque<Chunk>,
    bytes: usize,
    capacity: usize,
    policy: MemoryQueuePolicy,
    closed: bool,
    aborted: bool,
    dropped_bytes: usize,
}

impl PacketQueue {
    pub(crate) fn new(capacity: usize, policy: MemoryQueuePolicy) -> Self {
        Self {
            state: Mutex::new(State {
                chunks: VecDeque::new(),
                bytes: 0,
                capacity,
                policy,
                closed: false,
                aborted: false,
                dropped_bytes: 0,
            }),
            changed: Condvar::new(),
        }
    }

    pub(crate) fn push_owned(
        &self,
        data: Vec<u8>,
        endpoint: &'static str,
    ) -> Result<MemoryPushOutcome> {
        self.push(Chunk::Owned(data), endpoint)
    }

    pub(crate) fn push_shared(
        &self,
        data: Arc<[u8]>,
        endpoint: &'static str,
    ) -> Result<MemoryPushOutcome> {
        self.push(Chunk::Shared { data, start: 0 }, endpoint)
    }

    fn push(&self, chunk: Chunk, endpoint: &'static str) -> Result<MemoryPushOutcome> {
        let len = chunk.remaining();
        let mut state = self.lock();
        if state.aborted {
            return Err(Error::QueueAborted { endpoint });
        }
        if state.closed {
            return Err(Error::QueueClosed { endpoint });
        }
        if len == 0 {
            return Ok(MemoryPushOutcome::Accepted);
        }
        if len > state.capacity {
            return match state.policy {
                MemoryQueuePolicy::Drop => {
                    state.dropped_bytes = state.dropped_bytes.saturating_add(len);
                    Ok(MemoryPushOutcome::Dropped)
                }
                MemoryQueuePolicy::Backpressure => Err(Error::InvalidArgument {
                    field: "packets",
                    message: "one push cannot be larger than queue capacity".to_owned(),
                }),
            };
        }
        while len > state.capacity - state.bytes {
            match state.policy {
                MemoryQueuePolicy::Drop => {
                    state.dropped_bytes = state.dropped_bytes.saturating_add(len);
                    return Ok(MemoryPushOutcome::Dropped);
                }
                MemoryQueuePolicy::Backpressure => {
                    state = self.wait(state);
                    if state.aborted {
                        return Err(Error::QueueAborted { endpoint });
                    }
                    if state.closed {
                        return Err(Error::QueueClosed { endpoint });
                    }
                }
            }
        }
        state.bytes += len;
        state.chunks.push_back(chunk);
        self.changed.notify_all();
        Ok(MemoryPushOutcome::Accepted)
    }

    /// Removes up to `max_size` bytes for an input callback. A complete owned
    /// queue head no larger than `max_size` moves directly into the response;
    /// all split/shared/multi-chunk reads are assembled after unlocking.
    pub(crate) fn take_for_input(
        &self,
        max_size: usize,
        endpoint: &'static str,
    ) -> Result<Option<Vec<u8>>> {
        let mut state = self.lock();
        while state.chunks.is_empty() {
            if state.aborted {
                return Err(Error::QueueAborted { endpoint });
            }
            if state.closed {
                return Ok(None);
            }
            state = self.wait(state);
        }

        if matches!(state.chunks.front(), Some(Chunk::Owned(data)) if data.len() <= max_size) {
            let Chunk::Owned(data) = state.chunks.pop_front().expect("queue was not empty") else {
                unreachable!("front chunk was checked as owned")
            };
            state.bytes -= data.len();
            drop(state);
            self.changed.notify_all();
            return Ok(Some(data));
        }

        let mut pieces = Vec::new();
        let mut total = 0;
        while total < max_size {
            let Some(chunk) = state.chunks.pop_front() else {
                break;
            };
            let available = chunk.remaining();
            let take = (max_size - total).min(available);
            match chunk {
                Chunk::Owned(data) if take == data.len() => pieces.push((Arc::from(data), 0, take)),
                Chunk::Owned(data) => {
                    let data: Arc<[u8]> = Arc::from(data);
                    pieces.push((Arc::clone(&data), 0, take));
                    state.chunks.push_front(Chunk::Shared { data, start: take });
                }
                Chunk::Shared { data, start } => {
                    pieces.push((Arc::clone(&data), start, start + take));
                    if take != available {
                        state.chunks.push_front(Chunk::Shared {
                            data,
                            start: start + take,
                        });
                    }
                }
            }
            total += take;
            state.bytes -= take;
            if take != available {
                break;
            }
        }
        drop(state);
        self.changed.notify_all();

        let mut output = Vec::with_capacity(total);
        for (data, start, end) in pieces {
            output.extend_from_slice(&data[start..end]);
        }
        Ok(Some(output))
    }

    /// Removes one complete shared output payload. `None` is orderly EOF.
    pub(crate) fn recv_shared(&self, endpoint: &'static str) -> Result<Option<Arc<[u8]>>> {
        let mut state = self.lock();
        while state.chunks.is_empty() {
            if state.aborted {
                return Err(Error::QueueAborted { endpoint });
            }
            if state.closed {
                return Ok(None);
            }
            state = self.wait(state);
        }
        let chunk = state.chunks.pop_front().expect("queue was not empty");
        let Chunk::Shared { data, start: 0 } = chunk else {
            return Err(Error::CallbackProtocol {
                operation: "MemoryOutput::recv_shared",
            });
        };
        state.bytes -= data.len();
        drop(state);
        self.changed.notify_all();
        Ok(Some(data))
    }

    pub(crate) fn try_recv_shared(&self, endpoint: &'static str) -> Result<Option<Arc<[u8]>>> {
        let mut state = self.lock();
        if state.aborted {
            return Err(Error::QueueAborted { endpoint });
        }
        let Some(chunk) = state.chunks.pop_front() else {
            return Ok(None);
        };
        let Chunk::Shared { data, start: 0 } = chunk else {
            return Err(Error::CallbackProtocol {
                operation: "MemoryOutput::try_recv_shared",
            });
        };
        state.bytes -= data.len();
        drop(state);
        self.changed.notify_all();
        Ok(Some(data))
    }

    pub(crate) fn close(&self) {
        let mut state = self.lock();
        state.closed = true;
        self.changed.notify_all();
    }

    pub(crate) fn abort(&self) {
        let mut state = self.lock();
        state.aborted = true;
        state.chunks.clear();
        state.bytes = 0;
        self.changed.notify_all();
    }

    pub(crate) fn queued_bytes(&self) -> usize {
        self.lock().bytes
    }

    pub(crate) fn dropped_bytes(&self) -> usize {
        self.lock().dropped_bytes
    }

    fn lock(&self) -> MutexGuard<'_, State> {
        self.state
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
    }

    fn wait<'a>(&self, state: MutexGuard<'a, State>) -> MutexGuard<'a, State> {
        self.changed
            .wait(state)
            .unwrap_or_else(|poisoned| poisoned.into_inner())
    }
}

#[cfg(test)]
mod tests {
    use std::sync::{Arc, Barrier, mpsc};
    use std::thread;

    use super::*;

    const ENDPOINT: &str = "test";

    fn data(bytes: usize) -> Arc<[u8]> {
        Arc::from(vec![0x47; bytes])
    }

    #[test]
    fn moves_a_complete_owned_input_chunk_without_reassembling_it() {
        let queue = PacketQueue::new(4, MemoryQueuePolicy::Drop);
        let data = vec![0x47; 4];
        let allocation = data.as_ptr();
        queue.push_owned(data, ENDPOINT).expect("push owned");

        let received = queue
            .take_for_input(4, ENDPOINT)
            .expect("take")
            .expect("queued data");
        assert_eq!(received.as_ptr(), allocation);
        assert_eq!(received, vec![0x47; 4]);
        assert_eq!(queue.queued_bytes(), 0);
    }

    #[test]
    fn drop_policy_preserves_queued_payload_and_accounts_rejection() {
        let queue = PacketQueue::new(4, MemoryQueuePolicy::Drop);
        assert!(matches!(
            queue.push_shared(data(4), ENDPOINT),
            Ok(MemoryPushOutcome::Accepted)
        ));
        assert!(matches!(
            queue.push_shared(data(4), ENDPOINT),
            Ok(MemoryPushOutcome::Dropped)
        ));
        assert_eq!(queue.queued_bytes(), 4);
        assert_eq!(queue.dropped_bytes(), 4);
        assert_eq!(queue.recv_shared(ENDPOINT).expect("receive"), Some(data(4)));
    }

    #[test]
    fn close_drains_before_eof_and_abort_discards() {
        let queue = PacketQueue::new(4, MemoryQueuePolicy::Drop);
        queue.push_shared(data(4), ENDPOINT).expect("push");
        queue.close();
        assert_eq!(queue.recv_shared(ENDPOINT).expect("drain"), Some(data(4)));
        assert_eq!(queue.recv_shared(ENDPOINT).expect("eof"), None);
        assert!(matches!(
            queue.push_shared(data(0), ENDPOINT),
            Err(Error::QueueClosed { .. })
        ));

        let queue = PacketQueue::new(4, MemoryQueuePolicy::Drop);
        queue.push_shared(data(4), ENDPOINT).expect("push");
        queue.abort();
        assert!(matches!(
            queue.recv_shared(ENDPOINT),
            Err(Error::QueueAborted { .. })
        ));
        assert!(matches!(
            queue.push_shared(data(0), ENDPOINT),
            Err(Error::QueueAborted { .. })
        ));
    }

    #[test]
    fn backpressured_producer_wakes_when_consumer_frees_capacity() {
        let queue = Arc::new(PacketQueue::new(4, MemoryQueuePolicy::Backpressure));
        queue.push_shared(data(4), ENDPOINT).expect("initial push");
        let barrier = Arc::new(Barrier::new(2));
        let (sent, received) = mpsc::channel();
        let worker_queue = Arc::clone(&queue);
        let worker_barrier = Arc::clone(&barrier);
        let producer = thread::spawn(move || {
            worker_barrier.wait();
            let result = worker_queue.push_shared(data(4), ENDPOINT);
            sent.send(result).expect("send producer result");
        });

        barrier.wait();
        assert_eq!(queue.recv_shared(ENDPOINT).expect("receive"), Some(data(4)));
        assert!(matches!(
            received.recv().expect("producer result"),
            Ok(MemoryPushOutcome::Accepted)
        ));
        producer.join().expect("producer join");
    }

    #[test]
    fn close_wakes_backpressured_producer_with_closed_error() {
        let queue = Arc::new(PacketQueue::new(4, MemoryQueuePolicy::Backpressure));
        queue.push_shared(data(4), ENDPOINT).expect("initial push");
        let barrier = Arc::new(Barrier::new(2));
        let (sent, received) = mpsc::channel();
        let worker_queue = Arc::clone(&queue);
        let worker_barrier = Arc::clone(&barrier);
        let producer = thread::spawn(move || {
            worker_barrier.wait();
            sent.send(worker_queue.push_shared(data(4), ENDPOINT))
                .expect("send producer result");
        });

        barrier.wait();
        queue.close();
        assert!(matches!(
            received.recv().expect("producer result"),
            Err(Error::QueueClosed { .. })
        ));
        producer.join().expect("producer join");
    }
}