1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100
//! This crate provides I/O-related utilities complimenting the Rust Standard //! Library `std::io`, `std::fs`, etc. //! //! ## Overview //! //! The [`fs`] module includes a [`fs::PosRead`] trait, offering a uniform //! `pread` for positioned file reads, and a [`fs::ReadSlice`] supporting //! multiple independent reader instances limited to a fixed start..end range. //! //! The [`io`] module includes a [`io::GatheringReader`], which presents a //! continuous `Read` interface over N non-contiguous byte buffers. //! //! The [`mem`] module includes a [`mem::MemHandle`] supporting prioritized //! concurrent memory access advice (e.g. madvise (2) on unix). //! //! ## Optional Features //! //! _mmap (default):_ Adds [`fs::ReadSlice::mem_map`] support for memory //! mapping. #![warn(rust_2018_idioms)] /// The crate version string. pub static VERSION: &str = env!("CARGO_PKG_VERSION"); /// Filesystem extensions and utilities. /// /// The [`fs::PosRead`] trait offers a uniform `pread` for positioned reads. /// /// The [`fs::ReadPos`] and [`fs::ReadSlice`] types re-implement `Read` and /// `Seek` over any `Borrow` of a `PosRead` type. For `File` in particular, /// this enables multiple independent reader instances, without needing a path /// to open an independent new `File` instance. Thus these types are /// compatible with "unnamed" (not linked) temporary files, and can reduce the /// number of necessary file handles. Note that unix `dup`/`dup2` and the /// standard `File::try_clone` do _not_ provide independent file positions. /// /// ## Example /// /// ``` rust /// # use std::io; /// use std::fs::File; /// use std::io::{Read, Write}; /// use olio::fs::{ReadPos, ReadSlice}; /// use tempfile::tempfile; /// /// # fn run() -> Result<(), io::Error> { /// let mut file = tempfile()?; /// file.write_all(b"0123456789")?; /// /// // ReadPos by &File so that we can subslice by shared reference /// let mut rpos = ReadPos::new(&file, 10); /// /// // Read the first half /// let mut buf = [0u8; 5]; /// rpos.read_exact(&mut buf)?; /// assert_eq!(&buf, b"01234"); /// /// // Create an independent ReadSlice and read to end /// let mut rslice = rpos.subslice(2, 7); /// let mut buf = Vec::new(); /// rslice.read_to_end(&mut buf)?; /// assert_eq!(&buf, b"23456"); /// /// // Read the second half from the original ReadPos /// assert_eq!(rpos.tell(), 5); /// let mut buf = [0u8; 5]; /// rpos.read_exact(&mut buf)?; /// assert_eq!(&buf, b"56789"); /// # Ok(()) /// # } /// # run().unwrap(); /// ``` pub mod fs { mod pos_read; pub use pos_read::PosRead; mod read; pub use read::{ReadPos, ReadSlice}; /// Compatibility type aliases. pub mod rc { use std::fs::File; use std::sync::Arc; pub type ReadPos = super::ReadPos<Arc<File>>; pub type ReadSlice = super::ReadSlice<Arc<File>>; } } /// I/O extensions and utilities pub mod io { mod gather; pub use gather::GatheringReader; } /// Random access memory utilities pub mod mem { mod handle; pub use handle::{MemAdviseError, MemHandle, MemAdvice}; }