Promises vs Futures

19 min read

If you know JavaScript Promises, you already understand 80% of Rust’s async model — and the remaining 20% is exactly where most TypeScript/JavaScript developers get burned. This page is about that 20%: the single most important difference is that a JavaScript Promise is eager (it starts doing work the moment it is created), while a Rust Future is lazy (it does nothing at all until you .await it or hand it to a runtime).

Quick Overview

A Future is Rust’s equivalent of a JavaScript Promise: a value that represents an asynchronous computation that will produce a result later. The crucial difference is timing: a Promise begins executing the instant you create it, whereas a Future is an inert description of work that runs only when something polls it. On top of that, Rust ships with no built-in async runtime — there is no event loop hiding in the language, so you must bring your own executor (almost always Tokio).

Note: This page focuses on the concept — eager vs lazy, and the runtime requirement. The mechanics of async/await syntax live in async-await.md, and runtime setup lives in tokio-setup.md.

TypeScript/JavaScript Example

In JavaScript, calling an async function (or constructing a Promise) starts the work immediately. The await only controls when you wait for the result, not when the work begins.

1
// TypeScript / JavaScript (Node v22) — Promises are EAGER
2

3
function makeRequest(id: number): Promise<number> {
4
  console.log(`  -> running request ${id}`);
5
  return Promise.resolve(id * 10);
6
}
7

8
console.log("Before creating the promise");
9
const p = makeRequest(1); // the body runs RIGHT NOW, before the next line
10
console.log("After creating the promise");
11

12
const result = await p; // we only WAIT here; work already happened
13
console.log(`Got result: ${result}`);

Running this with Node v22 prints:

1
Before creating the promise
2
  -> running request 1
3
After creating the promise
4
Got result: 10

Notice the -> running request 1 line appears before After creating the promise. The work started at creation. The same is true for the Promise constructor itself: the executor callback runs synchronously the moment you write new Promise(...).

1
// The executor runs immediately, even with no .then/.await
2
console.log("before new Promise");
3
const eager = new Promise<number>((resolve) => {
4
  console.log("  executor running immediately");
5
  resolve(42);
6
});
7
console.log("after new Promise");

Output (Node v22):

1
before new Promise
2
  executor running immediately
3
after new Promise

Rust Equivalent

The same shape of code in Rust behaves differently: building the future runs none of its body. Only .await triggers execution.

1
// Rust — Futures are LAZY
2

3
async fn make_request(id: u32) -> u32 {
4
    println!("  -> running request {id}");
5
    id * 10
6
}
7

8
#[tokio::main]
9
async fn main() {
10
    println!("Before creating the future");
11
    let fut = make_request(1); // nothing printed yet — body has NOT run
12
    println!("After creating the future (nothing ran yet)");
13

14
    let result = fut.await; // NOW the body runs
15
    println!("Got result: {result}");
16
}

Real output (Rust 1.96.0, Tokio 1.x):

1
Before creating the future
2
After creating the future (nothing ran yet)
3
  -> running request 1
4
Got result: 10

Look at the order: -> running request 1 appears after After creating the future, the exact opposite of JavaScript. Creating fut produced an inert value; the body only ran at .await.

Note: #[tokio::main] is a macro that sets up a Tokio runtime and runs your async fn main on it. We use it here so the example is complete; it is covered in depth in tokio-setup.md. Without some runtime, there is nothing to drive the future at all.

Detailed Explanation

What `async fn` actually returns

When you write async fn make_request(id: u32) -> u32, Rust does not create a function that returns u32. It creates a function that returns an anonymous type implementing the Future trait — conceptually impl Future<Output = u32>. The function body is compiled into a state machine that knows how to make progress one step at a time.

You can see this by writing the future-returning function explicitly:

1
use std::future::Future;
2

3
fn build_task(n: u32) -> impl Future<Output = u32> {
4
    // The async block evaluates to a Future; the body runs only when awaited.
5
    async move {
6
        println!("  computing for {n}");
7
        n + 1
8
    }
9
}
10

11
#[tokio::main]
12
async fn main() {
13
    let task = build_task(10); // nothing computed yet
14
    println!("task built");
15
    let out = task.await;
16
    println!("out = {out}");
17
}

Output:

1
task built
2
  computing for 10
3
out = 11

build_task(10) returns a value. The println!(" computing for {n}") inside it does not run until task.await. An async fn is sugar for “a function whose body is an async block.”

Lazy means “polled to completion”

A Future is defined by one method, poll. The runtime calls poll; the future does a chunk of work and returns either Poll::Ready(value) (done) or Poll::Pending (not done yet, wake me later). Nothing happens until someone calls poll — and .await is the syntax that arranges for that to happen.

Here is a hand-written future so you can see poll directly:

1
use std::future::Future;
2
use std::pin::Pin;
3
use std::task::{Context, Poll};
4

5
// A future that is "ready" the first time it is polled.
6
struct ReadyValue(u32);
7

8
impl Future for ReadyValue {
9
    type Output = u32;
10

11
    fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Self::Output> {
12
        println!("  poll() called");
13
        Poll::Ready(self.0)
14
    }
15
}
16

17
#[tokio::main]
18
async fn main() {
19
    let fut = ReadyValue(99); // constructing it does NOT call poll()
20
    println!("future built, poll not called yet");
21
    let value = fut.await; // .await drives poll() for us
22
    println!("value = {value}");
23
}

Output:

1
future built, poll not called yet
2
  poll() called
3
value = 99

Constructing ReadyValue(99) does nothing. The poll() called line proves the body of a future only executes when an executor drives it.

Tip: You will almost never implement Future by hand. async/await generates the state machine and the poll implementation for you. This example exists purely to make “lazy” concrete.

The eager/lazy difference is visible in concurrency

Because JavaScript Promises are already running, Promise.all([a, b]) runs a and b concurrently for free — they both started when you created them. In Rust, two futures awaited one after another run sequentially, because the first does not even begin until you .await it. To get concurrency you must combine them with something like join!.

1
use std::time::Instant;
2
use tokio::time::{sleep, Duration};
3

4
async fn fetch(id: u32, ms: u64) -> u32 {
5
    sleep(Duration::from_millis(ms)).await;
6
    println!("  fetched {id}");
7
    id
8
}
9

10
#[tokio::main]
11
async fn main() {
12
    // Sequential: each .await waits for the previous to finish.
13
    let start = Instant::now();
14
    let a = fetch(1, 100).await;
15
    let b = fetch(2, 100).await;
16
    println!("sequential took ~{} ms (a={a}, b={b})", start.elapsed().as_millis());
17

18
    // Concurrent: join! polls both on the same task, interleaving them.
19
    let start = Instant::now();
20
    let (a, b) = tokio::join!(fetch(3, 100), fetch(4, 100));
21
    println!("join! took ~{} ms (a={a}, b={b})", start.elapsed().as_millis());
22
}

Real output:

1
  fetched 1
2
  fetched 2
3
sequential took ~204 ms (a=1, b=2)
4
  fetched 4
5
  fetched 3
6
join! took ~102 ms (a=3, b=4)

The sequential version takes ~200 ms (100 + 100); join! takes ~100 ms because both futures make progress together. In JavaScript, await a; await b would also take ~200 ms for the awaiting — but the underlying timers would already be counting down, so the mental model is different. The key Rust takeaway: awaiting in sequence is sequential, and there is no hidden concurrency.

There is no built-in executor

This is the second half of the story. JavaScript has a built-in event loop (in the browser, and libuv in Node). It is always there; you never “start” it. Rust deliberately ships no runtime in its standard library. The Future trait and async/await are in std, but the thing that drives futures — the executor — is a library you choose.

The most common is Tokio. But any executor works; here is the same idea using a minimal one from the futures crate, with no Tokio at all:

1
use futures::executor::block_on;
2

3
async fn greet(name: &str) -> String {
4
    format!("Hello, {name}!")
5
}
6

7
fn main() {
8
    // `block_on` is an executor: it drives the future to completion on this thread.
9
    let message = block_on(greet("Rust"));
10
    println!("{message}");
11
}

Output:

1
Hello, Rust!

block_on is the executor: it repeatedly polls the future until it returns Poll::Ready, blocking the current thread in the meantime. The point is that something — block_on, #[tokio::main], a runtime you build by hand — must call poll. Futures cannot run themselves.

Building a runtime explicitly

#[tokio::main] is convenient, but it is only a macro that expands to “build a runtime and call block_on.” You can do it yourself, which makes the “you supply the runtime” point unmistakable:

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

3
async fn do_work() -> &'static str {
4
    sleep(Duration::from_millis(50)).await;
5
    "work complete"
6
}
7

8
fn main() {
9
    // The runtime is something YOU build — there is no implicit global executor.
10
    let runtime = tokio::runtime::Runtime::new().expect("failed to build runtime");
11
    let result = runtime.block_on(do_work());
12
    println!("{result}");
13
}

Output:

1
work complete

Key Differences

Aspect	JavaScript `Promise`	Rust `Future`
Execution start	Eager — runs on creation	Lazy — runs only when `.await`ed/polled
What creation does	Starts the work, returns a handle	Builds an inert state machine, runs nothing
Runtime / event loop	Built in (browser / Node libuv)	None in `std`; you choose one (Tokio, `futures`, …)
Core mechanism	Microtask queue managed by the engine	`poll` returning `Ready`/`Pending`, driven by an executor
Re-running	Cannot re-run; a settled Promise is final	Re-buildable: a closure can produce a fresh future each call
Cancellation	Hard — a started Promise keeps going	Drop the future before completion and its work stops
Concurrency for free	`Promise.all` of already-running promises	None; combine with `join!`/`select!` or spawn tasks
Overhead of unused one	Work already happened (wasted)	Zero — an unawaited future never ran

Why lazy is a feature, not a quirk

Laziness gives Rust three things JavaScript cannot offer easily:

Zero-cost composition. You can build a big tree of combined futures (join!, select!, adapters) and the work only happens when the whole thing is awaited. There is no partial, wasted execution.
Real cancellation. Because a future is just a value, dropping it before it finishes stops its work cleanly. A JavaScript Promise, once started, runs to completion even if nobody is listening — there is no built-in .cancel().
Backpressure and control. The executor decides when and how often to poll, enabling sophisticated scheduling that an always-running model can’t express.

Warning: The flip side is the classic beginner trap: if you build a future and never .await it, none of its code runs. In JavaScript a “fire-and-forget” Promise still executes; in Rust it silently does nothing. The compiler warns you about this (see Pitfalls).

Common Pitfalls

Pitfall 1: Forgetting `.await` — the future never runs

This is the number one mistake for JavaScript developers. In JavaScript, dropping the await still runs the work (you just don’t wait for it). In Rust, dropping .await means the work never happens.

1
async fn save_to_db(name: &str) {
2
    println!("saving {name}");
3
}
4

5
#[tokio::main]
6
async fn main() {
7
    save_to_db("Alice"); // forgot .await — body never runs
8
    println!("done");
9
}

The compiler catches this with a warning (it does not stop compilation, so watch for it):

1
warning: unused implementer of `Future` that must be used
2
 --> src/main.rs:7:5
3
  |
4
7 |     save_to_db("Alice"); // forgot .await — body never runs
5
  |     ^^^^^^^^^^^^^^^^^^^
6
  |
7
  = note: futures do nothing unless you `.await` or poll them
8
  = note: `#[warn(unused_must_use)]` on by default

The note — “futures do nothing unless you .await or poll them” — is the lazy model spelled out. The fix is to add .await (or spawn a task if you genuinely want fire-and-forget):

1
async fn save_to_db(name: &str) {
2
    println!("saving {name}");
3
}
4

5
#[tokio::main]
6
async fn main() {
7
    save_to_db("Alice").await; // now the body runs
8
    println!("done");
9
}

cargo clippy reports the same thing, so a linted CI will not let this slip through:

1
warning: unused implementer of `std::future::Future` that must be used
2
 --> src/main.rs:7:5
3
  |
4
7 |     save_to_db("Alice"); // forgot .await — body never runs
5
  |     ^^^^^^^^^^^^^^^^^^^
6
  |
7
  = note: futures do nothing unless you `.await` or poll them
8
  = note: `#[warn(unused_must_use)]` on by default

Pitfall 2: Using `.await` outside an async context

You can only .await inside an async fn or async block. Trying to await in a plain fn (including a non-async main) is a hard error.

1
async fn fetch() -> u32 {
2
    42
3
}
4

5
fn main() {
6
    let x = fetch().await; // does not compile (error[E0728])
7
    println!("{x}");
8
}

Real compiler error:

1
error[E0728]: `await` is only allowed inside `async` functions and blocks
2
 --> src/main.rs:6:21
3
  |
4
5 | fn main() {
5
  | --------- this is not `async`
6
6 |     let x = fetch().await; // await outside async
7
  |                     ^^^^^ only allowed inside `async` functions and blocks

The fix is to enter an async context: add #[tokio::main] to make main async, or drive the future with an executor like runtime.block_on(...) / futures::executor::block_on(...) as shown earlier.

Pitfall 3: Expecting work to start before `.await`

Because of eager Promises, JavaScript developers often write code assuming a “kick off now, await later” pattern:

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

3
async fn slow(label: &str) -> &str {
4
    sleep(Duration::from_millis(100)).await;
5
    label
6
}
7

8
#[tokio::main]
9
async fn main() {
10
    // This does NOT start both timers — `b` hasn't begun yet.
11
    let a = slow("a");
12
    let b = slow("b");
13
    // Total wait is ~200 ms, not ~100 ms:
14
    let (ra, rb) = (a.await, b.await);
15
    println!("{ra} {rb}");
16
}

The two slow(...) calls just build futures; neither timer starts. By the time you a.await, only a is running; b doesn’t begin until a finishes. If you wanted them concurrent, use tokio::join! or spawn tasks. This compiles and runs fine — it’s a correctness/performance trap, not a compile error, which makes it especially sneaky.

Pitfall 4: Thinking there’s a default runtime

Coming from Node, it is tempting to assume “async just works.” It does not — without a runtime, .await has nothing to drive it. Calling block_on from inside an already-running Tokio runtime, or forgetting the runtime entirely, leads to panics or the “await outside async” error from Pitfall 2. The mental model to internalize: async/await is syntax; the runtime is a dependency you add. See tokio-setup.md.

Best Practices

Always .await (or deliberately spawn). Treat the “unused Future” warning as an error in CI. If you truly want background work, use tokio::spawn — that is the explicit, intentional way to “fire and forget.”
Reach for combinators to recover JavaScript-style concurrency. Use join!/try_join! for the Promise.all pattern and select! for Promise.race. Don’t fake concurrency with sequential .awaits.
Let async fn write the Future for you. Return impl Future<Output = T> only when you need to (e.g., conditionally choosing between futures); otherwise just write async fn. Never hand-implement the Future trait unless you are writing a low-level primitive.
Pick one runtime and stick to it. Mixing executors (e.g., futures::executor::block_on inside a Tokio task) causes confusing behavior. For applications, standardize on Tokio; see tokio-intro.md.
Exploit laziness for retries and timeouts. Because a future is a re-buildable value, a closure || do_work() can produce a fresh future on each attempt — impossible with an already-settled Promise.

Real-World Example

A retry helper showcases why laziness is a genuine advantage. In JavaScript, once you call an async function you get a Promise that is already running and can only be awaited once — retrying means calling the function again. Rust makes this explicit and clean: you pass a closure that builds a fresh future for each attempt.

1
use std::future::Future;
2
use tokio::time::{sleep, Duration};
3

4
/// Runs an async operation, retrying up to `max_attempts` times.
5
/// `op` is a closure that builds a FRESH future each call — possible only
6
/// because Rust futures are lazy and can be created on demand.
7
async fn with_retry<F, Fut, T, E>(max_attempts: u32, mut op: F) -> Result<T, E>
8
where
9
    F: FnMut() -> Fut,
10
    Fut: Future<Output = Result<T, E>>,
11
{
12
    let mut attempt = 1;
13
    loop {
14
        match op().await {
15
            Ok(value) => return Ok(value),
16
            Err(_) if attempt < max_attempts => {
17
                println!("  attempt {attempt} failed, retrying...");
18
                attempt += 1;
19
                sleep(Duration::from_millis(20)).await;
20
            }
21
            Err(err) => return Err(err),
22
        }
23
    }
24
}
25

26
// A flaky "API call" that succeeds on the 3rd try.
27
async fn flaky_fetch(counter: &std::cell::Cell<u32>) -> Result<String, String> {
28
    let n = counter.get() + 1;
29
    counter.set(n);
30
    if n < 3 {
31
        Err(format!("network error (call {n})"))
32
    } else {
33
        Ok(format!("payload from call {n}"))
34
    }
35
}
36

37
#[tokio::main]
38
async fn main() {
39
    let counter = std::cell::Cell::new(0);
40
    let result = with_retry(5, || flaky_fetch(&counter)).await;
41
    match result {
42
        Ok(body) => println!("success: {body}"),
43
        Err(e) => println!("gave up: {e}"),
44
    }
45
}

Real output:

1
  attempt 1 failed, retrying...
2
  attempt 2 failed, retrying...
3
success: payload from call 3

Each call to op() builds a brand-new future; with_retry polls it to completion via .await, and on failure simply builds the next one. Because the future is lazy and re-buildable, the retry logic is just an ordinary loop — no Promise juggling, no double-execution.

Note: Error handling here uses Result<T, E> rather than thrown exceptions. The ? operator integrates with .await to make this ergonomic; that is covered in async-await.md and builds on Section 08: Error Handling.

Exercises

Exercise 1: Make the work actually happen

Difficulty: Beginner

Objective: Internalize that a future does nothing until .awaited.

Instructions: The program below compiles with a warning and prints only done. Fix it so it also logs the event. Do not change the body of log_event.

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

3
async fn log_event(name: &str) {
4
    sleep(Duration::from_millis(10)).await;
5
    println!("logged: {name}");
6
}
7

8
#[tokio::main]
9
async fn main() {
10
    log_event("startup"); // TODO: why doesn't this print anything?
11
    println!("done");
12
}

Solution

The future returned by log_event(...) is never polled, so its body never runs. Add .await:

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

3
async fn log_event(name: &str) {
4
    sleep(Duration::from_millis(10)).await;
5
    println!("logged: {name}");
6
}
7

8
#[tokio::main]
9
async fn main() {
10
    log_event("startup").await; // the fix: add .await
11
    println!("done");
12
}

Output:

1
logged: startup
2
done

Exercise 2: From sequential to concurrent

Difficulty: Intermediate

Objective: See that two futures only run concurrently when you combine them — building them is not enough.

Instructions: This program fetches two prices sequentially, taking ~160 ms. Rewrite it so both fetches run concurrently and the total wait is ~80 ms. Keep both results.

1
use std::time::Instant;
2
use tokio::time::{sleep, Duration};
3

4
async fn fetch_price(symbol: &str, ms: u64) -> f64 {
5
    sleep(Duration::from_millis(ms)).await;
6
    println!("got price for {symbol}");
7
    100.0
8
}
9

10
#[tokio::main]
11
async fn main() {
12
    let start = Instant::now();
13
    let apple = fetch_price("AAPL", 80).await; // TODO: make these
14
    let google = fetch_price("GOOG", 80).await; // TODO: concurrent
15
    println!(
16
        "total {:.1} in ~{} ms",
17
        apple + google,
18
        start.elapsed().as_millis()
19
    );
20
}

Solution

Build both futures and drive them together with tokio::join!. (Awaiting them one at a time is sequential precisely because the second future hasn’t started yet.)

1
use std::time::Instant;
2
use tokio::time::{sleep, Duration};
3

4
async fn fetch_price(symbol: &str, ms: u64) -> f64 {
5
    sleep(Duration::from_millis(ms)).await;
6
    println!("got price for {symbol}");
7
    100.0
8
}
9

10
#[tokio::main]
11
async fn main() {
12
    let start = Instant::now();
13
    // Concurrent: build both futures, then join! drives them together.
14
    let (apple, google) = tokio::join!(
15
        fetch_price("AAPL", 80),
16
        fetch_price("GOOG", 80),
17
    );
18
    println!(
19
        "total {:.1} in ~{} ms",
20
        apple + google,
21
        start.elapsed().as_millis()
22
    );
23
}

Output (the two “got price” lines may appear in either order):

1
got price for GOOG
2
got price for AAPL
3
total 200.0 in ~82 ms

join! is the Promise.all analogue — see select-join.md.

Exercise 3: Implement `Future` by hand

Difficulty: Advanced

Objective: Prove to yourself that “lazy” means “polled,” by writing a Future whose poll you control.

Instructions: Implement a PendingOnce future that returns Poll::Pending the first time it is polled and Poll::Ready("ready now") the second time. Remember to wake the task before returning Pending, or the executor will never poll you again. Await it from main and print the result.

1
use std::future::Future;
2
use std::pin::Pin;
3
use std::task::{Context, Poll};
4

5
struct PendingOnce {
6
    polled_before: bool,
7
}
8

9
impl Future for PendingOnce {
10
    type Output = &'static str;
11

12
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
13
        // TODO: Pending first, Ready second; wake before returning Pending.
14
        todo!()
15
    }
16
}
17

18
#[tokio::main]
19
async fn main() {
20
    let result = PendingOnce { polled_before: false }.await;
21
    println!("{result}");
22
}

Solution

1
use std::future::Future;
2
use std::pin::Pin;
3
use std::task::{Context, Poll};
4

5
// Returns Pending the first poll, Ready the second. Demonstrates the poll loop.
6
struct PendingOnce {
7
    polled_before: bool,
8
}
9

10
impl Future for PendingOnce {
11
    type Output = &'static str;
12

13
    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
14
        if self.polled_before {
15
            Poll::Ready("ready now")
16
        } else {
17
            self.polled_before = true;
18
            cx.waker().wake_by_ref(); // ask the executor to poll us again
19
            Poll::Pending
20
        }
21
    }
22
}
23

24
#[tokio::main]
25
async fn main() {
26
    let result = PendingOnce { polled_before: false }.await;
27
    println!("{result}");
28
}

Output:

1
ready now

The cx.waker().wake_by_ref() call is essential: returning Poll::Pending tells the runtime “not done,” and the waker is how you signal “poll me again.” Without it, the task would sleep forever. This is the machinery async/await generates for you automatically — which is why you should almost never write it by hand.

Promises vs Futures

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

What `async fn` actually returns

Lazy means “polled to completion”

The eager/lazy difference is visible in concurrency

There is no built-in executor

Building a runtime explicitly

Key Differences

Why lazy is a feature, not a quirk

Common Pitfalls

Pitfall 1: Forgetting `.await` — the future never runs

Pitfall 2: Using `.await` outside an async context

Pitfall 3: Expecting work to start before `.await`

Pitfall 4: Thinking there’s a default runtime

Best Practices

Real-World Example

Further Reading

Official Documentation

Exercises

Exercise 1: Make the work actually happen

Exercise 2: From sequential to concurrent

Exercise 3: Implement `Future` by hand

Promises vs Futures

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

What async fn actually returns

Lazy means “polled to completion”

The eager/lazy difference is visible in concurrency

There is no built-in executor

Building a runtime explicitly

Key Differences

Why lazy is a feature, not a quirk

Common Pitfalls

Pitfall 1: Forgetting .await — the future never runs

Pitfall 2: Using .await outside an async context

Pitfall 3: Expecting work to start before .await

Pitfall 4: Thinking there’s a default runtime

Best Practices

Real-World Example

Further Reading

Official Documentation

Related Sections in This Guide

Exercises

Exercise 1: Make the work actually happen

Exercise 2: From sequential to concurrent

Exercise 3: Implement Future by hand

What `async fn` actually returns

Pitfall 1: Forgetting `.await` — the future never runs

Pitfall 2: Using `.await` outside an async context

Pitfall 3: Expecting work to start before `.await`

Exercise 3: Implement `Future` by hand