Rust Async

Future::poll Contract

The Future::poll contract has three invariants:

1. Return Pending only after registering a waker. If you return Poll::Pending without calling cx.waker().wake_by_ref() or storing the waker for later notification, the executor has no way to know when to re-poll. The future is never woken and appears hung.

2. Never return Pending without waker registration. This causes a busy-loop: the executor keeps polling, gets Pending, and has no wake signal, so it either spins or gives up.

3. Never poll after Ready. Once a future returns Poll::Ready(value), polling again is a logic error. The future may panic or return garbage. Use FusedFuture or .fuse() if you need safe repeated polling.

Incorrect (Pending without waker registration):

impl Future for MyFuture {
    type Output = i32;
    fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Self::Output> {
        if self.ready {
            Poll::Ready(42)
        } else {
            // BUG: no waker registered — this future will never wake
            Poll::Pending
        }
    }
}

Correct (waker stored for later notification):

impl Future for MyFuture {
    type Output = i32;
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        if self.ready {
            Poll::Ready(42)
        } else {
            // Store waker so the background task can call wake() when ready
            self.get_mut().waker = Some(cx.waker().clone());
            Poll::Pending
        }
    }
}

Async State Machines

Every async fn compiles to an anonymous enum state machine. Each .await is a yield point that creates a new variant. All variables captured across .await points are stored in the future struct.

• Large captured variables = large future. A future holding a [u8; 65536] across an .await is 64KB+ per instance.
• Use std::mem::size_of_val(&future) to profile future sizes.
• Box large futures at creation: Box::pin(large_async_fn()).
• Minimize variables held across .await — drop or move them before yielding.
• Deeply nested async call chains multiply future sizes (each level wraps the inner).

Incorrect (large buffer captured across .await):

async fn process() {
    let buffer = [0u8; 65536]; // 64KB lives in the future struct
    let result = network_call().await; // buffer held across .await
    use_buffer(&buffer, result);
}

// Spawning 1000 tasks = 64MB just for buffers
for _ in 0..1000 {
    tokio::spawn(process());
}

Correct (scope buffer before .await or box the future):

async fn process() {
    let result = network_call().await;
    let buffer = [0u8; 65536]; // Allocated AFTER .await, not captured across yield
    use_buffer(&buffer, result);
}

// Or box the future to move it to heap with a single pointer on the stack
async fn process_boxed() {
    let buffer = [0u8; 65536];
    let fut = Box::pin(async move {
        let result = network_call().await;
        use_buffer(&buffer, result);
    });
    fut.await;
}

Tokio Runtime

Tokio runtime configuration, spawn_blocking, and task lifecycle management.

Task Cancellation Lifecycle

Dropping a JoinHandle detaches the task — it does NOT cancel it. The task continues running in the background, potentially leaking resources, holding connections, or writing to closed channels.

Cancellation strategies:

• AbortHandle::abort() — forcefully cancels the task at the next .await point. The JoinHandle returns JoinError::is_cancelled.
• CancellationToken — cooperative cancellation. The task checks token.is_cancelled() or token.cancelled().await at strategic points.
• Dropping a future inside select! — cancels by dropping at the .await yield point. Only safe if the future is cancellation-safe.

Incorrect (assuming drop cancels):

async fn leak_example() {
    let handle = tokio::spawn(async {
        // This task runs FOREVER even after handle is dropped
        loop {
            do_work().await;
            tokio::time::sleep(Duration::from_secs(1)).await;
        }
    });
    drop(handle); // BUG: task is detached, not cancelled — runs until process exits
}

Correct (cooperative cancellation with CancellationToken):

use tokio_util::sync::CancellationToken;

async fn managed_example() {
    let token = CancellationToken::new();
    let task_token = token.clone();

    let handle = tokio::spawn(async move {
        loop {
            tokio::select! {
                _ = task_token.cancelled() => {
                    // Clean up resources
                    break;
                }
                _ = do_work() => {}
            }
        }
    });

    // Later: signal cancellation
    token.cancel();
    handle.await.unwrap(); // Task exits cleanly
}

Select & Join

Composing futures with select!, join!, try_join!, and collection types.

select! Semantics

tokio::select! polls multiple futures and completes when the FIRST one resolves. All other branches are dropped immediately, cancelling them mid-execution.

Key rules:

• Losing branches are dropped (cancelled) at their last .await point. Any partial progress is lost unless the future is cancellation-safe.
• Use biased for deterministic priority: without it, branches are polled in random order. With biased, the first matching branch always wins.
• Use .fuse() on completed futures to prevent re-polling a finished future (returns Pending forever after Ready).
• In loops, pin futures outside the loop. Otherwise they are recreated and restarted on every iteration.

Incorrect (future recreated each loop iteration):

loop {
    tokio::select! {
        // BUG: timeout is recreated every iteration — never fires
        _ = tokio::time::sleep(Duration::from_secs(30)) => {
            println!("timeout");
            break;
        }
        msg = rx.recv() => {
            process(msg);
        }
    }
}

Correct (future pinned outside loop):

let timeout = tokio::time::sleep(Duration::from_secs(30));