# Tokio A runtime for writing reliable, asynchronous, and slim applications with the Rust programming language. It is: * **Fast**: Tokio's zero-cost abstractions give you bare-metal performance. * **Reliable**: Tokio leverages Rust's ownership, type system, and concurrency model to reduce bugs and ensure thread safety. * **Scalable**: Tokio has a minimal footprint, and handles backpressure and cancellation naturally. [![Crates.io][crates-badge]][crates-url] [![MIT licensed][mit-badge]][mit-url] [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] [crates-badge]: https://img.shields.io/crates/v/tokio.svg [crates-url]: https://crates.io/crates/tokio [mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg [mit-url]: https://github.com/tokio-rs/tokio/blob/master/LICENSE [actions-badge]: https://github.com/tokio-rs/tokio/workflows/CI/badge.svg [actions-url]: https://github.com/tokio-rs/tokio/actions?query=workflow%3ACI+branch%3Amaster [discord-badge]: https://img.shields.io/discord/500028886025895936.svg?logo=discord&style=flat-square [discord-url]: https://discord.gg/tokio [Website](https://tokio.rs) | [Guides](https://tokio.rs/tokio/tutorial) | [API Docs](https://docs.rs/tokio/latest/tokio) | [Chat](https://discord.gg/tokio) ## Overview Tokio is an event-driven, non-blocking I/O platform for writing asynchronous applications with the Rust programming language. At a high level, it provides a few major components: * A multithreaded, work-stealing based task [scheduler]. * A reactor backed by the operating system's event queue (epoll, kqueue, IOCP, etc...). * Asynchronous [TCP and UDP][net] sockets. These components provide the runtime components necessary for building an asynchronous application. [net]: https://docs.rs/tokio/latest/tokio/net/index.html [scheduler]: https://docs.rs/tokio/latest/tokio/runtime/index.html ## Example A basic TCP echo server with Tokio. Make sure you activated the full features of the tokio crate on Cargo.toml: ```toml [dependencies] tokio = { version = "1.24.1", features = ["full"] } ``` Then, on your main.rs: ```rust,no_run use tokio::net::TcpListener; use tokio::io::{AsyncReadExt, AsyncWriteExt}; #[tokio::main] async fn main() -> Result<(), Box> { let listener = TcpListener::bind("127.0.0.1:8080").await?; loop { let (mut socket, _) = listener.accept().await?; tokio::spawn(async move { let mut buf = [0; 1024]; // In a loop, read data from the socket and write the data back. loop { let n = match socket.read(&mut buf).await { // socket closed Ok(n) if n == 0 => return, Ok(n) => n, Err(e) => { eprintln!("failed to read from socket; err = {:?}", e); return; } }; // Write the data back if let Err(e) = socket.write_all(&buf[0..n]).await { eprintln!("failed to write to socket; err = {:?}", e); return; } } }); } } ``` More examples can be found [here][examples]. For a larger "real world" example, see the [mini-redis] repository. [examples]: https://github.com/tokio-rs/tokio/tree/master/examples [mini-redis]: https://github.com/tokio-rs/mini-redis/ To see a list of the available features flags that can be enabled, check our [docs][feature-flag-docs]. ## Getting Help First, see if the answer to your question can be found in the [Guides] or the [API documentation]. If the answer is not there, there is an active community in the [Tokio Discord server][chat]. We would be happy to try to answer your question. You can also ask your question on [the discussions page][discussions]. [Guides]: https://tokio.rs/tokio/tutorial [API documentation]: https://docs.rs/tokio/latest/tokio [chat]: https://discord.gg/tokio [discussions]: https://github.com/tokio-rs/tokio/discussions [feature-flag-docs]: https://docs.rs/tokio/#feature-flags ## Contributing :balloon: Thanks for your help improving the project! We are so happy to have you! We have a [contributing guide][guide] to help you get involved in the Tokio project. [guide]: https://github.com/tokio-rs/tokio/blob/master/CONTRIBUTING.md ## Related Projects In addition to the crates in this repository, the Tokio project also maintains several other libraries, including: * [`hyper`]: A fast and correct HTTP/1.1 and HTTP/2 implementation for Rust. * [`tonic`]: A gRPC over HTTP/2 implementation focused on high performance, interoperability, and flexibility. * [`warp`]: A super-easy, composable, web server framework for warp speeds. * [`tower`]: A library of modular and reusable components for building robust networking clients and servers. * [`tracing`] (formerly `tokio-trace`): A framework for application-level tracing and async-aware diagnostics. * [`rdbc`]: A Rust database connectivity library for MySQL, Postgres and SQLite. * [`mio`]: A low-level, cross-platform abstraction over OS I/O APIs that powers `tokio`. * [`bytes`]: Utilities for working with bytes, including efficient byte buffers. * [`loom`]: A testing tool for concurrent Rust code [`warp`]: https://github.com/seanmonstar/warp [`hyper`]: https://github.com/hyperium/hyper [`tonic`]: https://github.com/hyperium/tonic [`tower`]: https://github.com/tower-rs/tower [`loom`]: https://github.com/tokio-rs/loom [`rdbc`]: https://github.com/tokio-rs/rdbc [`tracing`]: https://github.com/tokio-rs/tracing [`mio`]: https://github.com/tokio-rs/mio [`bytes`]: https://github.com/tokio-rs/bytes ## Changelog The Tokio repository contains multiple crates. Each crate has its own changelog. * `tokio` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio/CHANGELOG.md) * `tokio-util` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-util/CHANGELOG.md) * `tokio-stream` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-stream/CHANGELOG.md) * `tokio-macros` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-macros/CHANGELOG.md) * `tokio-test` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-test/CHANGELOG.md) ## Supported Rust Versions Tokio will keep a rolling MSRV (minimum supported rust version) policy of **at least** 6 months. When increasing the MSRV, the new Rust version must have been released at least six months ago. The current MSRV is 1.49.0. ## Release schedule Tokio doesn't follow a fixed release schedule, but we typically make one to two new minor releases each month. We make patch releases for bugfixes as necessary. ## Bug patching policy For the purposes of making patch releases with bugfixes, we have designated certain minor releases as LTS (long term support) releases. Whenever a bug warrants a patch release with a fix for the bug, it will be backported and released as a new patch release for each LTS minor version. Our current LTS releases are: * `1.18.x` - LTS release until June 2023 * `1.20.x` - LTS release until September 2023. Each LTS release will continue to receive backported fixes for at least a year. If you wish to use a fixed minor release in your project, we recommend that you use an LTS release. To use a fixed minor version, you can specify the version with a tilde. For example, to specify that you wish to use the newest `1.18.x` patch release, you can use the following dependency specification: ```text tokio = { version = "~1.18", features = [...] } ``` ## License This project is licensed under the [MIT license]. [MIT license]: https://github.com/tokio-rs/tokio/blob/master/LICENSE ### Contribution Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tokio by you, shall be licensed as MIT, without any additional terms or conditions.