tokio/io/
mod.rs

1//! Traits, helpers, and type definitions for asynchronous I/O functionality.
2//!
3//! This module is the asynchronous version of `std::io`. Primarily, it
4//! defines two traits, [`AsyncRead`] and [`AsyncWrite`], which are asynchronous
5//! versions of the [`Read`] and [`Write`] traits in the standard library.
6//!
7//! # AsyncRead and AsyncWrite
8//!
9//! Like the standard library's [`Read`] and [`Write`] traits, [`AsyncRead`] and
10//! [`AsyncWrite`] provide the most general interface for reading and writing
11//! input and output. Unlike the standard library's traits, however, they are
12//! _asynchronous_ &mdash; meaning that reading from or writing to a `tokio::io`
13//! type will _yield_ to the Tokio scheduler when IO is not ready, rather than
14//! blocking. This allows other tasks to run while waiting on IO.
15//!
16//! Another difference is that `AsyncRead` and `AsyncWrite` only contain
17//! core methods needed to provide asynchronous reading and writing
18//! functionality. Instead, utility methods are defined in the [`AsyncReadExt`]
19//! and [`AsyncWriteExt`] extension traits. These traits are automatically
20//! implemented for all values that implement `AsyncRead` and `AsyncWrite`
21//! respectively.
22//!
23//! End users will rarely interact directly with `AsyncRead` and
24//! `AsyncWrite`. Instead, they will use the async functions defined in the
25//! extension traits. Library authors are expected to implement `AsyncRead`
26//! and `AsyncWrite` in order to provide types that behave like byte streams.
27//!
28//! Even with these differences, Tokio's `AsyncRead` and `AsyncWrite` traits
29//! can be used in almost exactly the same manner as the standard library's
30//! `Read` and `Write`. Most types in the standard library that implement `Read`
31//! and `Write` have asynchronous equivalents in `tokio` that implement
32//! `AsyncRead` and `AsyncWrite`, such as [`File`] and [`TcpStream`].
33//!
34//! For example, the standard library documentation introduces `Read` by
35//! [demonstrating][std_example] reading some bytes from a [`std::fs::File`]. We
36//! can do the same with [`tokio::fs::File`][`File`]:
37//!
38//! ```no_run
39//! use tokio::io::{self, AsyncReadExt};
40//! use tokio::fs::File;
41//!
42//! #[tokio::main]
43//! async fn main() -> io::Result<()> {
44//!     let mut f = File::open("foo.txt").await?;
45//!     let mut buffer = [0; 10];
46//!
47//!     // read up to 10 bytes
48//!     let n = f.read(&mut buffer).await?;
49//!
50//!     println!("The bytes: {:?}", &buffer[..n]);
51//!     Ok(())
52//! }
53//! ```
54//!
55//! [`File`]: crate::fs::File
56//! [`TcpStream`]: crate::net::TcpStream
57//! [`std::fs::File`]: std::fs::File
58//! [std_example]: std::io#read-and-write
59//!
60//! ## Buffered Readers and Writers
61//!
62//! Byte-based interfaces are unwieldy and can be inefficient, as we'd need to be
63//! making near-constant calls to the operating system. To help with this,
64//! `std::io` comes with [support for _buffered_ readers and writers][stdbuf],
65//! and therefore, `tokio::io` does as well.
66//!
67//! Tokio provides an async version of the [`std::io::BufRead`] trait,
68//! [`AsyncBufRead`]; and async [`BufReader`] and [`BufWriter`] structs, which
69//! wrap readers and writers. These wrappers use a buffer, reducing the number
70//! of calls and providing nicer methods for accessing exactly what you want.
71//!
72//! For example, [`BufReader`] works with the [`AsyncBufRead`] trait to add
73//! extra methods to any async reader:
74//!
75//! ```no_run
76//! use tokio::io::{self, BufReader, AsyncBufReadExt};
77//! use tokio::fs::File;
78//!
79//! #[tokio::main]
80//! async fn main() -> io::Result<()> {
81//!     let f = File::open("foo.txt").await?;
82//!     let mut reader = BufReader::new(f);
83//!     let mut buffer = String::new();
84//!
85//!     // read a line into buffer
86//!     reader.read_line(&mut buffer).await?;
87//!
88//!     println!("{}", buffer);
89//!     Ok(())
90//! }
91//! ```
92//!
93//! [`BufWriter`] doesn't add any new ways of writing; it just buffers every call
94//! to [`write`](crate::io::AsyncWriteExt::write). However, you **must** flush
95//! [`BufWriter`] to ensure that any buffered data is written.
96//!
97//! ```no_run
98//! use tokio::io::{self, BufWriter, AsyncWriteExt};
99//! use tokio::fs::File;
100//!
101//! #[tokio::main]
102//! async fn main() -> io::Result<()> {
103//!     let f = File::create("foo.txt").await?;
104//!     {
105//!         let mut writer = BufWriter::new(f);
106//!
107//!         // Write a byte to the buffer.
108//!         writer.write(&[42u8]).await?;
109//!
110//!         // Flush the buffer before it goes out of scope.
111//!         writer.flush().await?;
112//!
113//!     } // Unless flushed or shut down, the contents of the buffer is discarded on drop.
114//!
115//!     Ok(())
116//! }
117//! ```
118//!
119//! [stdbuf]: std::io#bufreader-and-bufwriter
120//! [`std::io::BufRead`]: std::io::BufRead
121//! [`AsyncBufRead`]: crate::io::AsyncBufRead
122//! [`BufReader`]: crate::io::BufReader
123//! [`BufWriter`]: crate::io::BufWriter
124//!
125//! ## Implementing AsyncRead and AsyncWrite
126//!
127//! Because they are traits, we can implement [`AsyncRead`] and [`AsyncWrite`] for
128//! our own types, as well. Note that these traits must only be implemented for
129//! non-blocking I/O types that integrate with the futures type system. In
130//! other words, these types must never block the thread, and instead the
131//! current task is notified when the I/O resource is ready.
132//!
133//! ## Conversion to and from Sink/Stream
134//!
135//! It is often convenient to encapsulate the reading and writing of
136//! bytes and instead work with a [`Sink`] or [`Stream`] of some data
137//! type that is encoded as bytes and/or decoded from bytes. Tokio
138//! provides some utility traits in the [tokio-util] crate that
139//! abstract the asynchronous buffering that is required and allows
140//! you to write [`Encoder`] and [`Decoder`] functions working with a
141//! buffer of bytes, and then use that ["codec"] to transform anything
142//! that implements [`AsyncRead`] and [`AsyncWrite`] into a `Sink`/`Stream` of
143//! your structured data.
144//!
145//! [tokio-util]: https://docs.rs/tokio-util/0.6/tokio_util/codec/index.html
146//!
147//! # Standard input and output
148//!
149//! Tokio provides asynchronous APIs to standard [input], [output], and [error].
150//! These APIs are very similar to the ones provided by `std`, but they also
151//! implement [`AsyncRead`] and [`AsyncWrite`].
152//!
153//! Note that the standard input / output APIs  **must** be used from the
154//! context of the Tokio runtime, as they require Tokio-specific features to
155//! function. Calling these functions outside of a Tokio runtime will panic.
156//!
157//! [input]: fn@stdin
158//! [output]: fn@stdout
159//! [error]: fn@stderr
160//!
161//! # `std` re-exports
162//!
163//! Additionally, [`Error`], [`ErrorKind`], [`Result`], and [`SeekFrom`] are
164//! re-exported from `std::io` for ease of use.
165//!
166//! [`AsyncRead`]: trait@AsyncRead
167//! [`AsyncWrite`]: trait@AsyncWrite
168//! [`AsyncReadExt`]: trait@AsyncReadExt
169//! [`AsyncWriteExt`]: trait@AsyncWriteExt
170//! ["codec"]: https://docs.rs/tokio-util/0.6/tokio_util/codec/index.html
171//! [`Encoder`]: https://docs.rs/tokio-util/0.6/tokio_util/codec/trait.Encoder.html
172//! [`Decoder`]: https://docs.rs/tokio-util/0.6/tokio_util/codec/trait.Decoder.html
173//! [`Error`]: struct@Error
174//! [`ErrorKind`]: enum@ErrorKind
175//! [`Result`]: type@Result
176//! [`Read`]: std::io::Read
177//! [`SeekFrom`]: enum@SeekFrom
178//! [`Sink`]: https://docs.rs/futures/0.3/futures/sink/trait.Sink.html
179//! [`Stream`]: https://docs.rs/futures/0.3/futures/stream/trait.Stream.html
180//! [`Write`]: std::io::Write
181cfg_io_blocking! {
182    pub(crate) mod blocking;
183}
184
185mod async_buf_read;
186pub use self::async_buf_read::AsyncBufRead;
187
188mod async_read;
189pub use self::async_read::AsyncRead;
190
191mod async_seek;
192pub use self::async_seek::AsyncSeek;
193
194mod async_write;
195pub use self::async_write::AsyncWrite;
196
197mod read_buf;
198pub use self::read_buf::ReadBuf;
199
200// Re-export some types from `std::io` so that users don't have to deal
201// with conflicts when `use`ing `tokio::io` and `std::io`.
202#[doc(no_inline)]
203pub use std::io::{Error, ErrorKind, Result, SeekFrom};
204
205cfg_io_driver_impl! {
206    pub(crate) mod interest;
207    pub(crate) mod ready;
208
209    cfg_net! {
210        pub use interest::Interest;
211        pub use ready::Ready;
212    }
213
214    #[cfg_attr(tokio_wasi, allow(unused_imports))]
215    mod poll_evented;
216
217    #[cfg(not(loom))]
218    #[cfg_attr(tokio_wasi, allow(unused_imports))]
219    pub(crate) use poll_evented::PollEvented;
220}
221
222cfg_aio! {
223    /// BSD-specific I/O types.
224    pub mod bsd {
225        mod poll_aio;
226
227        pub use poll_aio::{Aio, AioEvent, AioSource};
228    }
229}
230
231cfg_net_unix! {
232    mod async_fd;
233
234    pub mod unix {
235        //! Asynchronous IO structures specific to Unix-like operating systems.
236        pub use super::async_fd::{AsyncFd, AsyncFdReadyGuard, AsyncFdReadyMutGuard, TryIoError};
237    }
238}
239
240cfg_io_std! {
241    mod stdio_common;
242
243    mod stderr;
244    pub use stderr::{stderr, Stderr};
245
246    mod stdin;
247    pub use stdin::{stdin, Stdin};
248
249    mod stdout;
250    pub use stdout::{stdout, Stdout};
251}
252
253cfg_io_util! {
254    mod split;
255    pub use split::{split, ReadHalf, WriteHalf};
256
257    pub(crate) mod seek;
258    pub(crate) mod util;
259    pub use util::{
260        copy, copy_bidirectional, copy_buf, duplex, empty, repeat, sink, AsyncBufReadExt, AsyncReadExt, AsyncSeekExt, AsyncWriteExt,
261        BufReader, BufStream, BufWriter, DuplexStream, Empty, Lines, Repeat, Sink, Split, Take,
262    };
263}
264
265cfg_not_io_util! {
266    cfg_process! {
267        pub(crate) mod util;
268    }
269}
270
271cfg_io_blocking! {
272    /// Types in this module can be mocked out in tests.
273    mod sys {
274        // TODO: don't rename
275        pub(crate) use crate::blocking::spawn_blocking as run;
276        pub(crate) use crate::blocking::JoinHandle as Blocking;
277    }
278}
tokio/io/mod.rs

tokio/io/
mod.rs
