feat(io): read-multi traits (#732)

* feat(io): traits for async read multi

* docs(io): managed & multi read

* feat(io): use new managed traits

* docs(io): fix broken links

* docs(io): `len` is for each time

Author: Berrysoft

compio-io/src/lib.rs

@@ -16,6 +16,15 @@
 //! - [`BufReader`]: An async reader with internal buffer
 //! - [`BufWriter`]: An async writer with internal buffer
 //!
+//! ### Managed IO
+//!
+//! - [`AsyncReadManaged`]: Async read with a managed buffer
+//! - [`AsyncReadManagedAt`]: Async read with a managed buffer and offset
+//! - [`AsyncReadMulti`]: Async read, and returns a stream of multiple managed
+//!   buffers
+//! - [`AsyncReadMultiAt`]: Async read with offset, and returns a stream of
+//!   multiple managed buffers
+//!
 //! ### Extension
 //!
 //! - [`AsyncReadExt`]: Extension trait for [`AsyncRead`]

compio-io/src/read/mod.rs

@@ -8,10 +8,12 @@ mod buf;
 #[macro_use]
 mod ext;
 mod managed;
+mod multi;
 
 pub use buf::*;
 pub use ext::*;
 pub use managed::*;
+pub use multi::*;
 
 use crate::util::{slice_to_buf, slice_to_uninit};
 

compio-io/src/read/multi.rs

@@ -0,0 +1,34 @@
+use futures_util::Stream;
+
+use crate::{AsyncReadManaged, AsyncReadManagedAt, IoResult};
+
+/// # AsyncReadMulti
+///
+/// Async read with buffer pool and returns a stream of managed buffers.
+pub trait AsyncReadMulti: AsyncReadManaged {
+    /// Read some bytes from this source and return a stream of
+    /// [`AsyncReadManaged::Buffer`].
+    ///
+    /// # Implementation Note
+    ///
+    /// - If `len` == 0, implementation should use buffer's size as `len`
+    /// - if `len` > 0, `min(len, buffer_size)` will be the max number of bytes
+    ///   to be read each time.
+    fn read_multi(&mut self, len: usize) -> impl Stream<Item = IoResult<Self::Buffer>>;
+}
+
+/// # AsyncReadMultiAt
+///
+/// Async read with buffer pool and position, returns a stream of managed
+/// buffers.
+pub trait AsyncReadMultiAt: AsyncReadManagedAt {
+    /// Read some bytes from this source at position and return a stream of
+    /// [`AsyncReadManagedAt::Buffer`].
+    ///
+    /// # Implementation Note
+    ///
+    /// - If `len` == 0, implementation should use buffer's size as `len`
+    /// - if `len` > 0, `min(len, buffer_size)` will be the max number of bytes
+    ///   to be read each time.
+    fn read_multi_at(&self, len: usize, pos: u64) -> impl Stream<Item = IoResult<Self::Buffer>>;
+}