README.md
1# Tokio
2
3A runtime for writing reliable, asynchronous, and slim applications with
4the Rust programming language. It is:
5
6* **Fast**: Tokio's zero-cost abstractions give you bare-metal
7 performance.
8
9* **Reliable**: Tokio leverages Rust's ownership, type system, and
10 concurrency model to reduce bugs and ensure thread safety.
11
12* **Scalable**: Tokio has a minimal footprint, and handles backpressure
13 and cancellation naturally.
14
15[![Crates.io][crates-badge]][crates-url]
16[![MIT licensed][mit-badge]][mit-url]
17[![Build Status][azure-badge]][azure-url]
18[![Discord chat][discord-badge]][discord-url]
19
20[crates-badge]: https://img.shields.io/crates/v/tokio.svg
21[crates-url]: https://crates.io/crates/tokio
22[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
23[mit-url]: LICENSE
24[azure-badge]: https://dev.azure.com/tokio-rs/Tokio/_apis/build/status/tokio-rs.tokio?branchName=master
25[azure-url]: https://dev.azure.com/tokio-rs/Tokio/_build/latest?definitionId=1&branchName=master
26[discord-badge]: https://img.shields.io/discord/500028886025895936.svg?logo=discord&style=flat-square
27[discord-url]: https://discord.gg/6yGkFeN
28
29[Website](https://tokio.rs) |
30[Guides](https://tokio.rs/docs/) |
31[API Docs](https://docs.rs/tokio/0.2/tokio) |
32[Chat](https://discord.gg/6yGkFeN)
33
34## Overview
35
36Tokio is an event-driven, non-blocking I/O platform for writing
37asynchronous applications with the Rust programming language. At a high
38level, it provides a few major components:
39
40* A multithreaded, work-stealing based task [scheduler].
41* A reactor backed by the operating system's event queue (epoll, kqueue,
42 IOCP, etc...).
43* Asynchronous [TCP and UDP][net] sockets.
44
45These components provide the runtime components necessary for building
46an asynchronous application.
47
48[net]: https://docs.rs/tokio/0.2/tokio/net/index.html
49[scheduler]: https://docs.rs/tokio/0.2/tokio/runtime/index.html
50
51## Example
52
53To get started, add the following to `Cargo.toml`.
54
55```toml
56tokio = { version = "0.2", features = ["full"] }
57```
58
59Tokio requires components to be explicitly enabled using feature flags. As a
60shorthand, the `full` feature enables all components.
61
62A basic TCP echo server with Tokio:
63
64```rust,no_run
65use tokio::net::TcpListener;
66use tokio::prelude::*;
67
68#[tokio::main]
69async fn main() -> Result<(), Box<dyn std::error::Error>> {
70 let mut listener = TcpListener::bind("127.0.0.1:8080").await?;
71
72 loop {
73 let (mut socket, _) = listener.accept().await?;
74
75 tokio::spawn(async move {
76 let mut buf = [0; 1024];
77
78 // In a loop, read data from the socket and write the data back.
79 loop {
80 let n = match socket.read(&mut buf).await {
81 // socket closed
82 Ok(n) if n == 0 => return,
83 Ok(n) => n,
84 Err(e) => {
85 eprintln!("failed to read from socket; err = {:?}", e);
86 return;
87 }
88 };
89
90 // Write the data back
91 if let Err(e) = socket.write_all(&buf[0..n]).await {
92 eprintln!("failed to write to socket; err = {:?}", e);
93 return;
94 }
95 }
96 });
97 }
98}
99```
100
101More examples can be found [here](../examples).
102
103## Getting Help
104
105First, see if the answer to your question can be found in the [Guides] or the
106[API documentation]. If the answer is not there, there is an active community in
107the [Tokio Discord server][chat]. We would be happy to try to answer your
108question. Last, if that doesn't work, try opening an [issue] with the question.
109
110[Guides]: https://tokio.rs/docs/
111[API documentation]: https://docs.rs/tokio/0.2
112[chat]: https://discord.gg/6yGkFeN
113[issue]: https://github.com/tokio-rs/tokio/issues/new
114
115## Contributing
116
117:balloon: Thanks for your help improving the project! We are so happy to have
118you! We have a [contributing guide][guide] to help you get involved in the Tokio
119project.
120
121[guide]: CONTRIBUTING.md
122
123## Related Projects
124
125In addition to the crates in this repository, the Tokio project also maintains
126several other libraries, including:
127
128* [`tracing`] (formerly `tokio-trace`): A framework for application-level
129 tracing and async-aware diagnostics.
130
131* [`mio`]: A low-level, cross-platform abstraction over OS I/O APIs that powers
132 `tokio`.
133
134* [`bytes`]: Utilities for working with bytes, including efficient byte buffers.
135
136[`tracing`]: https://github.com/tokio-rs/tracing
137[`mio`]: https://github.com/tokio-rs/mio
138[`bytes`]: https://github.com/tokio-rs/bytes
139
140## Supported Rust Versions
141
142Tokio is built against the latest stable, nightly, and beta Rust releases. The
143minimum version supported is the stable release from three months before the
144current stable release version. For example, if the latest stable Rust is 1.29,
145the minimum version supported is 1.26. The current Tokio version is not
146guaranteed to build on Rust versions earlier than the minimum supported version.
147
148## License
149
150This project is licensed under the [MIT license](LICENSE).
151
152### Contribution
153
154Unless you explicitly state otherwise, any contribution intentionally submitted
155for inclusion in Tokio by you, shall be licensed as MIT, without any additional
156terms or conditions.
157
