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[![Gitter chat][gitter-badge]][gitter-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-MIT
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[gitter-badge]: https://img.shields.io/gitter/room/tokio-rs/tokio.svg
27[gitter-url]: https://gitter.im/tokio-rs/tokio
28
29[Website](https://tokio.rs) |
30[Guides](https://tokio.rs/docs/getting-started/hello-world/) |
31[API Docs](https://docs.rs/tokio/0.1.22/tokio) |
32[Chat](https://gitter.im/tokio-rs/tokio)
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.1.22/tokio/net/index.html
49[reactor]: https://docs.rs/tokio/0.1.22/tokio/reactor/index.html
50[scheduler]: https://docs.rs/tokio/0.1.22/tokio/runtime/index.html
51
52## Example
53
54A basic TCP echo server with Tokio:
55
56```rust
57extern crate tokio;
58
59use tokio::prelude::*;
60use tokio::io::copy;
61use tokio::net::TcpListener;
62
63fn main() {
64 // Bind the server's socket.
65 let addr = "127.0.0.1:12345".parse().unwrap();
66 let listener = TcpListener::bind(&addr)
67 .expect("unable to bind TCP listener");
68
69 // Pull out a stream of sockets for incoming connections
70 let server = listener.incoming()
71 .map_err(|e| eprintln!("accept failed = {:?}", e))
72 .for_each(|sock| {
73 // Split up the reading and writing parts of the
74 // socket.
75 let (reader, writer) = sock.split();
76
77 // A future that echos the data and returns how
78 // many bytes were copied...
79 let bytes_copied = copy(reader, writer);
80
81 // ... after which we'll print what happened.
82 let handle_conn = bytes_copied.map(|amt| {
83 println!("wrote {:?} bytes", amt)
84 }).map_err(|err| {
85 eprintln!("IO error {:?}", err)
86 });
87
88 // Spawn the future as a concurrent task.
89 tokio::spawn(handle_conn)
90 });
91
92 // Start the Tokio runtime
93 tokio::run(server);
94}
95```
96
97More examples can be found [here](examples).
98
99## Getting Help
100
101First, see if the answer to your question can be found in the [Guides] or the
102[API documentation]. If the answer is not there, there is an active community in
103the [Tokio Gitter channel][chat]. We would be happy to try to answer your
104question. Last, if that doesn't work, try opening an [issue] with the question.
105
106[chat]: https://gitter.im/tokio-rs/tokio
107[issue]: https://github.com/tokio-rs/tokio/issues/new
108
109## Supported Rust Versions
110
111Tokio is built against the latest stable, nightly, and beta Rust releases. The
112minimum version supported is the stable release from three months before the
113current stable release version. For example, if the latest stable Rust is 1.29,
114the minimum version supported is 1.26. The current Tokio version is not
115guaranteed to build on Rust versions earlier than the minimum supported version.
116
117## License
118
119This project is licensed under the [MIT license](LICENSE).
120
121### Contribution
122
123Unless you explicitly state otherwise, any contribution intentionally submitted
124for inclusion in Tokio by you, shall be licensed as MIT, without any additional
125terms or conditions.
126
