tokio README

The project's README from github.com/tokio-rs/tokio. As one markdown file: README.md.

Tokio

A runtime for writing reliable, asynchronous, and slim applications with the Rust programming language. It is:

Crates.io MIT licensed Build Status Discord chat

Website | Guides | API Docs | Chat

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:

These components provide the runtime components necessary for building an asynchronous application.

Example

A basic TCP echo server with Tokio.

Make sure you enable the full features of the tokio crate on Cargo.toml:

[dependencies]
tokio = { version = "1.53.1", features = ["full"] }

Then, on your main.rs:

use tokio::net::TcpListener;
use tokio::io::{AsyncReadExt, AsyncWriteExt};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    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(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. For a larger "real world" example, see the mini-redis repository.

To see a list of the available feature flags that can be enabled, check our 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. We would be happy to try to answer your question. You can also ask your question on the discussions page.

Contributing

:balloon: Thanks for your help improving the project! We are so happy to have you! We have a contributing guide to help you get involved in the Tokio project.

In addition to the crates in this repository, the Tokio project also maintains several other libraries, including:

Changelog

The Tokio repository contains multiple crates. Each crate has its own changelog.

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.71.

Note that the MSRV is not increased automatically, and only as part of a minor release. The MSRV history for past minor releases can be found below:

Note that although we try to avoid the situation where a dependency transitively increases the MSRV of Tokio, we do not guarantee that this does not happen. However, every minor release will have some set of versions of dependencies that works with the MSRV of that minor release.

Release schedule

Tokio doesn't follow a fixed release schedule, but we typically make one minor release 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:

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.47.x patch release, you can use the following dependency specification:

tokio = { version = "~1.47", features = [...] }

Previous LTS releases

License

This project is licensed under the MIT 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.

tokio (tokio-rs/tokio)

Searching Database…

33.4K ·GitHub
Tokio
What is this?Tokio is a runtime for writing reliable, asynchronous applications with Rust: it supplies the scheduling, non-blocking I/O, networking and timers that async Rust programs need.
So is it a library I pull into my Rust project, or a standalone program?A library, not an app: your project depends on the tokio crate (the repo also ships tokio-util, tokio-stream, tokio-macros and tokio-test), and your code runs on Tokio's scheduler.
How do I add it to a project?Add the tokio crate to your Cargo.toml — the README example enables the 'full' feature set — then write async code in main.rs; a TCP echo server example shows the basic shape.
Do I need a specific Rust version to use it?Yes, a reasonably current toolchain: the current minimum supported Rust version (MSRV) is 1.71, and bumps only land in minor releases, at least six months after that Rust version shipped.
Does it work the same on Linux, macOS and Windows?Yes — the README names the native OS event queues it builds on: epoll (Linux), kqueue (macOS/BSD) and IOCP (Windows), so all three major desktop and server platforms are covered.
What does Tokio give me under the hood?Three major components: a multithreaded, work-stealing task scheduler; a reactor backed by the OS event queue; and asynchronous TCP and UDP sockets — together the runtime pieces an async application needs.
Where can I see a bigger real-world example than the echo server?The repo has more examples, and the team points to mini-redis — a larger 'real world' project built with Tokio.
What other libraries does the Tokio project maintain?Companion crates: axum and warp (web frameworks), hyper (HTTP/1.1 and HTTP/2), tonic (gRPC over HTTP/2), tower (client/server components), tracing (async-aware diagnostics), mio (low-level OS I/O), bytes (buffers) and loom (concurrency testing).
What are similar projects?libuv, compio, conc, muduo, libevent, disruptor, sidekiq, taskflow
Which topics is it in?asynchronous, udp, multithreading, scalability, runtime, concurrency, systems-programming, async, high-performance, developers, backend, networking
Creator
tokio-rs
Size
17.6 MB
Stars
33.4K
Updated
CommitOct 16Releasetokio-1.53.3Oct 13
Age
10y
Commits · 90 Days