compio_io/lib.rs
1//! This crate provides traits and utilities for completion-based IO.
2//!
3//! # Contents
4//! ### Fundamental
5//!
6//! - [`AsyncRead`]: Async read into a buffer implements [`IoBufMut`]
7//! - [`AsyncReadAt`]: Async read into a buffer implements [`IoBufMut`] with
8//! offset
9//! - [`AsyncWrite`]: Async write from a buffer implements [`IoBuf`]
10//! - [`AsyncWriteAt`]: Async write from a buffer implements [`IoBuf`] with
11//! offset
12//!
13//! ### Buffered IO
14//!
15//! - [`AsyncBufRead`]: Trait of async read with buffered content
16//! - [`BufReader`]: An async reader with internal buffer
17//! - [`BufWriter`]: An async writer with internal buffer
18//!
19//! ### Extension
20//!
21//! - [`AsyncReadExt`]: Extension trait for [`AsyncRead`]
22//! - [`AsyncReadAtExt`]: Extension trait for [`AsyncReadAt`]
23//! - [`AsyncWriteExt`]: Extension trait for [`AsyncWrite`]
24//! - [`AsyncWriteAtExt`]: Extension trait for [`AsyncWriteAt`]
25//!
26//!
27//! [`IoBufMut`]: compio_buf::IoBufMut
28//! [`IoBuf`]: compio_buf::IoBuf
29//!
30//! # Examples
31//!
32//! ### Read
33//!
34//! ```
35//! use compio_buf::BufResult;
36//! use compio_io::AsyncRead;
37//! # compio_runtime::Runtime::new().unwrap().block_on(async {
38//!
39//! let mut reader = "Hello, world!".as_bytes();
40//! let (res, buf) = reader.read(Vec::with_capacity(20)).await.unwrap();
41//!
42//! assert_eq!(buf.as_slice(), b"Hello, world!");
43//! assert_eq!(res, 13);
44//! # })
45//! ```
46//!
47//! ### Write
48//!
49//! Writing to a fixed-size buffer wrapped by [`Cursor`](std::io::Cursor). The
50//! implementation will write the content start at the current
51//! [`position`](std::io::Cursor::position):
52//!
53//! ```
54//! use std::io::Cursor;
55//!
56//! use compio_buf::BufResult;
57//! use compio_io::AsyncWrite;
58//! # compio_runtime::Runtime::new().unwrap().block_on(async {
59//!
60//! let mut writer = Cursor::new([0; 6]);
61//! writer.set_position(2);
62//! let (n, buf) = writer.write(vec![1, 1, 1, 1, 1, 1]).await.unwrap();
63//!
64//! assert_eq!(n, 4);
65//! assert_eq!(writer.into_inner(), [0, 0, 1, 1, 1, 1]);
66//! # })
67//! ```
68//!
69//! Writing to `Vec<u8>`, which is extendable. Notice that the implementation
70//! will append the content to the end:
71//!
72//! ```
73//! use compio_buf::BufResult;
74//! use compio_io::AsyncWrite;
75//! # compio_runtime::Runtime::new().unwrap().block_on(async {
76//!
77//! let mut writer = vec![1, 2, 3];
78//! let (_, buf) = writer.write(vec![3, 2, 1]).await.unwrap();
79//!
80//! assert_eq!(writer, [1, 2, 3, 3, 2, 1]);
81//! # })
82//! ```
83//!
84//! This crate doesn't depend on a specific runtime. It can work with `tokio`
85//! well:
86//! ```
87//! use compio_buf::BufResult;
88//! use compio_io::AsyncWrite;
89//!
90//! #[tokio::main(flavor = "current_thread")]
91//! async fn main() {
92//! let mut writer = vec![1, 2, 3];
93//! let (_, buf) = writer.write(vec![3, 2, 1]).await.unwrap();
94//!
95//! assert_eq!(writer, [1, 2, 3, 3, 2, 1]);
96//! }
97//! ```
98
99#![warn(missing_docs)]
100// This is OK as we're thread-per-core and don't need `Send` or other auto trait on anonymous future
101#![allow(async_fn_in_trait)]
102#![cfg_attr(feature = "allocator_api", feature(allocator_api))]
103#![cfg_attr(feature = "read_buf", feature(read_buf, core_io_borrowed_buf))]
104#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
105
106mod buffer;
107#[cfg(feature = "compat")]
108pub mod compat;
109mod read;
110mod split;
111pub mod util;
112mod write;
113
114pub(crate) type IoResult<T> = std::io::Result<T>;
115
116pub use read::*;
117pub use split::*;
118pub use util::{copy, null, repeat};
119pub use write::*;