Skip to main content

threers_codec/
bytes.rs

1//! Bytes shared between readers without copying: a buffer in memory, or a
2//! file mapped into it.
3//!
4//! A 4K or 8K film runs to gigabytes. Reading one whole into a `Vec` before
5//! the first picture means waiting for all of it and holding all of it.
6//! Mapped, the operating system pages in what the demuxer and decoder touch,
7//! as they touch it, and drops it again under memory pressure; the first
8//! picture is ready after reading the index and one sample. Everything here
9//! that takes a whole file ([`VideoReader`](crate::decode::VideoReader),
10//! [`demux`](crate::decode::demux), the audio decoders) takes a slice, so a
11//! mapping slots in anywhere a `Vec` did.
12//!
13//! ```no_run
14//! use threers_codec::bytes::Bytes;
15//!
16//! let file = Bytes::map("film.mp4").unwrap();
17//! println!("{} bytes, mapped: {}", file.len(), file.is_mapped());
18//! ```
19
20use std::ops::Deref;
21use std::path::Path;
22use std::sync::Arc;
23
24/// Shared, immutable bytes: cheap to clone, from memory or a mapped file.
25#[derive(Clone)]
26pub struct Bytes(Arc<dyn AsRef<[u8]> + Send + Sync>, bool);
27
28impl std::fmt::Debug for Bytes {
29    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
30        f.debug_struct("Bytes")
31            .field("len", &self.len())
32            .field("mapped", &self.1)
33            .finish()
34    }
35}
36
37impl Bytes {
38    /// Map the file at `path` read-only, where the platform can (Unix);
39    /// elsewhere it is read into memory. The file must not be changed while
40    /// mapped: like every program that maps files, this reads what is there.
41    pub fn map(path: impl AsRef<Path>) -> std::io::Result<Self> {
42        let file = std::fs::File::open(path)?;
43        #[cfg(unix)]
44        {
45            if let Some(map) = mmap::Map::new(&file)? {
46                return Ok(Self(Arc::new(map), true));
47            }
48        }
49        use std::io::Read;
50        let mut data = Vec::new();
51        (&file).read_to_end(&mut data)?;
52        Ok(Self::from(data))
53    }
54
55    /// Whether the bytes are a mapping of a file rather than a buffer.
56    pub fn is_mapped(&self) -> bool {
57        self.1
58    }
59}
60
61impl Deref for Bytes {
62    type Target = [u8];
63    fn deref(&self) -> &[u8] {
64        (*self.0).as_ref()
65    }
66}
67
68impl AsRef<[u8]> for Bytes {
69    fn as_ref(&self) -> &[u8] {
70        self
71    }
72}
73
74impl From<Vec<u8>> for Bytes {
75    fn from(v: Vec<u8>) -> Self {
76        Self(Arc::new(v), false)
77    }
78}
79
80impl From<Arc<Vec<u8>>> for Bytes {
81    fn from(v: Arc<Vec<u8>>) -> Self {
82        Self(Arc::new(VecRef(v)), false)
83    }
84}
85
86struct VecRef(Arc<Vec<u8>>);
87
88impl AsRef<[u8]> for VecRef {
89    fn as_ref(&self) -> &[u8] {
90        &self.0
91    }
92}
93
94/// Picture buffers handed back to be filled again: the big byte buffers a
95/// hardware decoder copies each picture into.
96///
97/// A fresh 50 MB buffer for every 8K picture costs more than the copy into
98/// it: the system hands over new pages that are faulted in and zeroed on
99/// first touch (measured on Linux, about 10 ms a picture against 2 ms for
100/// the copy). A decoder that takes its buffers from here, and a player that
101/// gives each picture's buffers back once it is off the screen, reuse a few
102/// buffers for the whole film. Cheap to clone; every clone is the same pool.
103/// It keeps at most a handful of buffers; the rest are freed.
104#[derive(Clone, Default, Debug)]
105pub struct FramePool(Arc<std::sync::Mutex<Vec<Vec<u8>>>>);
106
107impl FramePool {
108    /// How many buffers it keeps: a luma and a chroma buffer for each of the
109    /// pictures a player holds at once (decoded ahead, due, on screen).
110    const KEEP: usize = 12;
111
112    /// An empty buffer with room for `len` bytes: the smallest given back
113    /// that is big enough, or a new one.
114    pub fn take(&self, len: usize) -> Vec<u8> {
115        let mut held = self.0.lock().unwrap_or_else(|e| e.into_inner());
116        let fit = held
117            .iter()
118            .enumerate()
119            .filter(|(_, b)| b.capacity() >= len)
120            .min_by_key(|(_, b)| b.capacity())
121            .map(|(i, _)| i);
122        match fit {
123            Some(i) => {
124                let mut buf = held.swap_remove(i);
125                buf.clear();
126                buf
127            }
128            None => Vec::with_capacity(len),
129        }
130    }
131
132    /// Give `buf` back, to be taken again.
133    pub fn give(&self, buf: Vec<u8>) {
134        if buf.capacity() == 0 {
135            return;
136        }
137        let mut held = self.0.lock().unwrap_or_else(|e| e.into_inner());
138        if held.len() < Self::KEEP {
139            held.push(buf);
140        }
141    }
142
143    /// Buffers waiting to be taken.
144    pub fn len(&self) -> usize {
145        self.0.lock().unwrap_or_else(|e| e.into_inner()).len()
146    }
147
148    /// Whether none are.
149    pub fn is_empty(&self) -> bool {
150        self.len() == 0
151    }
152}
153
154#[cfg(unix)]
155mod mmap {
156    use std::ffi::c_void;
157    use std::os::fd::AsRawFd;
158
159    const PROT_READ: i32 = 1;
160    const MAP_PRIVATE: i32 = 2;
161    /// `MADV_SEQUENTIAL`, 2 on Linux and the BSDs (macOS included).
162    const MADV_SEQUENTIAL: i32 = 2;
163
164    unsafe extern "C" {
165        fn mmap(
166            addr: *mut c_void,
167            len: usize,
168            prot: i32,
169            flags: i32,
170            fd: i32,
171            offset: i64,
172        ) -> *mut c_void;
173        fn munmap(addr: *mut c_void, len: usize) -> i32;
174        fn madvise(addr: *mut c_void, len: usize, advice: i32) -> i32;
175    }
176
177    /// A read-only private mapping of a whole file.
178    pub(super) struct Map {
179        ptr: *mut c_void,
180        len: usize,
181    }
182
183    // Read-only memory nobody writes through.
184    unsafe impl Send for Map {}
185    unsafe impl Sync for Map {}
186
187    impl Map {
188        /// `None` for an empty file, which has nothing to map.
189        pub(super) fn new(file: &std::fs::File) -> std::io::Result<Option<Self>> {
190            let len = file.metadata()?.len();
191            if len == 0 {
192                return Ok(None);
193            }
194            let len =
195                usize::try_from(len).map_err(|_| std::io::Error::other("file too large to map"))?;
196            let ptr = unsafe {
197                mmap(
198                    std::ptr::null_mut(),
199                    len,
200                    PROT_READ,
201                    MAP_PRIVATE,
202                    file.as_raw_fd(),
203                    0,
204                )
205            };
206            if ptr as isize == -1 {
207                return Err(std::io::Error::last_os_error());
208            }
209            // Demuxing and decoding read a video front to back: ask for
210            // read-ahead. Advice only; a refusal changes nothing.
211            unsafe { madvise(ptr, len, MADV_SEQUENTIAL) };
212            Ok(Some(Self { ptr, len }))
213        }
214    }
215
216    impl AsRef<[u8]> for Map {
217        fn as_ref(&self) -> &[u8] {
218            unsafe { std::slice::from_raw_parts(self.ptr as *const u8, self.len) }
219        }
220    }
221
222    impl Drop for Map {
223        fn drop(&mut self) {
224            unsafe { munmap(self.ptr, self.len) };
225        }
226    }
227}
228
229#[cfg(test)]
230mod tests {
231    use super::*;
232
233    #[test]
234    fn a_mapped_file_reads_as_its_bytes() {
235        let path = std::env::temp_dir().join(format!("threers-bytes-{}.bin", std::process::id()));
236        let data: Vec<u8> = (0..100_000u32).map(|i| (i * 7 % 251) as u8).collect();
237        std::fs::write(&path, &data).unwrap();
238        let mapped = Bytes::map(&path).unwrap();
239        assert_eq!(mapped.is_mapped(), cfg!(unix));
240        assert_eq!(&mapped[..], &data[..]);
241        let shared = mapped.clone();
242        drop(mapped);
243        assert_eq!(
244            shared[99_999], data[99_999],
245            "a clone keeps the mapping alive"
246        );
247        drop(shared);
248        std::fs::write(&path, b"").unwrap();
249        assert!(
250            Bytes::map(&path).unwrap().is_empty(),
251            "an empty file maps to nothing"
252        );
253        std::fs::remove_file(&path).unwrap();
254        assert!(Bytes::from(vec![1, 2, 3]).iter().eq([1u8, 2, 3].iter()));
255    }
256
257    #[test]
258    fn a_frame_pool_hands_back_the_closest_fit() {
259        let pool = FramePool::default();
260        let fresh = pool.take(100);
261        assert!(fresh.capacity() >= 100 && fresh.is_empty());
262        let (mut big, small) = (Vec::with_capacity(1000), Vec::<u8>::with_capacity(300));
263        big.extend_from_slice(&[7; 10]);
264        let (big_at, small_at) = (big.as_ptr(), small.as_ptr());
265        pool.give(big);
266        pool.give(small);
267        pool.give(Vec::new());
268        assert_eq!(pool.len(), 2, "an empty buffer is not kept");
269        let got = pool.take(200);
270        assert_eq!(got.as_ptr(), small_at, "the smallest that fits");
271        let got = pool.take(500);
272        assert_eq!(got.as_ptr(), big_at);
273        assert!(got.is_empty(), "handed back empty");
274        assert!(pool.is_empty());
275        for _ in 0..20 {
276            pool.give(vec![0; 4]);
277        }
278        assert_eq!(pool.len(), FramePool::KEEP, "the rest are freed");
279    }
280}