Rust Future — poll, state machines, Tokio runtime, and Pin

Contents

  1. 1. State machine
  2. 2. Scheduling
  3. 3. Runtime
  4. 4. async
  5. 5. pin

Rust’s Future is the core abstraction for async programming. What follows is how async/await, polling, and the runtime stack fit together.

async gives you cheap, suspendable functions; they only run when you .await them and the executor polls them.

Compared with one OS thread per bit of concurrency, async tasks are lighter—you can host many concurrent operations without paying for a thread each time.

A minimal async entry point:

1
2
3
4
5
6
7
8
async fn async_fn() {
// handle async logic
}

#[tokio::main]
async fn main() {
async_fn().await
}

State machine

async is mostly compiler sugar: it implements Future for you and stores progress in a state machine.

1
2
3
4
5
6
7
trait Future {
type Output;
fn poll(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
) -> Poll<Self::Output>;
}

poll asks whether the work is done. A task is either Pending (yield control until something can make progress) or Ready (finished). The executor keeps polling until Ready.

We can see that flow by implementing a small Delay future:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use std::time::{Duration, Instant};

struct Delay {
when: Instant,
}

impl Future for Delay {
type Output = &'static str;

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<&'static str> {
if Instant::now() >= self.when {
Poll::Ready("done")
} else {
// Not ready yet — schedule another wake
cx.waker().wake_by_ref();
Poll::Pending
}
}
}

#[tokio::main]
async fn main() {
let when = Instant::now() + Duration::from_millis(3);
let future = Delay { when };

let out = future.await;
assert_eq!(out, "done");
}

Each poll checks the deadline. If time has passed, return Ready; otherwise schedule another wake and return Pending.

We have a state machine—who drives it?

Scheduling

Rust needs a runtime to schedule async tasks. The runtime polls futures and advances work.

When a future returns Pending, the task yields and arranges to be woken later.

Typical path when work completes on the first poll:

graph TD
    executor --> task
    task -- poll --> future
    future -- ready --> task

When the future is Pending, something must schedule the next wake. The wake may run on a different task than the one that polled last time. The waker travels through Context on every poll:

graph TD
    executor --> task
    executor --> waker
    executor -.-> task
    task -- poll with context (waker) --> future
    future -- update --> waker
    future -- pending --> task
    waker -- wake --> executor

Runtime

Scheduling lives in a runtime. Rust’s standard library does not ship one; most projects use Tokio.

#[tokio::main] expands to a multi-thread runtime that blocks until the async main finishes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
#[tokio::main]
async fn main() {
println!("hello");
}

// tranform to
fn main() {
tokio::runtime::Builder::new_multi_thread()
.enable_all()
.build()
.unwrap()
.block_on(async {
println!("Hello world");
})
}

Single-thread flavor:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
#[tokio::main(flavor = "current_thread")]
async fn main() {
println!("Hello world");
}
// tranform to
fn main() {
tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.unwrap()
.block_on(async {
println!("Hello world");
})
}

async

You rarely implement Future by hand. async fn is enough—the Delay example collapses to something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
use std::sync::Arc;
use std::thread;
use std::time::{Duration, Instant};
use tokio::sync::Notify;

async fn delay(dur: Duration) {
let when = Instant::now() + dur;
let notify = Arc::new(Notify::new());
let notify_clone = notify.clone();

thread::spawn(move || {
let now = Instant::now();

if now < when {
thread::sleep(when - now);
}

notify_clone.notify_one();
});

notify.notified().await;
}

#[tokio::main]
async fn main() {
delay(Duration::from_secs(1)).await;
}

pin

Remember Pin<&mut Self> on poll—why pin a future?

1
2
3
4
5
6
7
8
9
10
11
async fn my_async_fn() {
// async logic here
}

#[tokio::main]
async fn main() {
let mut future = my_async_fn();
(&mut future).await;
// error:
// within `impl Future<Output = ()>`, the trait `Unpin` is not implemented for `[async fn body@src/main.rs:1:24: 3:2]`
}

Polling through a stack reference fails unless the future is Unpin.

A Future from async is a state machine that moves while polled. If it held stack references, those addresses would go stale when the state machine moves—classic use-after-move.

Unpin marks types that are safe to move while referenced. Most ordinary types are Unpin. For !Unpin futures, pin them on the stack (pin!) or heap (Box::pin) so the address stays valid until completion:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
use tokio::pin;

async fn my_async_fn() {
// async logic here
}

#[tokio::main]
async fn main() {
let future = my_async_fn();
// option 1
pin!(future);
(&mut future).await;

// option 2
// let pinned_fut = Box::pin(future);
// pinned_fut.await;
}

That’s enough for one sitting. Next up: running several futures concurrently.

More on pinning: Pinning

Tokio’s runtime tour: Async in depth

Questions? Leave a comment below or email: newbvirgil@gmail.com