Rust Async Practice: async/await, Futures & Tokio Basics

Most async Rust code uses Tokio as its runtime. Add it to your Cargo.toml before anything else:

[dependencies]
tokio = { version = "1", features = ["macros", "rt-multi-thread", "time"] }

macros enables #[tokio::main] and #[tokio::test]. rt-multi-thread gives you the multi-threaded scheduler. Add "full" instead if you want everything.

The most common first error. You wrote .await in a regular fn:

// WRONG: .await outside async context
// fn main() {
//     let data = fetch_data().await;  // error[E0728]
// }

// RIGHT: Use #[tokio::main] to make main async
#[tokio::main]
async fn main() {
    let data = fetch_data().await;
    println!("{data}");
}

async fn fetch_data() -> String {
    "data".to_string()
}

If you cannot make the function async (e.g., inside a trait impl), build a runtime manually:

fn main() {
    let rt = tokio::runtime::Runtime::new().unwrap();
    rt.block_on(async {
        let data = fetch_data().await;
        println!("{data}");
    });
}

tokio::spawn requires Send + 'static because the runtime can move tasks between threads. Three common causes:

// WRONG: Rc is not Send
// use std::rc::Rc;
// let shared = Rc::new("data".to_string());
// tokio::spawn(async move {
//     println!("{shared}");  // error[E0277]
// });

// RIGHT: Use Arc instead
use std::sync::Arc;
let shared = Arc::new("data".to_string());
tokio::spawn(async move {
    println!("{shared}");
});

Other causes: holding a &reference across .await (not 'static), or capturing a non-Send type like Cell or MutexGuard (from std) across a yield point. The concurrency guide explains Send and Sync traits in detail.

async fn fetch() -> String {
    "data".to_string()
}

// WRONG: Calling async fn without .await
// let result = fetch(); // result is a Future, not a String!
// println!("{result}"); // ERROR: Future doesn't implement Display

// RIGHT: Await the future
#[tokio::main]
async fn main() {
    let result = fetch().await; // now it's a String
    println!("{result}");
}

async fn desugars to a regular function that returns an impl Future. The future does nothing until an executor polls it. .await is the common way to drive that polling.

This is different from JavaScript promises, which start executing immediately. In Rust, fetch() without .await just constructs the future — no network call happens, no work runs.

Key distinction: join! runs multiple futures concurrently within a single task. spawn creates a new task that can be scheduled across threads, which is why it requires Send.

// join! — concurrent, same task, no Send needed
let (a, b) = tokio::join!(fetch_users(), fetch_posts());

// spawn — background task, must be Send + 'static
let handle = tokio::spawn(async { process_data().await });
let result = handle.await.unwrap();

// select! — race futures, cancel the loser
tokio::select! {
    val = fetch_primary() => println!("primary: {val}"),
    _ = tokio::time::sleep(Duration::from_secs(5)) => println!("timeout"),
}

Calling blocking I/O inside an async task starves the executor — other tasks on that thread cannot progress:

// WRONG: Blocking I/O starves the async executor
// async fn read_config() -> String {
//     std::fs::read_to_string("config.toml").unwrap()  // blocks!
// }

// RIGHT: Use tokio::fs for async file I/O
async fn read_config() -> String {
    tokio::fs::read_to_string("config.toml").await.unwrap()
}

// Or for CPU-heavy / non-async-compatible work:
let result = tokio::task::spawn_blocking(|| {
    expensive_computation()
}).await.unwrap();

Rule of thumb: if a function doesn't return a Future and takes more than a few microseconds, wrap it in spawn_blocking. Error propagation with ? works identically in async functions -- see error handling for the full pattern.

A lock guard held across an .await point keeps the lock held while the task is suspended, blocking other tasks:

// WRONG: MutexGuard held across .await
// async fn update(mutex: &tokio::sync::Mutex<Vec<String>>) {
//     let mut guard = mutex.lock().await;
//     let data = fetch_data().await;  // guard still held!
//     guard.push(data);
// }

// RIGHT: Await first, then lock
async fn update(mutex: &tokio::sync::Mutex<Vec<String>>) {
    let data = fetch_data().await;      // await first
    let mut guard = mutex.lock().await;  // then lock
    guard.push(data);                    // quick update, guard drops
}

If you must hold a lock across .await, use tokio::sync::Mutex (not std::sync::Mutex). But prefer restructuring to minimize lock duration. Move closures play a key role in async tasks -- the closures guide covers capture modes and the move keyword that tokio::spawn requires.

• The Rust Async Book — official guide to async/await
• Tokio Tutorial — hands-on Tokio introduction
• Tokio: Spawning — why spawn requires Send + 'static
• How Async Works: Polling and Wakers — the machinery under the hood