The crab language is my first programming language.

Which means every concept I encounter, I am encountering it cold — no familiar analogies, no “oh, this is just like how X works in Y.” So when I got to asynchronous programming, I did not just have to understand async. I had to build the entire mental model from scratch.

This is that mental model, written as clearly as I can manage.

The Problem Async Is Solving

Let’s start with something concrete. Imagine you are downloading a file. The download takes five seconds. If your program is synchronous, it will sit there, doing absolutely nothing, for those five entire seconds. The CPU is idle. Your program is blocked. Nothing else can happen.

This is called I/O-bound work — work where the bottleneck is not computation, it is waiting. Waiting for a network response, waiting for a disk to read data, waiting for a timer to finish.

The naive fix is threads. Spawn a new thread for each task. But OS threads are expensive. Each one needs its own memory stack, its own kernel bookkeeping, its own scheduling overhead. A web server handling ten thousand simultaneous connections cannot spin up ten thousand threads. That would be catastrophic.

Asynchronous programming exists to solve this. It lets you handle thousands of tasks concurrently on a handful of threads — or even one — by making tasks cooperative. Instead of the OS forcibly switching between threads, async tasks voluntarily pause themselves at specific points and let the runtime run something else in the meantime.

That is the core idea. Everything else is just the machinery that makes it work.

The Fast-Food Lobby Analogy

Here is the best analogy I found.

Think of a fast-food restaurant with a lobby and buzzers. You walk up, place your order, and the cashier hands you a buzzer. You go sit down. You check your phone, talk to friends, do whatever. You are not blocked at the counter. When your food is ready, the buzzer goes off and you walk back up.

This is async. The cashier is the runtime. The buzzer is the Waker. And .await is the moment you sat down.

Contrast this with a single-lane drive-thru. The car at the window has a complicated order. Every car behind it has to wait. That is synchronous programming.

What Does “Async” Actually Mean in Rust?

When you write async fn something(), the function no longer runs immediately when called. It returns a Future — a paused computation that represents work that will eventually produce a result. Nothing in the function body executes until something drives that future forward.

This is what people mean when they say futures are lazy. Calling an async function is like writing a recipe. The food does not cook itself just because you wrote the recipe down.

let my_future = async {
    println!("This will NEVER print!");
    42
};
// Nothing has happened yet. The print statement has not run.
// my_future is just a paused state machine sitting in memory.

To actually run the future, you either .await it inside another async context, or hand it to a runtime executor like trpl::block_on. Until then, it is inert.

The State Machine the Compiler Builds For You

Here is where it gets genuinely interesting.

When the Rust compiler sees an async function, it does not compile it as a normal function. It transforms it into a state machine — typically an enum — that tracks exactly where the function paused and what local variables it had at that moment.

Take this simple async function:

async fn download(id: i32) {
    println!("Downloading file...");
    tokio::time::sleep(Duration::from_secs(2)).await;
    println!("Finished file {}", id);
}

The compiler turns this into something conceptually like:

enum DownloadStateMachine {
    Start,
    WaitingOnSleep { id: i32 },
    Done,
}

Every .await point is a potential pause point — a place where the state machine saves its current variables, returns Poll::Pending to whoever is polling it, and waits to be woken up again. When the runtime eventually polls it again, the state machine picks up from exactly where it left off.

This is why a future is sometimes described as a paused computation. It is not a thread. It is not a callback. It is a struct in memory, sitting at a known checkpoint, waiting for its turn.

What .await Actually Is

This confused me early on. .await looks like a method but it does not have parentheses. That is because it is not a method. It is a compiler-level keyword that gets transformed into something like this at compile time:

// CONCEPTUAL: What the compiler writes when it sees .await
loop {
    match future.poll(cx) {
        Poll::Ready(value) => break value,  // Done! Return the value.
        Poll::Pending => yield,             // Not ready. Give the CPU back.
    }
}

When you write something.await, you are saying: "Pause this current async block. Repeatedly poll this future until it is ready. Give control to the runtime in between each check."

The key mental model:

.await means: "Suspend ME until THAT future makes progress."

And crucially — the await point is both where you hand control to the runtime and where you take it back when the result is ready.

The Runtime: The Stage Manager

Rust does not ship with an async runtime. This is intentional. A web server running on a beefy multi-core machine needs a very different runtime than a microcontroller with no heap. Rather than forcing one runtime on everyone, Rust lets you pick — or even write your own.

The most common choice is Tokio.

A runtime has two main components:

The Executor is a thread pool. It maintains a queue of runnable tasks, picks one, and polls it. If the task returns Poll::Pending, the executor drops it and pulls the next one.

The Reactor is the bridge to the operating system. It talks to low-level OS event systems — epoll on Linux, kqueue on macOS, IOCP on Windows. When your task is waiting for a network socket, the reactor registers interest with the OS: "Tell me when this socket becomes readable." The OS watches the hardware. When data arrives, it notifies the reactor. The reactor calls the Waker, which tells the executor to put that task back in the queue.

Meanwhile, no thread is blocked. No CPU core is wasting time spinning. The entire mechanism is driven by OS notifications.

The #[tokio::main] macro that you see in Tokio programs is just syntactic sugar. Under the hood, it rewrites your async main into:

fn main() {
    let mut runtime = tokio::runtime::Runtime::new().unwrap();
    runtime.block_on(async {
        // Your code runs here
    });
}

Somewhere, something has to wait. block_on blocks exactly one thread — the main thread — and inside that one blocked thread, thousands of async tasks can run cooperatively without blocking each other.

Why main() Cannot Be Async

This catches a lot of people. You cannot write async fn main() in Rust without an attribute macro like #[tokio::main]. The reason is that main() is where the runtime starts. If main itself were async, something else would need to drive it — which means another runtime underneath, all the way down. The synchronous main is the anchor point. It starts the runtime. The runtime drives everything else.

Concurrency vs. Parallelism (and Where Async Fits)

These two words get conflated constantly. Here is the real difference:

• Parallelism means multiple CPU cores doing work at the same time.
• Concurrency means multiple tasks making progress during overlapping time periods. It does not specify how.

Threads are one way to achieve concurrency. Async is another. The difference is in who manages the scheduling.

With threads, the OS decides which thread runs when, using preemptive scheduling — it can forcibly pause a thread mid-instruction and hand the CPU to another one.

With async, the runtime manages scheduling using cooperative scheduling. A task runs until it voluntarily yields at an .await point. The runtime cannot forcibly pause it mid-execution. This is efficient, but it also means that if a task never yields — say, it is doing heavy CPU computation with no .await points — it will freeze the entire thread and starve every other task on it.

The mental model:

many async tasks
       ↓
runtime scheduler
       ↓
few OS threads

Async does not replace threads. It sits on top of them. The OS schedules threads. Tokio schedules async tasks inside those threads. This is called layered scheduling.

Futures and the Future Trait

At the graduate level, a future is defined by this trait:

pub trait Future {
    type Output;

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

Output is the associated type — the value the future eventually produces. poll is the method the runtime calls repeatedly to ask: "Are you done yet?"

The future responds with either:

Poll::Ready(value)  // "Yes, here is your result."
Poll::Pending       // "Not yet. I have registered my Waker. Come back later."

The cx: &mut Context parameter carries the Waker — the mechanism that lets the future tell the runtime when to come back. Without the Waker, the runtime would have to blindly poll every future in a busy loop, which would be massively wasteful.

When a future calls cx.waker().wake(), it is saying: "I have registered with the OS reactor. When my data arrives, the reactor will call this, which tells you to put me back in the runnable queue."

Pinning: Why Futures Cannot Move in Memory

This one requires some careful thinking.

Async state machines are structs. Sometimes those structs contain references to their own fields — a future that holds a reference to a string it is working on, where both the string and the reference live inside the same struct. These are called self-referential types.

A reference is a memory address. When you move a struct to a new location in memory, the struct’s bytes get copied bit-for-bit to the new address. But the old addresses stored inside those bytes are not updated. If a field pointed to another field inside the same struct, after the move, it now points to where that other field used to be. Dangling pointer. Memory unsafety.

To prevent this, Rust uses Pin<&mut T>. A pinned value is guaranteed to never move in memory while it is being polled. When you write pin!(my_future) using the macro, Rust staples the future to its current stack slot. The future cannot be moved. The internal pointers stay valid.

This is why poll takes self: Pin<&mut Self> rather than &mut self. If you could poll a future through a regular mutable reference, you could move it, which would invalidate those internal pointers.

Streams: Async Iterators

An iterator gives you items immediately, one by one. A stream gives you items over time — each next() call returns a future, which might resolve instantly or might have to wait for a database query, a network packet, or some other async operation.

while let Some(value) = stream.next().await {
    println!("The value was {value}");
}

The trait behind a stream looks like a combination of Iterator and Future:

fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>;

It returns:

• Poll::Pending — not ready yet, come back
• Poll::Ready(Some(item)) — here is the next item
• Poll::Ready(None) — the stream is finished

Note that poll_next also takes Pin<&mut Self> for the same reason poll does — the stream's internal state machine must not move.

The Most Important Mental Model

Here is the table I keep coming back to:

Thing Mental Model async {} Creates a paused computation Future A state machine .await Repeatedly polls the state machine poll() Asks: "Can you make progress?" Pending "Not ready yet, come back later" Ready "I am done"

And the flow:

async block
    ↓
compiled into state machine
    ↓
.await repeatedly polls it
    ↓
future advances step by step
    ↓
sleep().await pauses it
    ↓
executor switches elsewhere
    ↓
future gets polled again later

Async Within One Block Is Still Sequential

This is a mistake that is very easy to make.

Simply writing async and await does not automatically make things run at the same time. If your sending loop and your receiving loop are inside the same async block, they still execute one after the other.

trpl::block_on(async {
    // Sends all messages first...
    for val in vals {
        tx.send(val).unwrap();
        trpl::sleep(Duration::from_millis(500)).await;
    }

    // ...then receives them all.
    while let Some(value) = rx.recv().await {
        println!("received '{value}'");
    }
});

This entire block is one future. One state machine. The .await points let the executor pause this block momentarily, but there is nothing else to run — it just waits out the timer and comes back. The result is sequential, not concurrent.

To run things concurrently, you need to either spawn separate tasks with spawn_task, or join separate futures with trpl::join or join!. Each future becomes independently schedulable, and the executor can interleave them.

let tx_fut = async move { /* send things */ };
let rx_fut = async { /* receive things */ };
trpl::join(tx_fut, rx_fut).await;

Now the executor can run tx_fut until it hits an .await, switch to rx_fut, switch back, and so on. That is real concurrency.

Starving Other Futures

Because async is cooperative, a task that never yields will freeze every other task on its thread. This is called future starvation.

If you write a CPU-heavy loop inside an async block with no .await points, it will hog the thread indefinitely:

let a = async {
    slow("a", 30); // This blocks. No await point.
    slow("a", 10); // Still blocking.
    slow("a", 20); // Still blocking.
    trpl::sleep(Duration::from_millis(50)).await; // Only now does it yield.
};

During those three slow() calls, no other future on this thread can make any progress.

The naive fix is to insert a tiny trpl::sleep(1ms).await between each slow operation. This works, but it introduces artificial delay — you are not actually sleeping, you just want to share the CPU.

The correct fix is yield_now():

slow("a", 30);
trpl::yield_now().await; // "I am pausing voluntarily. Run something else."
slow("a", 10);
trpl::yield_now().await;

yield_now() immediately returns control to the executor without any artificial sleep. As soon as the other tasks have had their turn, execution comes back. It is the difference between being a good citizen and pretending to be asleep.

Threads vs. Async: When to Use Which

Feature Threads Async Managed by The OS The runtime Cost Higher (stack memory, kernel overhead) Lower (a few bytes per task) Best for CPU-bound work I/O-bound work Scheduling Preemptive (OS decides) Cooperative (task decides)

These are not mutually exclusive. Real applications often mix them. You might spawn a standard OS thread to handle a blocking CPU-heavy operation while async handles all the network I/O around it.

thread::spawn(move || {
    // CPU-heavy or blocking work goes here
    for i in 1..11 {
        tx.send(i).unwrap();
        thread::sleep(Duration::from_secs(1)); // Blocking is fine in a thread
    }
});

trpl::block_on(async {
    while let Some(message) = rx.recv().await {
        println!("Received: {message}");
    }
});

The thread does its blocking work. The async side receives results without blocking its runtime. Both models doing what they are best at.

The Precise Summary

Here is the one paragraph I would have wanted on day one:

Async programming avoids needing one OS thread per task by transforming async functions into compiler-generated state machines called Futures. These futures store their paused execution state in memory. The runtime repeatedly polls these futures to make progress. When a future cannot continue, it returns Pending and provides a Waker, which allows the runtime to be notified later — often through OS event systems like epoll or IOCP — when the task is ready to resume. Many tasks share a small number of OS threads. The OS schedules threads. The runtime schedules tasks inside those threads.

That is it. That is the whole thing.

This blog post is based on my notes from reading The Rust Programming Language book. Rust is my first programming language, which means every mental model here was built without prior knowledge of how other languages handle async. If that context is useful to someone else also starting out — that is the point.

Async Rust Finally Made Sense was originally published in Rust in Plain English on Medium, where people are continuing the conversation by highlighting and responding to this story.

Before I even wrote my first line of the crab language, I came across a video from ThePrimeagen where he casually implied that async Rust is notoriously difficult to wrap your head around. I filed that away as a warning. So when I finally got to it — as someone for whom Rust is their first programming language — I braced for the worst.

It didn’t go the way I expected. Instead of hitting a wall, I found myself genuinely fascinated. The concepts weren’t just challenging — they were elegant. Understanding how async Rust works under the hood is actually what made async programming as a whole click for me. This post is my attempt to walk you through that same understanding, from the inside out.

The Future Trait: The Foundation

Everything in async Rust sits on top of one core abstraction: the Future trait. Here is how Rust defines it:

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

Let’s unpack this piece by piece, because every single part here is doing something important.

Associated Types vs. Generics

The first thing that might catch your eye is type Output. This is an associated type, and it answers a question you might have asked yourself: why not just write Future<T> like a generic?

Here is the problem with generics in this case. If the trait were defined as Future<T>, a single struct could potentially implement both Future<String> and Future<i32> at the same time:

struct MyWork;

impl Future<String> for MyWork {
    fn poll(&mut self) -> String { "Done".into() }
}

impl Future<i32> for MyWork {
    fn poll(&mut self) -> i32 { 100 }
}

Now imagine writing let result = MyWork.await. The compiler has absolutely no idea whether result should be a String or an i32. It's ambiguous, and Rust does not tolerate ambiguity.

With an associated type (type Output), each implementing type can only define Output once. One type, one future, one output. The compiler always knows what it's dealing with.

Poll<T>: The Answer the Runtime Gets

When the runtime asks a future “are you done yet?”, the future answers with a Poll:

pub enum Poll<T> {
    Ready(T),
    Pending,
}

It’s beautifully simple. Either the future has finished and here is the result (Ready(T)), or it's still working (Pending). Think of it like Option<T> — one variant carries a value, one doesn't.

One important thing worth knowing: once a future returns Ready, you should not call poll on it again. Most futures will panic if you do. This behavior mirrors Iterator::next — once the iterator signals it's done, continuing to call next is on you.

How .await Works

The .await keyword feels magical, but it is really just a loop with a poll call at its heart. A rough mental model looks like this:

let page_title_fut = page_title(url);
loop {
    match page_title_fut.poll {
        Ready(value) => {
            // we have the value, break out
        }
        Pending => {
            continue,
        }
    }
}

Of course, a real runtime is far smarter than a busy loop. The cx: &mut Context<'_> parameter is the key to that. The Context carries a waker — a mechanism that lets the future tell the runtime "hey, I'm still waiting, but wake me up when I'm ready." The runtime can then park that future and go do other work, instead of spinning in place wasting CPU cycles.

The Pin Type: The Part Everyone Struggles With

This is where most people hit a wall, myself included. Let’s go slow.

Why Does Pinning Exist?

When Rust compiles an async block, it doesn't generate some magic thread. It generates a state machine — a struct that remembers where in the async function we currently are, and all the local variables needed to resume from that point.

Here is the thing about that struct: it can be self-referential. One field of the struct might hold a reference to another field in the same struct. For example, if your async function creates a buffer and then borrows from it, both the buffer and the reference to it live inside the same generated struct.

Now imagine moving that struct to a new location in memory (say, from the stack to the heap). In Rust, moving something is a bitwise copy. The bytes get copied faithfully to the new address — including the pointer that was pointing to a field within the old location. That field has now moved too, but the pointer still holds the old address. You just created a dangling pointer.

This is the core problem Pin is designed to solve.

The Memory Geography of Box<dyn Future> vs. pin!

To make this concrete, consider a case where we want to run several futures concurrently and store them in a Vec. A first attempt might look like:

let futures: Vec<Box<dyn Future<Output = ()>>> =
    vec![Box::new(tx1_fut), Box::new(rx_fut), Box::new(tx_fut)];

Here is what’s happening in memory with this approach:

• futures is a stack variable.
• It points to heap-allocated memory for the Vec itself.
• Each item in the Vec is a Box — another pointer — to the actual future on the heap.
• The future (state machine struct) was moved from the stack to the heap during the Box::new(...) call.

That move is the problem. When the state machine is copied bit-for-bit from the stack to the heap, any self-referential pointers inside it now point to the old stack memory. That memory is gone. Dangling pointer.

The error message Rust gives you is illuminating:

error[E0277]: `dyn Future<Output = ()>` cannot be unpinned

The solution is pin!:

let tx1_fut = pin!(async move { ... });
let rx_fut  = pin!(async { ... });
let tx_fut  = pin!(async move { ... });

let futures: Vec<Pin<&mut dyn Future<Output = ()>>> =
    vec![tx1_fut, rx_fut, tx_fut];

Here is what changes:

The pin! macro "staples" the state machine to the current stack frame. It uses a shadowing trick — it replaces your variable with a Pin<&mut Future> that points to the same stack slot. The actual future data does not move. The Vec then stores references to these pinned stack locations, not owned copies on the heap.

Let’s make this comparison explicit:

Box<dyn Future> pin! Future Location Heap (inside the Box) Stack (local variables) Indirection Vec → Box → Future Vec → Reference → Future Safety Check Runtime Compile-time Heap Allocations 3+ (Vec + each Box) 1 (just the Vec)

The pin! approach is faster, and more importantly, it is safe at compile time. The Rust compiler can statically verify that you will never move the future after pinning it.

pin! vs. Box::pin

Once you understand pinning, the difference between the two becomes obvious:

• pin! (macro) — Stack pinning. The future stays on the stack, anchored to the current function's frame. Use this when your future is a local variable and you don't need it to outlive the current scope. Cheaper, since it avoids a heap allocation for the future itself.
• Box::pin (function) — Heap pinning. The future is moved to the heap, but pinned there. Use this when the future needs to outlive the current function, or when you're storing it in a data structure that requires ownership (not just a reference).

And as for why the poll method takes Pin<&mut Self> rather than Pin<&Self> — the state machine changes state. It transitions from Pending to Ready. That requires mutability. &mut is non-negotiable here.

The Stream Trait: Futures That Keep Giving

Once you have a solid understanding of Future, Stream is a natural extension. The best way to think about it is in three levels.

The intuition: A Future is like ordering a single package online. You wait, and eventually it arrives. An Iterator is like a local shelf — you reach in and grab items instantly, one after another. A Stream is like a subscription box. Items arrive over time, and you have to wait for each one.

• Iterator: Give me the next item. (Instant)
• Future: Give me one thing, but I’ll have to wait for it. (Wait once)
• Stream: Give me a sequence of things, and I’ll have to wait for each one. (Wait many times)

The mechanics: The Stream trait is essentially a hybrid of Iterator and Future. When you poll a stream, it returns one of three things:

1. Poll::Pending — "I'm still waiting for the next item."
2. Poll::Ready(Some(item)) — "Here is the next item."
3. Poll::Ready(None) — "The stream is exhausted."

The signature of poll_next reflects this:

fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>;

Notice that poll_next also takes self: Pin<&mut Self>. The same reasoning applies — the stream is a state machine, it mutates its state between polls, and it must not be moved mid-operation.

In practice, you rarely call poll_next directly. You use StreamExt, which gives you the familiar .next().await ergonomics:

while let Some(msg) = message_stream.next().await {
    println!("Received: {msg}");
}

That .next().await is hiding a poll_next call inside a loop, with the waker mechanism handling the "come back when there's data" part for you.

Putting It All Together

Here is the mental model I now carry around:

Every async block compiles into a struct — a state machine. That struct implements Future. Its poll method is called by the runtime. If the work is done, it returns Ready. If not, it registers a waker via the Context and returns Pending. The runtime parks the future and comes back when the waker fires.

Because those state machine structs can be self-referential, moving them is dangerous. Pin exists to make the compiler aware of this constraint and enforce it. The pin! macro keeps futures on the stack; Box::pin moves them to the heap but pins them there.

Stream extends this entire model to a sequence of values that each arrive asynchronously — Iterator + Future composed into one trait.

What struck me most about all of this is how deeply compositional the design is. There is no special scheduler baked into the language. There is no hidden thread pool in the compiler. There is just a chain of well-designed traits, each solving one specific problem, that together produce a complete async system. The runtime (whether Tokio or async-std) plugs into this system through the Context and the waker mechanism — and the rest follows.

It took me a while to appreciate that, but I think it’s genuinely beautiful.

This blog post is based on my notes from reading The Rust Programming Language book. Any feedback and corrections are welcomed

Thanks for reading.

The Thing That Made Async Rust Finally Click For Me was originally published in Rust in Plain English on Medium, where people are continuing the conversation by highlighting and responding to this story.

And honestly, it took longer than I’d like to admit.

Rust was my first programming language. Not Python. Not JavaScript. Rust — the language that apparently makes experienced developers cry. So when the Rust book threw “functional programming” at me, I didn’t have the luxury of thinking, “oh, this is just like how we do it in Python.” I had to figure it out from scratch.

What follows is everything I learned, structured the way I wish someone had explained it to me: starting simple, then building up. If you’re new to programming, or new to Rust, I hope this saves you a few hours of staring blankly at your screen.

What is Functional Programming, Actually?

Before diving into any code, here’s the honest one-line answer: functional programming is a style of writing code where you describe what you want, not how to do it, step by step.

That’s it. Everything else — immutability, closures, iterators — is just what that philosophy looks like in practice.

Level 1: The “No-Touchy” Rule

The most foundational idea in functional programming is immutability. The idea is simple: instead of reaching into a variable and changing it, you leave it alone and create something new from it.

Think of it like this — if your friend lends you their notes, you photocopy them and write on the copy. You don’t scribble on the original. Immutability is that instinct, but for code.

Here’s what that looks like in Rust:

fn main() {
    let scores = vec![10, 20, 30];

    // Instead of a for loop that changes scores,
    // we create a new collection: doubled_scores.
    let doubled_scores: Vec<i32> = scores.iter()
        .map(|x| x * 2)  // for each x, give me x * 2
        .collect();       // put them into a new vector

    println!("{:?}", doubled_scores); // [20, 40, 60]
}

scores.iter() goes over each value one at a time. .map() takes each value and applies the rule x * 2. .collect() gathers everything into a brand new vector. The original scores is never touched.

Why does this matter? If you never change a variable, you can never accidentally break it somewhere else in your program. It’s a safety guarantee baked right into the style.

“But Wait — Won’t Copying Everything Kill My Memory?”

This was the first question I asked. And it’s the right one.

If you’re copying a massive list 100 times across 100 iterations, you’d crash a server. But here’s the trick: Rust’s iterators are lazy.

When you write .map(|x| x * 2), Rust does not immediately create a new list. It sets up a conveyor belt. The multiplication only happens when something downstream actually asks for a value — like .collect(). The data moves through the pipeline exactly once.

If you use .into_iter() instead of .iter(), the original vector is consumed and its values move into the new one. No copying at all:

let big_vec = vec![1, 2, 3];
let new_vec: Vec<i32> = big_vec.into_iter() // big_vec ends here
    .map(|x| x + 1)
    .collect(); // new_vec begins here

So: functional programming is not slow. It’s not memory-hungry. Rust calls this zero-cost abstraction — the compiled code is just as fast as a hand-written loop, sometimes faster.

Level 2: Pipelines and Higher-Order Functions

Now that we understand the “no-touchy” rule, let’s talk about what makes functional programming genuinely elegant: chaining operations together like a pipeline.

Instead of writing out every step manually, you describe the transformations you want. This is called declarative programming.

fn main() {
    let nums = vec![1, 2, 3, 4, 5, 6];

    let result: i32 = nums.into_iter()
        .filter(|x| x % 2 == 0) // keep only even numbers
        .map(|x| x * x)         // square them
        .sum();                  // add them all up

    println!("The result is {}", result); // 56
}

Read that code like a sentence: “Take the numbers, keep the even ones, square them, and sum everything up.” That’s what declarative means — you say what you want, and Rust figures out the how.

The key feature enabling this is higher-order functions: functions that take other functions as arguments. .filter() and .map() both accept closures — small anonymous functions you pass in. Which brings us to the heart of the whole thing.

Closures: Anonymous Functions That Carry a Backpack

A closure is a function with no name. Like Python’s lambdas, but more powerful, because closures in Rust can capture variables from the scope around them.

Think of a closure as a bundle of instructions that also carries a “backpack” of data from wherever it was created.

Here’s a simple example:

fn main() {
    let greeting = "Welcome";

    let greet = |name| {
        println!("{} {}", greeting, name)
    };

    greet("Riz"); // output: Welcome Riz
}

greet is a function disguised as a variable. The parameter name is passed in when you call it. But greeting? That comes from the surrounding scope. The closure reached out and grabbed it. That's the "backpack."

How Closures Capture: Three Ways

When a closure captures a variable from its environment, it does so in one of three ways:

1. Borrowing (read-only)

let list = vec![1, 2, 3];
let only_borrows = || println!("From closure: {:?}", list);
only_borrows();
println!("Still usable: {:?}", list); // works fine

2. Mutably Borrowing (read and write)

let mut list = vec![1, 2, 3];
let mut add_to_list = || list.push(4);
add_to_list();
println!("{:?}", list); // [1, 2, 3, 4]

3. Taking Ownership (the move keyword)

let list = vec![1, 2, 3];
let takes_ownership = move || println!("I own the list now: {:?}", list);
// list is no longer accessible here

The move keyword is essential when passing closures to threads — you don't want your data to disappear while another thread is running with it.

The Secret Underneath: Closures Are Structs

Here’s the graduate-level truth: when you write a closure, Rust doesn’t create a “naked” function. It quietly generates a hidden struct that holds whatever the closure captured, and implements one of three traits on it.

These traits are the job descriptions a closure must fulfil:

Trait Contract Callable FnOnce Takes ownership of captured variables Only once FnMut Mutably borrows captured variables Multiple times, can change them Fn Immutably borrows captured variables Multiple times, read-only

They nest inside each other: Fn implies FnMut, which implies FnOnce. FnOnce is the most general — it only promises the closure can be called at least once.

How Closures and Traits Fit Together: A Job Analogy

The best way I found to understand all of this at once is the job analogy.

• Traits (Fn, FnMut, FnOnce) are job descriptions — they define what requirements a candidate must meet.
• Generic type parameters (like <F>) are job openings — slots waiting to be filled.
• Closures are applicants — they come with their own internal struct and data.

Look at the definition of unwrap_or_else on the Option enum:

impl<T> Option<T> {
    pub fn unwrap_or_else<F>(self, f: F) -> T
    where
        F: FnOnce() -> T
    {
        match self {
            Some(x) => x,
            None => f(),
        }
    }
}

Step by step:

• <F> is a generic type: "this function works with any type, as long as we call it F."
• f: F is the actual closure you pass in — the hidden struct the compiler built.
• where F: FnOnce() -> T is the requirement: "I don't care what your struct is called internally, as long as it implements FnOnce."
• f() is syntax sugar. The compiler sees it and calls f.call_once() under the hood.

Why where Instead of Inline Bounds?

You can write trait bounds inline — <F: FnOnce() -> T> — and it works. But when you have multiple type parameters with multiple bounds, inline gets painful to read:

fn do_something<T: Display + Clone, U: Clone + Debug, V: Into<String>>(t: T, u: U, v: V) -> i32 {
    // ...
}

The where clause cleans this up considerably:

fn do_something<T, U, V>(t: T, u: U, v: V)
where
    T: Display + Clone,
    U: Clone + Debug,
    V: Into<String>
{
    // ...
}

Same meaning. Much easier on the eyes.

Iterators: The Real Engine

Now let’s talk about the thing that makes pipelines actually work: iterators.

Every iterator in Rust implements the Iterator trait, which boils down to one core method:

pub trait Iterator {
    type Item;
    fn next(&mut self) -> Option<Self::Item>;
}

type Item is an associated type — a placeholder that each specific iterator fills in. A vector of i32 values gives an iterator where Item = i32. The next() method hands you values one at a time, wrapped in Some, until there's nothing left and it returns None.

You can call next() directly:

let v1 = vec![1, 2, 3];
let mut v1_iter = v1.iter();

assert_eq!(v1_iter.next(), Some(&1));
assert_eq!(v1_iter.next(), Some(&2));
assert_eq!(v1_iter.next(), Some(&3));
assert_eq!(v1_iter.next(), None);

Note that v1_iter must be mut. The iterator keeps an internal bookmark of where it is. Calling next() moves that bookmark forward — the iterator's own data changes, so the variable holding it must be mutable.

iter() vs into_iter() vs &v

Syntax Ownership of original Type of each item for val in v1.iter() Preserved (borrowed) &T for val in v1 Consumed (moved) T for val in &v1 Preserved (borrowed) &T

Use .iter() when you want to keep the original. Use .into_iter() when you're done with it.

Consuming Adapters vs. Iterator Adapters

Iterator methods split into two camps:

Consuming adapters call next() and use up the iterator. sum() is the classic example — it pulls every value out, adds them up, and the iterator is gone afterward.

let v1 = vec![1, 2, 3];
let total: i32 = v1.iter().sum();
assert_eq!(total, 6);

Iterator adapters don’t consume. They produce a new iterator with some transformation applied. map() and filter() are iterator adapters. They are lazy — nothing happens until a consuming adapter comes along and demands values.

let v1: Vec<i32> = vec![1, 2, 3];
v1.iter().map(|x| x + 1); // warning: does nothing

Rust will actually warn you here. The iterator is set up, the closure is defined, but without a .collect() or .sum() at the end, no values ever flow through. This is lazy evaluation in its most visible form.

The correct version:

let v2: Vec<i32> = v1.iter().map(|x| x + 1).collect();

Here’s the sequence of what actually happens:

1. collect() asks map() for the first item.
2. map() asks v1.iter() for the first item.
3. v1.iter() hands back Some(&1).
4. map() runs the closure: 1 + 1 = 2. Hands 2 to collect().
5. collect() stores it. Asks again.
6. This repeats until v1.iter() returns None.
7. collect() stops and hands back the finished vector.

Data travels through the chain exactly once. No intermediate collections are created.

Closures Capturing the Environment: A Real Example

Iterator adapters often take closures as arguments, and those closures can reach into the surrounding environment. This is where the two ideas — closures and iterators — combine into something genuinely useful.

fn shoes_in_size(shoes: Vec<Shoe>, shoe_size: u32) -> Vec<Shoe> {
    shoes.into_iter().filter(|s| s.size == shoe_size).collect()
}

The closure |s| s.size == shoe_size captures shoe_size from the function's parameters. The filter() adapter uses that closure to decide which shoes survive. into_iter() consumes the original vector. collect() assembles the result.

Clean. Readable. No mutation anywhere.

Handling “Nothingness” the Functional Way

One more pattern worth understanding: functional programming handles the absence of a value as gracefully as it handles the presence of one.

In Rust, this is the Option enum. And the real power comes when you chain operations on it:

fn get_user_id(username: &str) -> Option<u32> {
    if username == "admin" { Some(1) } else { None }
}

fn main() {
    let access_level = get_user_id("admin")
        .map(|id| id * 10)
        .and_then(|id| Some(id + 5));

    println!("Access level: {:?}", access_level); // Some(15)
}

If "admin" is passed:

• get_user_id returns Some(1)
• .map() unwraps it, applies * 10, rewraps: Some(10)
• .and_then() unwraps it, applies + 5, and we wrap it: Some(15)

If any other username is passed:

• get_user_id returns None
• .map() sees None, skips
• .and_then() sees None, skips
• Result: None

The key difference between .map() and .and_then():

• .map() says: "I'll wrap the result for you."
• .and_then() says: "You wrap it yourself."

That’s why we wrote Some(id + 5) inside and_then — if we'd written just id + 5, the types wouldn't match and the compiler would rightly complain.

The Bigger Picture

By the end of all this, the pattern becomes clear.

Functional programming in Rust is not a separate universe from the rest of the language — it’s baked in. Iterators, closures, Option, map, filter, collect — these aren't exotic add-ons. They're the idiomatic way Rust expects you to process data.

The reason it feels unfamiliar at first isn’t because it’s complicated. It’s because most people learning programming are taught the imperative style — loops, mutations, step-by-step instructions — before they ever see the declarative alternative. Once the pipeline model clicks, reading Rust code starts to feel less like deciphering instructions and more like reading a sentence.

That shift in how you read code? That’s when it gets fun.

This post was written while working through The Rust Programming Language book. If you’re starting from zero like I was, I’d recommend reading it alongside writing actual code — nothing makes the concepts land faster than watching the compiler yell at you.

I Learned Functional Programming in Rust Before I Knew What “Functional” Even Meant was originally published in Rust in Plain English on Medium, where people are continuing the conversation by highlighting and responding to this story.

Most resources about Rust smart pointers assume you already know what a pointer is. They assume you’ve spent time in C or C++, that you’ve felt the pain of a dangling pointer or a segfault, and that you’re now here looking for a safer alternative.

I had none of that context. Rust is my first programming language.

So when Chapter 15 of The Rust Programming Language book opened with “A pointer is a variable which stores the memory address of a chunk of memory,” I had to stop, stare at that sentence for a while, and actually think about what memory even is.

What follows is what I pieced together. Not just what smart pointers are, but why they exist the way they do — and the mental models that finally made everything feel less like magic and more like deliberate, sensible design.

First: What Even Is a Pointer?

Think of your computer’s RAM as a massive row of numbered mailboxes. Each box can hold a small piece of data. A pointer is a variable that doesn’t hold actual data — it holds the address (the box number) of where the real data lives.

A reference in Rust (&) is essentially a pointer, but with rules attached: ownership rules, borrowing rules, lifetime rules. Rust enforces that these rules are never broken, and it does so at compile time — before the program even runs.

Smart pointers are data structures that act like pointers but carry additional capabilities on top. They’re implemented as structs that implement two special traits: Deref and Drop.

• Deref lets you write code that works the same way whether you're working with a regular reference or a smart pointer.
• Drop lets you define cleanup logic — what happens when the smart pointer goes out of scope.

Here’s something that surprised me: we’ve already used smart pointers without realizing it. String and Vec<T> are smart pointers.

Box<T>: The Most Boring Smart Pointer (In the Best Way)

Box<T> is the most stripped-down smart pointer in Rust. All it does is allocate a value on the heap instead of the stack. No reference counting, no shared ownership, nothing fancy. Just a pointer to some heap memory that it owns.

You use it in three situations:

1. When you don’t know a type’s size at compile time

Rust needs to know exactly how much space every type takes at compile time so it can allocate the right amount of stack space. This becomes a problem with recursive types — types that contain themselves.

// This won't compile
enum List {
    Cons(i32, List), // Rust asks: how big is List? Well, it contains a List... infinite!
    Nil,
}

The fix is elegant. Since a pointer always has a fixed size (8 bytes on a 64-bit system), you just put the recursive part behind a Box:

enum List {
    Cons(i32, Box<List>), // Fixed size now: one i32 + one pointer
    Nil,
}

2. When moving large data would be expensive

When you move a value in Rust, if it lives on the stack, Rust copies all of it to a new location. For large data, that’s expensive. If instead the data lives on the heap behind a Box, moving ownership only copies the pointer — 8 bytes regardless of how big the data is.

3. When you want to store different types together

Sometimes you want a Vec that can hold different types — say, a Button struct and a Text struct — that share a common trait. Since different structs have different sizes, a plain Vec can't hold them. But a Vec<Box<dyn Draw>> can, because every element is just a pointer of the same size, regardless of what it points to.

The Deref Trait: Teaching Rust What * Means for Your Type

When you write *y in Rust, you're asking: "give me whatever y is pointing at." For a standard reference (&T), the compiler knows exactly how to do this. But for a custom struct? The compiler has no idea.

This is why the Deref trait exists. It lets you say: "when someone uses * on my type, here is how to get to the underlying data."

When you implement Deref for MyBox<T>:

use std::ops::Deref;

impl<T> Deref for MyBox<T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        &self.0 // return a reference to the inner value
    }
}

Under the hood, *y becomes *(y.deref()). Rust calls your deref() method to get a reference, and then applies the standard dereference to that. The compiler handles all of this invisibly.

Deref Coercion: Rust’s Quality-of-Life Gift

Once you implement Deref, Rust gives you something extra: deref coercion. This is an automatic conversion that happens when you pass a reference of one type to a function expecting a reference of another type — as long as a chain of Deref implementations connects them.

For example, if you have a &MyBox<String> and a function that expects a &str, Rust will:

1. Call deref() on &MyBox<String> → gets &String
2. Call deref() on &String → gets &str
3. Match found. Done.

Without this, you’d write:

hello(&(*m)[..]);

With it, you just write:

hello(&m);

The chain happens entirely at compile time, so there’s zero runtime cost.

The Drop Trait: Automating Cleanup

Drop lets you define what happens when a value goes out of scope. For smart pointers, this is where memory gets freed. For file handles, this is where the file gets closed. For network connections, this is where you tell the server you're done.

In languages like C, forgetting to close a file can corrupt it. Forgetting to free memory causes your program to gradually consume more and more RAM. The Drop trait makes all of this automatic in Rust.

impl Drop for MyFile {
    fn drop(&mut self) {
        println!("Closing file and saving data: {}", self.filename);
    }
}

The moment the value goes out of scope, this runs. You don’t call it. You can’t forget it.

One thing to know: you cannot call .drop() directly on a value. Rust won't let you, because it would cause a double free — Rust would try to clean up the same memory twice. If you want to drop something early, use the drop(value) function from std::mem::drop, which transfers ownership and drops it safely.

Values are dropped in reverse order of creation, by the way. The last thing created is the first thing cleaned up.

Rc<T>: When One Owner Isn't Enough

Rust’s default rule is single ownership: exactly one variable owns a piece of data at any time. That’s usually fine. But sometimes it genuinely isn’t.

Think of a graph data structure. A node might be pointed to by multiple edges. If you delete one edge, the node shouldn’t disappear — the other edges still need it. The node should only be cleaned up when nobody is pointing to it anymore.

This is what Rc<T> — Reference Counted — handles. It keeps a count of how many owners a piece of heap-allocated data has. Every time you create a new owner (Rc::clone(&value)), the count goes up. Every time an owner goes out of scope, the count goes down. When the count hits zero, the data is dropped.

let a = Rc::new(Node { ... });       // count: 1
let b = Rc::clone(&a);              // count: 2
let c = Rc::clone(&a);              // count: 3
// c goes out of scope             // count: 2
// b goes out of scope             // count: 1
// a goes out of scope             // count: 0 → data is freed

Two things to remember about Rc<T>:

First, Rc::clone() is not like a regular .clone(). It doesn't copy any data. It just increments the counter and gives you another pointer to the same data. This is cheap.

Second, Rc<T> only allows immutable access to the data. If multiple owners could all mutate the same value, you'd have chaos. This immutability is intentional and enforced.

Rc<T> is also single-threaded only. For multiple threads, you'd use Arc<T> (Atomic Reference Counting), which handles the counter increments safely across threads.

RefCell<T>: Mutating the Immutable (Carefully)

Here’s where things get genuinely interesting — and where Rust’s philosophy shows its teeth.

RefCell<T> enables something called interior mutability: the ability to mutate data even when you only have an immutable reference to it. This sounds like it should be illegal. In most of Rust, it is. But RefCell<T> does it safely by moving the borrow-checking from compile time to runtime.

The borrowing rules still apply — you can still only have one mutable borrow at a time, or any number of immutable borrows, but not both. If you violate these rules with RefCell<T>, your program doesn't fail to compile. It panics at runtime instead.

Why would you ever want this? Consider the most common reason: traits.

Sometimes a library defines a trait method with &self — immutable access. You implement that trait, and you're locked into that signature. But what if your implementation needs to mutate some internal state to do its job? You can't change the method signature. The Drop trait is a perfect example. So is any logging or caching mechanism.

RefCell<T> solves this by letting you hide the mutability:

struct MockMessenger {
    sent_messages: RefCell<Vec<String>>,
}

impl Messenger for MockMessenger {
    fn send(&self, message: &str) {
        self.sent_messages.borrow_mut().push(String::from(message));
    }
}

From the outside, MockMessenger looks immutable. Internally, borrow_mut() gives you temporary mutable access to the Vec, and the borrow-checking happens at runtime.

If you try to take two mutable borrows at once, the program panics. This is the tradeoff you accept: runtime errors instead of compile-time ones, in exchange for flexibility the compiler can’t reason about on its own.

RefCell<T> is also single-threaded. The thread-safe equivalent is Mutex<T>.

Combining Rc<T> and RefCell<T>

Each of these types solves one problem:

• Rc<T>: multiple owners, but only immutable access
• RefCell<T>: single owner, but mutable access even from an immutable reference

What if you need both? Multiple owners and mutability?

You combine them: Rc<RefCell<T>>.

let value = Rc::new(RefCell::new(5));

let a = Rc::clone(&value);
let b = Rc::clone(&value);

*value.borrow_mut() += 10;

// Both a and b now see the updated value: 1

This pattern comes up frequently when building data structures where multiple parts of your program need to share and modify the same piece of data.

Reference Cycles: The One Way Rust Can Leak Memory

Rust’s ownership system makes memory leaks nearly impossible. Nearly.

If you use Rc<T> and RefCell<T> together carelessly, you can create a reference cycle — where object A points to object B, and object B points back to object A. Both have a reference count of 2. When they go out of scope, the stack variables drop, bringing each count to 1. But the count never reaches 0, because each object is holding the other alive.

The data sits in the heap forever — no longer reachable from your code, never freed. That’s a memory leak.

The solution is Weak<T>. A weak reference says: "I know this data exists, but I am not claiming ownership. If everything else decides to drop it, don't wait for me."

Weak references don’t increment the strong count. They don’t keep data alive. And before you use a weak reference, you have to call .upgrade() on it, which returns an Option — because the data might have already been dropped.

The correct pattern for parent-child relationships is:

• Parent owns children → Rc<T> (strong reference)
• Child knows about parent → Weak<T> (weak reference, no ownership)

This way, when the parent is dropped, the strong count hits zero, and everything cleans up. The child’s weak reference to the parent simply returns None when upgraded.

Putting It All Together

Here’s a quick map of when to reach for each type:

You need…Use…Heap allocation, one ownerBox<T>Multiple owners, immutable accessRc<T>Single owner, interior mutabilityRefCell<T>Multiple owners, mutable accessRc<RefCell<T>>Non-owning reference (to prevent cycles)Weak<T>

Smart pointers are Rust’s way of giving you precise control over memory without making it your full-time job. Box<T> handles the common case. Rc<T> handles shared ownership. RefCell<T> handles the cases where the compiler can't statically reason about your borrowing patterns but you know — and can prove at runtime — that they're safe.

The compiler is always conservative. It would rather reject correct code than accept dangerous code. Smart pointers are the tools Rust gives you to say: “I understand the rules. I’ll enforce them myself.”

Coming from no prior programming experience, this chapter was a lot. But the more I sat with each type and really asked why does this exist, what problem did someone have before writing this, the clearer it got. The designs are not arbitrary. Every constraint, every limitation — the immutability of Rc, the runtime panics of RefCell, the non-ownership of Weak — is a deliberate, considered tradeoff.

That’s the thing about Rust. Once you stop fighting the rules and start asking why they exist, it starts to make a lot of sense.

Written as part of learning Rust from The Rust Programming Language book. First-time programmer trying to make sense of the heap, one smart pointer at a time.

Smart Pointers in Rust, A Beginner’s Perspective was originally published in Rust in Plain English on Medium, where people are continuing the conversation by highlighting and responding to this story.