1 use super::queue::{direction::Direction, Queue, QueueInit};
2 use crate::ioctl::{self, DqBufResult, V4l2BufferFromError};
3 use std::fmt::Debug;
4 
5 /// Trait for trying to dequeue a readable buffer from a queue.
6 pub trait TryDequeue {
7     type Dequeued: Debug + Send;
8 
9     /// Try to dequeue and return the next processed buffer.
10     ///
11     /// The V4L2 buffer will not be reused until the returned value is dropped.
12     /// It can be moved into a `Rc` or `Arc` and passed across threads.
13     ///
14     /// The data in the `DQBuffer` is read-only.
try_dequeue(&self) -> DqBufResult<Self::Dequeued, V4l2BufferFromError>15     fn try_dequeue(&self) -> DqBufResult<Self::Dequeued, V4l2BufferFromError>;
16 }
17 
18 /// Trait for streaming a queue on and off.
19 ///
20 /// The `Canceled` generic type is the type
21 /// for returned cancelled buffers, i.e. buffers that were queued prior to the
22 /// call to `stream_off()` but were not yet dequeued.
23 pub trait Stream {
24     type Canceled;
25 
26     /// Start streaming. Buffers queued prior to calling this method will start
27     /// being processed.
stream_on(&self) -> Result<(), ioctl::StreamOnError>28     fn stream_on(&self) -> Result<(), ioctl::StreamOnError>;
29 
30     /// Stop streaming.
31     ///
32     /// If successful, then all the buffers that are queued but have not been
33     /// dequeued yet return to the `Free` state, and be returned as `Canceled`.
stream_off(&self) -> Result<Vec<Self::Canceled>, ioctl::StreamOffError>34     fn stream_off(&self) -> Result<Vec<Self::Canceled>, ioctl::StreamOffError>;
35 }
36 
37 pub struct FreeBuffersResult<D: Direction, S: Stream> {
38     pub queue: Queue<D, QueueInit>,
39     pub canceled_buffers: Vec<S::Canceled>,
40 }
41 
42 /// Trait for a configured queue, i.e. a queue on which we can queue and dequeue
43 /// buffers.
44 pub trait AllocatedQueue<'a, D: Direction>: TryDequeue + Stream + Sized {
45     /// Returns the total number of buffers allocated for this queue.
num_buffers(&self) -> usize46     fn num_buffers(&self) -> usize;
47 
48     /// Returns the number of buffers that we can currently obtain and queue.
num_free_buffers(&self) -> usize49     fn num_free_buffers(&self) -> usize;
50 
51     /// Returns the number of buffers currently queued (i.e. being processed
52     /// or awaiting to be dequeued).
num_queued_buffers(&self) -> usize53     fn num_queued_buffers(&self) -> usize;
54 
55     /// Release all the allocated buffers and returns the queue to the `Init` state.
56     /// If successful, any queued buffer is also returned as canceled.
57     /// In case of failure, the queue and its currently queued buffers are lost.
free_buffers(self) -> Result<FreeBuffersResult<D, Self>, ioctl::ReqbufsError>58     fn free_buffers(self) -> Result<FreeBuffersResult<D, Self>, ioctl::ReqbufsError>;
59 }
60