rust-async-internals

Rust Async Internals

Purpose

Guide agents through Rust async/await internals: the Future trait and poll loop, Pin/Unpin for self-referential types, tokio's task model, diagnosing async stack traces with tokio-console, finding waker leaks, and common select!/join! pitfalls.

Triggers

• "How does async/await actually work in Rust?"
• "What is Pin and Unpin in async Rust?"
• "My async code is slow — how do I profile it?"
• "How do I use tokio-console to debug async tasks?"
• "I have a blocking call in async — what do I do?"
• "How does select! work and what are the pitfalls?"

Workflow

1. The Future trait — poll model

// std::future::Future (simplified)
pub trait Future {
    type Output;
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}

pub enum Poll<T> {
    Ready(T),    // computation done, T is the result
    Pending,     // not ready yet, waker registered, will be polled again
}

Execution model:

1. Calling .await calls poll() on the future
2. If Pending: current task registers its waker and yields to the runtime
3. When the waker is triggered (I/O ready, timer fired), the runtime re-polls
4. If Ready(val): the .await expression evaluates to val

2. Implementing a simple Future

use std::{
    future::Future,
    pin::Pin,
    task::{Context, Poll},
    time::{Duration, Instant},
};

struct Delay { deadline: Instant }

impl Delay {
    fn new(dur: Duration) -> Self {
        Delay { deadline: Instant::now() + dur }
    }
}

impl Future for Delay {
    type Output = ();

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
        if Instant::now() >= self.deadline {
            Poll::Ready(())
        } else {
            // Register the waker — runtime calls waker.wake() to re-poll
            // In production: register with I/O reactor or timer wheel
            let waker = cx.waker().clone();
            let deadline = self.deadline;
            std::thread::spawn(move || {
                let now = Instant::now();
                if deadline > now {
                    std::thread::sleep(deadline - now);
                }
                waker.wake();  // notify runtime to re-poll
            });
            Poll::Pending
        }
    }
}

// Usage
async fn main() {
    Delay::new(Duration::from_secs(1)).await;
    println!("Done");
}