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//! ### Adapters
27//! - [`framed::Framed`]: Adapts [`AsyncRead`] to [`Stream`] and [`AsyncWrite`]
28//! to [`Sink`], with framed de/encoding.
29//! - [`compat::SyncStream`]: Adapts async IO to std blocking io (requires
30//! `compat` feature)
31//! - [`compat::AsyncStream`]: Adapts async IO to [`futures_util::io`] traits
32//! (requires `compat` feature)
33//!
34//! [`IoBufMut`]: compio_buf::IoBufMut
35//! [`IoBuf`]: compio_buf::IoBuf
36//! [`Sink`]: futures_util::Sink
37//! [`Stream`]: futures_util::Stream
38//!
39//! # Examples
40//!
41//! ### Read
42//!
43//! ```
44//! use compio_buf::BufResult;
45//! use compio_io::AsyncRead;
46//! # compio_runtime::Runtime::new().unwrap().block_on(async {
47//!
48//! let mut reader = "Hello, world!".as_bytes();
49//! let (res, buf) = reader.read(Vec::with_capacity(20)).await.unwrap();
50//!
51//! assert_eq!(buf.as_slice(), b"Hello, world!");
52//! assert_eq!(res, 13);
53//! # })
54//! ```
55//!
56//! ### Write
57//!
58//! Writing to a fixed-size buffer wrapped by [`Cursor`](std::io::Cursor). The
59//! implementation will write the content start at the current
60//! [`position`](std::io::Cursor::position):
61//!
62//! ```
63//! use std::io::Cursor;
64//!
65//! use compio_buf::BufResult;
66//! use compio_io::AsyncWrite;
67//! # compio_runtime::Runtime::new().unwrap().block_on(async {
68//!
69//! let mut writer = Cursor::new([0; 6]);
70//! writer.set_position(2);
71//! let (n, buf) = writer.write(vec![1, 1, 1, 1, 1, 1]).await.unwrap();
72//!
73//! assert_eq!(n, 4);
74//! assert_eq!(writer.into_inner(), [0, 0, 1, 1, 1, 1]);
75//! # })
76//! ```
77//!
78//! Writing to `Vec<u8>`, which is extendable. Notice that the implementation
79//! will append the content to the end:
80//!
81//! ```
82//! use compio_buf::BufResult;
83//! use compio_io::AsyncWrite;
84//! # compio_runtime::Runtime::new().unwrap().block_on(async {
85//!
86//! let mut writer = vec![1, 2, 3];
87//! let (_, buf) = writer.write(vec![3, 2, 1]).await.unwrap();
88//!
89//! assert_eq!(writer, [1, 2, 3, 3, 2, 1]);
90//! # })
91//! ```
92//!
93//! This crate doesn't depend on a specific runtime. It can work with `tokio`
94//! well:
95//! ```
96//! use compio_buf::BufResult;
97//! use compio_io::AsyncWrite;
98//!
99//! #[tokio::main(flavor = "current_thread")]
100//! async fn main() {
101//! let mut writer = vec![1, 2, 3];
102//! let (_, buf) = writer.write(vec![3, 2, 1]).await.unwrap();
103//!
104//! assert_eq!(writer, [1, 2, 3, 3, 2, 1]);
105//! }
106//! ```
107
108#![warn(missing_docs)]
109// This is OK as we're thread-per-core and don't need `Send` or other auto trait on anonymous future
110#![allow(async_fn_in_trait)]
111#![cfg_attr(feature = "allocator_api", feature(allocator_api))]
112#![cfg_attr(feature = "read_buf", feature(read_buf, core_io_borrowed_buf))]
113#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
114
115use std::{future::Future, pin::Pin};
116type PinBoxFuture<T> = Pin<Box<dyn Future<Output = T>>>;
117
118mod buffer;
119pub mod framed;
120
121#[cfg(feature = "compat")]
122pub mod compat;
123mod read;
124pub mod util;
125mod write;
126
127pub(crate) type IoResult<T> = std::io::Result<T>;
128
129pub use read::*;
130#[doc(inline)]
131pub use util::{
132 copy, null, repeat,
133 split::{split, split_unsync},
134};
135pub use write::*;