Async Programming

🚀 Rust Async Programming: The Restaurant Kitchen Story

Imagine you’re running a busy restaurant kitchen. You have ONE chef (your CPU), but many orders coming in. How do you serve everyone without making them wait forever?

🍳 The Kitchen Analogy

Traditional cooking (blocking): Chef takes order → Cooks everything → Waits for pasta to boil → Stares at it → Serves → Next order.

Async cooking (non-blocking): Chef takes order → Puts pasta on → While it boils, starts grilling steak → Checks pasta → Plates steak → Drains pasta → Serves BOTH faster!

This is async programming in Rust. One worker doing multiple tasks by not waiting around doing nothing.

📚 What You’ll Learn

1. async keyword - Marking a task as “can be paused”
2. await keyword - Pausing until something is ready
3. Futures - Promises of work to be done
4. Async runtimes - The manager who runs everything
5. Pin and Unpin - Keeping things in place

🏷️ The async Keyword

What Is It?

The async keyword is like putting a “pausable” sticker on a task.

When you write async fn, you’re saying:

“This function might need to wait for something. Let other work happen while it waits!”

Simple Example

// Regular function - runs to completion
fn make_toast() -> String {
    "Toast ready!".to_string()
}

// Async function - can pause and resume
async fn boil_water() -> String {
    // Can pause here while water heats
    "Water boiled!".to_string()
}

The Magic Inside

When you mark a function async, Rust transforms it into something special:

// What you write:
async fn hello() -> String {
    "Hello!".to_string()
}

// What Rust sees:
fn hello() -> impl Future<Output = String> {
    // Returns a Future, not the String!
}

Key insight: An async function doesn’t run immediately. It returns a Future - a recipe that says “here’s how to get the result when you’re ready.”

⏸️ The await Keyword

What Is It?

await is like saying “I’ll wait here, but others can work.”

It’s the pause button that lets other tasks run while you wait.

The Restaurant Example

async fn make_breakfast() {
    let toast = toast_bread().await;  // Pause, let others work
    let eggs = fry_eggs().await;      // Pause again
    println!("Breakfast: {} and {}", toast, eggs);
}

async fn toast_bread() -> String {
    // Simulates waiting for toast
    "Golden toast".to_string()
}

async fn fry_eggs() -> String {
    "Sunny eggs".to_string()
}

Rules of await

1. Only works inside async functions
2. Pauses THIS task, not the whole program
3. Returns the actual value (unwraps the Future)

// ❌ Wrong - can't await in regular function
fn wrong() {
    let result = some_async_fn().await; // Error!
}

// ✅ Right - await inside async function
async fn right() {
    let result = some_async_fn().await; // Works!
}

Visual Flow

graph TD
    A["Start make_breakfast"] --> B["Call toast_bread"]
    B --> C["await - Pause here"]
    C --> D["Other tasks can run!"]
    D --> E["Toast ready - Resume"]
    E --> F["Call fry_eggs"]
    F --> G["await - Pause again"]
    G --> H["Other tasks run"]
    H --> I["Eggs ready - Resume"]
    I --> J["Print breakfast"]

📦 Futures: The Promise Box

What Is a Future?

A Future is like a gift box with a promise note:

“Your present isn’t ready yet, but check back later!”

It represents a value that will exist eventually.

The Future Trait

pub trait Future {
    type Output;  // What you get when done

    fn poll(self: Pin<&mut Self>, cx: &mut Context)
        -> Poll<Self::Output>;
}

enum Poll<T> {
    Ready(T),      // "Here's your value!"
    Pending,       // "Not yet, ask again later"
}

How Futures Work

Imagine ordering pizza:

1. Order placed → Future created (pizza coming)
2. Check status → poll() called
3. Not ready → Returns Pending
4. Check again → poll() called again
5. Ready! → Returns Ready(pizza)

async fn order_pizza() -> Pizza {
    // This creates a Future
    let pizza_future = call_pizzeria();

    // await polls until Ready
    let pizza = pizza_future.await;

    pizza
}

Future State Machine

When you write async code, Rust creates a state machine:

graph TD
    A["Initial State"] -->|poll| B{Ready?}
    B -->|Pending| C["Save State"]
    C -->|Later poll| B
    B -->|Ready| D["Return Value"]

🎮 Async Runtimes: The Kitchen Manager

What Is a Runtime?

An async runtime is like the restaurant manager who:

• Schedules which chef works on what
• Wakes up tasks when they’re ready
• Manages the whole kitchen efficiently

Rust doesn’t include a runtime by default! You need to pick one.

Popular Runtimes

1. Tokio (Most Popular)

// Add to Cargo.toml:
// tokio = { version = "1", features = ["full"] }

#[tokio::main]
async fn main() {
    println!("Hello from Tokio!");

    let result = fetch_data().await;
    println!("{}", result);
}

async fn fetch_data() -> String {
    "Data fetched!".to_string()
}

2. async-std

// Add to Cargo.toml:
// async-std = { version = "1", features = ["attributes"] }

#[async_std::main]
async fn main() {
    println!("Hello from async-std!");
}

3. smol (Lightweight)

// Minimal runtime for simple cases
fn main() {
    smol::block_on(async {
        println!("Hello from smol!");
    });
}

What Runtimes Do

graph TD
    A["Your Async Code"] --> B["Runtime"]
    B --> C["Task Scheduler"]
    B --> D["I/O Handler"]
    B --> E["Timer Manager"]
    C --> F["Runs Tasks Efficiently"]
    D --> G["Network/File Operations"]
    E --> H["Sleep/Timeout"]

Choosing a Runtime

📌 Pin and Unpin: Stay Put!

The Moving Problem

In Rust, values can move in memory. But some async code references itself (self-referential). If it moves, those references break!

What Is Pin?

Pin is a wrapper that says:

“This value CANNOT move to a different memory location!”

Think of it like pinning a note to a corkboard - it stays exactly where you put it.

Simple Example

use std::pin::Pin;

// Pin wraps a pointer type
let mut data = String::from("Hello");
let pinned: Pin<&mut String> = Pin::new(&mut data);

// pinned data won't move in memory

Why Futures Need Pin

Async functions can create self-referential structs:

async fn example() {
    let data = vec![1, 2, 3];
    let reference = &data[0];  // Points to data

    some_async_work().await;   // Pause here

    println!("{}", reference); // Still need reference!
}

During the await, this whole state (including data and reference) is stored. If it moves, reference would point to invalid memory!

Pin to the Rescue

// The Future trait requires Pin
fn poll(self: Pin<&mut Self>, cx: &mut Context)
    -> Poll<Self::Output>;

By requiring Pin<&mut Self>, Rust ensures the Future won’t move while being polled.

What Is Unpin?

Unpin is a marker trait meaning:

“This type is safe to move even when pinned.”

Most types are Unpin automatically. Only self-referential types aren’t.

// These are Unpin (safe to move):
// - i32, String, Vec<T>
// - Most regular types

// These are NOT Unpin:
// - Async function futures
// - Self-referential structs

Working with Pin

use std::pin::pin;

async fn my_async_fn() {
    // pin! macro for stack pinning
    let future = pin!(some_async_work());

    // Now safe to poll
}

Pin Flow

graph TD
    A["Create Future"] --> B{Self-referential?}
    B -->|No| C["Unpin - Can move freely"]
    B -->|Yes| D["Must be Pinned"]
    D --> E["Pin ensures no movement"]
    E --> F["Safe to poll"]
    C --> F

🎯 Putting It All Together

Here’s a complete example showing everything working together:

use tokio::time::{sleep, Duration};

#[tokio::main]
async fn main() {
    println!("🍳 Starting breakfast!");

    // Run tasks concurrently
    let (toast, coffee) = tokio::join!(
        make_toast(),
        brew_coffee()
    );

    println!("Breakfast ready!");
    println!("{} + {}", toast, coffee);
}

async fn make_toast() -> String {
    println!("Toasting bread...");
    sleep(Duration::from_secs(2)).await;
    "🍞 Golden toast".to_string()
}

async fn brew_coffee() -> String {
    println!("Brewing coffee...");
    sleep(Duration::from_secs(3)).await;
    "☕ Hot coffee".to_string()
}

What happens:

1. #[tokio::main] sets up the runtime
2. async fn marks functions as pausable
3. await pauses while sleeping
4. tokio::join! runs both concurrently
5. Total time: ~3 seconds (not 5!)

🧠 Key Takeaways

🚀 You Did It!

You now understand Rust’s async programming model:

✅ async creates pausable functions ✅ await pauses without blocking ✅ Futures are promises of values ✅ Runtimes manage everything ✅ Pin keeps things in place

The restaurant is running smoothly. Orders are flying out. Customers are happy. You’re the async chef master! 🎉