Let’s get started with our first Tokio app. Create a new project using Cargo and add the tokio dependency either to your Cargo.toml file or directly on the command line.

$ cargo add tokio --features full

Tokio comes with a ton of features, and for the scope of this guide, we just add all of them. In a real production app, you would switch features on and off as needed.

Hello Tokio #

This is what a Tokio “Hello, World!” app with some basic network I/O looks like:

use tokio::{
    io::{self, AsyncWriteExt},
    net::TcpListener,
};
#[tokio::main] // (1)
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("localhost:8001").await?; // (2)
    loop {
        let (mut socket, addr) = listener.accept().await?;
        println!("Listening to {}", addr);
        tokio::spawn(async move { // (3)
            socket.write_all("Hello World!\n\r".as_bytes()).await
        });
    }
}

The application creates a TCP Server and listens to port 8001. It waits for incoming connections, and when it got one, it will write “Hello, World” to the client.

It’s just a few lines of code, but there are already some new concepts going on. Let’s break them down piece by piece.

1. The #[tokio::main] attribute macro #

The first thing that you’ll notice is that we don’t work with a regular main function, but rather have an async main().

#[tokio::main]
async fn main() {
    println!("Hello, world!");
}

At the time of writing, Rust won’t recognize this and won’t support this entry point. The #[tokio::main] attribute macro makes this work. It creates a real main function and sets up a default Tokio runtime. If you expand the macro, it may look something like this:

fn main() {
    let mut rt = tokio::runtime::Runtime::new().unwrap();
    rt.block_on(async {
        println!("Hello, world!");
    });
}

In reality there a bit more details, but you get the gist. It creates a new, multi-threaded runtime and blocks with the Future from the async fn main() that you provided earlier.

Every async function or block creates code that implements the Future trait. The Tokio runtime can take this Future and execute it concurrently with other tasks. To kick off the process, it will execute the main entry point as “blocking”. This means that it will wait for the Future to complete before it exits the program. All other Futures and tasks that are spawned within this main entry point are then executed concurrently.

2. TCP Listeners #

Next, we create a TcpListener and bind it to localhost:8001.

let listener = TcpListener::bind("localhost:8001").await?;
loop {
    let (mut socket, addr) = listener.accept().await?;
    // ...
}

This code is equivalent to the sync version that you can find in the standard library of Rust. Tokio includes async versions of many standard library types, and try to keep the same API as the original. In the net feature, you will get abstractions for network applications, Tokio’s strength and main use case. It’s also possible to convert std::net::TcpListeners to tokio listeners. In the next line, we loop and accept listener connections.

3. Spawning tasks #

Spawning tasks is similar to spawning threads.

tokio::spawn(async move {
    socket.write_all("Hello World!\n\r".as_bytes()).await
});

Tokio’s spawn function takes everything that implements a proper Future. This can be async blocks or functions, or anything that implements the Future trait. In this example we spawn an async block with a move closure. Just like in Rust with threads, this move keywords transfers ownership of all variables into the closure.

Tasks are Tokio’s unit of execution. You should be able to spawn thousands, if not millions of tasks. tokio::spawn submits tasks to Tokio’s scheduler. The way Tokio works, it will pick a task that is ready to work with from a task queue, runs it on the worker thread until it hits an .await point, puts it back on the queue and continues once the Future is ready to continue.

Like thread::spawn, tokio::spawn returns a JoinHandle that can be .await-ed.

Trait bounds #

Tasks are are ‘static bound. They must not contain any references to data owned outside the task. Use move closures to transfer ownership to async blocks.

Tasks are Send bound. This allows Tokio to move tasks between threads. Tasks are Send when all data that is held across .await calls is Send.

Other spawning methods #

spawn_blocking runs the provided closure on a thread where blocking is acceptable. A closure that is run through this method runs on a dedicated thread pool for blocking tasks without holding up the main futures executor.

spawn_local spawns a !Send future on the local task set. The spawned future will be run on the same thread.

Exercise 1: Create an echo server #

With the knowledge from this chapter, try to create an echo server with Tokio. The server should listen on localhost:8001 and echo back any message it receives. Make sure that the server:

1. Accepts incoming connections
2. Reads incoming messages
3. Writes the message back to the client

As a stretch goal, try to handle multiple clients concurrently (Don’t worry if not, we take of that in the next chapter). Use telnet localhost 8001 to test your server (or use the demo client).

Solution #

This is the solution for the echo server exercise:

use tokio::{
    io::{self, AsyncBufReadExt, AsyncWriteExt, BufReader},
    net::TcpListener,
};
#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("localhost:8001").await?; // (1)
    loop {
        let (mut socket, addr) = listener.accept().await?; // (2)
        println!("New connection at {}", addr);
        tokio::spawn(async move { // (3)
            let (reader, mut writer) = socket.split(); // (4)
            let mut buf = String::new();
            let mut reader = BufReader::new(reader); // (5)
            // (6)
            while let Ok(_b_read) = reader.read_line(&mut buf).await {
                if buf.trim() == "quit" { // (7)
                    break;
                }
                writer.write_all(buf.as_bytes()).await.unwrap(); // (8)
                buf.clear();
            }
        });
    }
}

A quick rundown:

1. Just like in the “Tokio Hello World” example, we create a listener on port 8001.
2. We accept incoming connections in a loop.
3. For each connection, we spawn a new task. With this line, we are able to defer the work into a separate task. The main loop can continue to accept new connections. The move keyword makes sure that the task takes ownership of the socket.
4. We split the socket into a reader and a writer. We read incoming messages from the reader and write messages back to the writer. All over the same socket.
5. An empty string and a BufReader help us to read lines from the reader. The BufReader comes from tokio::io, has a similar interface to the standard library’s BufReader, but is async and can work with Tokio’s socket abstraction.
6. We read lines from the reader in a loop. This loop will continue until the client sends an empty message. read_line is available if you import the AsyncBufReadExt trait.
7. If the client sends the text “quit”, we break out of the loop.
8. We write the message back to the client. write_all is available if you import the AsyncWriteExt trait. We call unwrap at this point. Should this fail, the current thread panics. In Tokio, this means that the current worker thread panics. This does not influence the other worker threads. The Tokio runtime will also respawn a new worker thread if this panic happens. So even if we want to avoid unwraps and subsequent panics, for our little example in this context, it’s fine.

Tokio: Table of contents

1. Getting Started
2. Channels
3. Macros

Related Articles

• November 22, 2024 | Rust Unsafe for work
• November 20, 2024 | Rust, Tokio Tokio: Macros
• November 19, 2024 | Rust, Tokio Tokio: Channels