Rajeev Edmonds — Blog

How Async Rust Works Under the Hood: Futures, Executors, and Pinning Explained

2026-10-06T00:00:00.000Z

Introduction

You write async fn, sprinkle in a few .await calls, and everything just works. Until it doesn't.

Then one day you hit an error like future cannot be sent between threads safely. Or you see Pin<Box<dyn Future<Output = ()>>> in a function signature and feel your confidence drain away. Or your whole server freezes because of one innocent-looking function call.

Most of the confusion around async Rust comes from one thing: it works very differently from async in languages like JavaScript, Go, or C#. There is no built-in runtime and no hidden scheduler. The language gives you a small set of building blocks, and the ecosystem builds everything else on top.

In this guide, we'll open the hood and look at those building blocks one by one: the Future trait, poll, wakers, executors, and the famously confusing Pin. We'll also write a tiny working executor from scratch. You can follow along with a plain cargo new project and no external crates.

By the end, you'll know what the compiler does with your async fn, why Pin exists, and how to avoid the most common production mistakes.

The Big Idea: Async Rust Is Lazy and Cooperative

Before the details, two ideas explain almost everything else.

Futures are lazy. Calling an async fn does not run any of its body. It returns a value (a future) that describes the work. Nothing happens until something polls that value.
Scheduling is cooperative. A task runs until it hits an .await that can't make progress, and only then does it give control back. Nobody forcibly interrupts it.

Compare this with OS threads, where the kernel can pause your code at any instruction. In async Rust, you decide where the pause points are, and they are your .awaits.

Note: If a task never reaches an .await, it never gives the thread back. That's the root cause of most "my async server froze" bugs. We'll come back to this.

What Is a Future, Really?

A future is any type that implements this trait from the standard library:

pub trait Future {
    type Output;

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

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

That's the whole thing. A future is something you can ask, "Are you done yet?" by calling poll. It answers in one of two ways:

Poll::Ready(value): finished, here's the result.
Poll::Pending: not done yet, ask me again later.

Notice that poll takes a Context. That's how a future says, "Don't keep asking me in a loop. I'll tell you when I'm ready." We'll get to that in the waker section.

Polling vs. Callbacks

Many languages use callbacks or promises that push results to you. Rust uses a poll-based model, where the executor pulls progress out of futures.

This has real benefits:

Zero-cost abstractions. Futures are plain structs. No heap allocation is required just to have a future.
No hidden runtime. You choose your executor, or write your own.
Easy cancellation. Dropping a future cancels it. There is no separate cancel token to wire up.
Backpressure. The consumer controls when work progresses.

What the Compiler Does With `async fn`

Here is a simple async function:

async fn greet() -> String {
    let name = fetch_name().await;
    format!("Hello, {name}")
}

The compiler turns this into an anonymous type that implements Future<Output = String>. Conceptually, it is a state machine, an enum with one variant per suspension point:

// Simplified. The real generated code is more involved.
enum GreetFuture {
    Start,
    WaitingForName { fetch: FetchNameFuture },
    Done,
}

Each time the executor calls poll:

The future resumes from its current state.
It runs until the next .await that returns Pending, or until it finishes.
It saves any local variables it still needs inside the state, then returns.

This is why async Rust is so efficient. All the locals that live across an .await are stored inside the future itself, in one struct. No separate stack is needed per task, as with threads or green threads.

A Practical Consequence: Future Size

Because the future stores everything that lives across an .await, large local values make large futures:

async fn heavy() {
    let buffer = [0u8; 64 * 1024]; // 64 KB lives inside the future
    do_something().await;
    println!("{}", buffer.len());
}

If you spawn thousands of tasks like this, memory adds up. Large buffers are better placed on the heap with Vec or Box.

Wakers: How a Future Says "Try Me Again"

If the executor just polled every future in a tight loop, you'd burn 100% CPU doing nothing. Wakers solve this.

When a future returns Pending, it must first arrange for someone to call wake() when progress becomes possible. The Waker lives inside the Context passed to poll.

The flow looks like this:

The executor polls your future with a Context containing a Waker.
The future tries to do work (say, read from a socket) and finds no data yet.
The future clones and stores the waker, then returns Pending.
Later, something external happens, such as the OS reporting that the socket is readable.
That event source calls waker.wake().
The executor puts the task back in its queue and polls it again.

The golden rule: Returning Pending without arranging a wake-up means your task may sleep forever. The compiler can't catch this, so it's one of the easiest bugs to write when implementing futures by hand.

Executors and Reactors: Who Actually Drives Everything?

People often use "runtime" loosely, but separate jobs are being done:

Component	Job	Real-world example
Executor	Holds tasks, polls them when woken, runs them on threads	Tokio's scheduler, smol's executor
Reactor	Watches for I/O and timer events, calls `wake()`	Tokio's I/O driver built on `mio` (epoll, kqueue, IOCP)
Futures	Describe the work and register wakers	Your `async fn`s, `TcpStream::read`, `sleep`

An executor is surprisingly simple at its core: a queue of tasks plus a loop. A reactor is the part that talks to the operating system.

Build a Tiny Executor From Scratch

Let's make this concrete. We'll build two things using only the standard library:

A future that completes after a delay.
A block_on function that runs a future to completion.

Step 1: A Hand-Written Future

use std::future::Future;
use std::pin::Pin;
use std::sync::{Arc, Mutex};
use std::task::{Context, Poll, Waker};
use std::thread;
use std::time::Duration;

struct Shared {
    done: bool,
    waker: Option<Waker>,
}

pub struct Delay {
    shared: Arc<Mutex<Shared>>,
}

impl Delay {
    pub fn new(dur: Duration) -> Self {
        let shared = Arc::new(Mutex::new(Shared { done: false, waker: None }));
        let thread_shared = shared.clone();

        // Stand-in for a reactor: a helper thread that "fires an event".
        thread::spawn(move || {
            thread::sleep(dur);
            let mut s = thread_shared.lock().unwrap();
            s.done = true;
            if let Some(w) = s.waker.take() {
                w.wake();
            }
        });

        Delay { shared }
    }
}

impl Future for Delay {
    type Output = ();

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
        let mut s = self.shared.lock().unwrap();
        if s.done {
            Poll::Ready(())
        } else {
            // Store the latest waker so the helper thread can wake us.
            s.waker = Some(cx.waker().clone());
            Poll::Pending
        }
    }
}

Two details are worth noticing:

We overwrite the stored waker on every poll. The executor may hand us a different waker each time, and the most recent one is the one that counts.
The waker is called after we set done = true. Setting the flag first avoids a race where the future is polled and sees stale state.

Step 2: A Minimal `block_on`

use std::pin::pin;
use std::sync::Arc;
use std::task::Wake;
use std::thread::Thread;

struct ThreadWaker(Thread);

impl Wake for ThreadWaker {
    fn wake(self: Arc<Self>) {
        self.0.unpark();
    }
}

fn block_on<F: Future>(fut: F) -> F::Output {
    let mut fut = pin!(fut);
    let waker: Waker = Arc::new(ThreadWaker(thread::current())).into();
    let mut cx = Context::from_waker(&waker);

    loop {
        match fut.as_mut().poll(&mut cx) {
            Poll::Ready(value) => return value,
            Poll::Pending => thread::park(), // sleep until woken
        }
    }
}

Step 3: Run It

fn main() {
    block_on(async {
        println!("start");
        Delay::new(Duration::from_secs(1)).await;
        println!("one second later");
    });
}

Run cargo run and you'll see the two messages one second apart. The main thread sleeps in park() during the wait and uses almost no CPU.

This is the same pattern real runtimes follow. They just add task queues, many threads, and a proper reactor. A runtime like Tokio is this idea, scaled up and polished.

Why Does Pin Exist?

Now the part everyone dreads. Let's make it simple.

The Problem: Self-Referential Futures

Look at this function:

async fn example() {
    let data = [1, 2, 3];
    let r = &data;      // a reference to a local
    something().await;  // suspension point
    println!("{:?}", r);
}

The reference r points to data. Both live inside the generated future, across the .await. So the future contains a pointer to itself.

Now imagine the future is moved to a different memory address, perhaps by passing it into a function or pushing it into a Vec. The bytes get copied, but r still holds the old address. That is a dangling pointer, which means undefined behavior.

Normally Rust's borrow checker prevents this kind of thing. But for compiler-generated state machines, it can't express "this struct borrows from itself." The solution is to make sure the future never moves once it has started being polled.

The Solution: `Pin`

Pin<P> wraps a pointer type like &mut T or Box<T>. It promises that the value pointed to will not be moved until it's dropped, unless the type opts out.

That's why poll takes self: Pin<&mut Self> and not &mut self. A plain &mut would let you do std::mem::swap and move the future. A pinned reference won't.

Unpin: The Escape Hatch

Most types don't care about being moved. u32, String, and Vec<T> are all fine. These types automatically implement the marker trait Unpin, and for them pinning is a no-op.

Futures generated by async blocks are typically !Unpin. That is what makes pinning matter for them.

Here is a summary of the common ways to pin something:

Method	Where it lives	Notes
`Box::pin(fut)`	Heap	Safest and simplest. Costs one allocation.
`std::pin::pin!(fut)`	Stack (current scope)	No allocation. Stable since Rust 1.68.
`Pin::new(&mut fut)`	Wherever it is	Only works if `fut: Unpin`.
`Pin::new_unchecked`	Wherever it is	`unsafe`. You take responsibility for never moving it.

When You'll Actually Meet Pin in Daily Code

Storing futures in collections. You can't put different async blocks in a Vec directly, since each has a unique type. Use Vec<Pin<Box<dyn Future<Output = T>>>>.
Using select!. Futures reused across loop iterations often need pin!.
Recursion. An async function that calls itself needs boxing, because the future would otherwise have infinite size:

use std::future::Future;
use std::pin::Pin;

fn countdown(n: u32) -> Pin<Box<dyn Future<Output = ()>>> {
    Box::pin(async move {
        if n > 0 {
            println!("{n}");
            countdown(n - 1).await;
        }
    })
}

Tip: If Pin errors confuse you, the fix is usually Box::pin(...) or pin!(...). Reach for those first. You rarely need unsafe.

How Tokio Schedules Your Tasks

Let's connect all of this to the runtime most people use. When you write:

#[tokio::main]
async fn main() {
    let handle = tokio::spawn(async {
        // some work
        42
    });

    let result = handle.await.unwrap();
    println!("{result}");
}

tokio::spawn wraps your future in a task and hands it to the scheduler. By default, Tokio uses a multi-threaded work-stealing scheduler: one worker thread per CPU core, each with its own queue. If a worker runs out of tasks, it steals from another.

Because your task might be resumed on a different thread after an .await, the future must be Send. That's the origin of the dreaded error:

error: future cannot be sent between threads safely

It usually means something non-Send (like an Rc, or a std::sync::MutexGuard) is held across an .await.

If you don't need multiple threads, Tokio also offers a single-threaded flavor:

#[tokio::main(flavor = "current_thread")]
async fn main() { /* ... */ }

Choosing a Runtime

Runtime	Best for	Character
Tokio	Servers, networking, most production apps	Largest ecosystem, work-stealing, feature-rich
smol	Smaller apps and libraries	Lightweight and minimal
Embassy	Embedded, `no_std`	Async on microcontrollers, no heap needed

Common Async Rust Pitfalls (and How to Fix Them)

1. Blocking the Executor

This is the number one mistake.

async fn bad() {
    std::thread::sleep(std::time::Duration::from_secs(5)); // blocks the worker thread!
}

While that thread sleeps, every task scheduled on it is stuck. Use the async version:

async fn good() {
    tokio::time::sleep(std::time::Duration::from_secs(5)).await;
}

For CPU-heavy or genuinely blocking work (file parsing, hashing, a sync library), move it off the async workers:

let result = tokio::task::spawn_blocking(|| expensive_computation()).await?;

2. Holding a Lock Across `.await`

// Risky: std::sync::MutexGuard held over an await point
let guard = data.lock().unwrap();
do_io().await;
println!("{}", *guard);

This can cause deadlocks and Send errors. Prefer to drop the guard before awaiting:

let value = {
    let guard = data.lock().unwrap();
    guard.clone()
}; // guard dropped here
do_io().await;

If you truly need to hold a lock across an await, use tokio::sync::Mutex.

3. Forgetting to `.await`

Because futures are lazy, this does nothing:

async fn run() {
    save_to_db(); // never runs; just creates a future
}

The compiler warns with unused_must_use. Treat that warning as an error.

4. Cancellation Surprises

Dropping a future cancels it at its last .await. That's powerful, but with tokio::select! a losing branch is simply dropped, and any partial work in it is lost. If an operation isn't cancel-safe, such as a read that has consumed some bytes into a temporary buffer, you can lose data. Always check the docs for cancel-safety notes on the functions you use inside select!.

5. Accidentally Sequential Code

let a = fetch_a().await;
let b = fetch_b().await; // starts only after a finishes

If the two are independent, run them concurrently:

let (a, b) = tokio::join!(fetch_a(), fetch_b());

Best Practices Checklist

Keep the time between .awaits short. Long synchronous stretches starve other tasks.
Use spawn_blocking for blocking or CPU-heavy work.
Don't hold std mutex guards across .await.
Prefer join! for independent operations.
Use bounded channels so slow consumers apply backpressure.
Avoid large stack arrays in async functions. Box them.
Check cancel-safety before using futures inside select!.
If you're writing a library, avoid tying users to one runtime when you can.

Conclusion

Async Rust looks mysterious mainly because the machinery is exposed rather than hidden. Once you see the pieces, they fit together neatly:

An async fn becomes a state machine that implements Future.
Executors poll futures, and futures return Ready or Pending.
A Pending future stores a waker, and the reactor calls it when progress is possible.
Pin exists so self-referential state machines never move in memory.
Cooperative scheduling means you must never block a worker thread.

A good next step is to take the Delay and block_on code above and extend it. Add a task queue so block_on can run several futures, then compare your version with Tokio's source. Building even a toy executor will teach you more than reading a dozen articles.

Make Your Rust CLI Pipe-Friendly: stdin, stdout and Broken Pipes

2026-09-28T00:00:00.000Z

The best command-line tools compose. They read from a file or from a pipe, and they behave when their output is piped into something else. Getting that right in Rust takes only a few lines, but there's one classic trap: the broken pipe.

Read from a file or stdin

Here's a small tool, shout, that uppercases its input. With a path argument it reads that file; without one it reads stdin.

use std::fs::File;
use std::io::{self, BufRead, BufReader, BufWriter, IsTerminal, Write};

fn run() -> io::Result<()> {
    let path = std::env::args().nth(1);

    let reader: Box<dyn BufRead> = match path {
        Some(p) => Box::new(BufReader::new(File::open(p)?)),
        None if io::stdin().is_terminal() => {
            eprintln!("usage: shout <file>  (or pipe text into stdin)");
            std::process::exit(2);
        }
        None => Box::new(io::stdin().lock()),
    };

    let mut out = BufWriter::new(io::stdout().lock());

    for line in reader.lines() {
        writeln!(out, "{}", line?.to_uppercase())?;
    }

    out.flush()
}

A few details are worth knowing:

Box<dyn BufRead> lets both branches share one loop, whether the source is a file or stdin.
IsTerminal (stable since Rust 1.70) tells you whether stdin is an interactive terminal. Without that check, running shout with no arguments would sit there silently waiting for input, which looks like a hang.
stdout is line-buffered, so wrapping it in a BufWriter cuts down on system calls when you print many lines.

The broken pipe trap

Now try shout big.log | head -n 3. head prints three lines and exits, closing the pipe, and your next write fails. Rust's runtime ignores SIGPIPE, so instead of being killed silently like a typical Unix tool, your program gets a BrokenPipe error. With println!, that error becomes a panic. With writeln! and ?, it bubbles up as an Err.

That Err isn't a real failure. The reader simply got what it needed. So treat it as a normal exit in main:

fn main() {
    if let Err(e) = run() {
        if e.kind() == io::ErrorKind::BrokenPipe {
            return; // downstream (e.g. `head`) closed the pipe, which is fine
        }
        eprintln!("shout: {e}");
        std::process::exit(1);
    }
}

Now the tool works in all three modes:

shout notes.txt
printf 'hello\nworld\n' | shout
shout big.log | head -n 3

Reading from stdin, writing through a buffer, and treating BrokenPipe as a clean exit are three small habits that make a tool feel native on the command line.

How to Integrate Assembly and C Code in Your Rust Projects (The Practical Guide)

2026-09-28T00:00:00.000Z

Introduction

Rust is great, but it doesn't live in a vacuum. Sooner or later, you'll hit a moment where you need to talk to code that isn't Rust.

Maybe your company has a battle-tested C library that nobody wants to rewrite. Maybe you're working with a hardware SDK that ships only a C header. Or maybe you've found a hot loop where a few hand-written instructions beat what the compiler generates.

So how do you bring C and assembly into a Rust project without turning your build into a mess? And how do you keep Rust's safety guarantees from falling apart at the boundary?

This guide answers both questions. We'll cover the main ways to mix these languages, build a working example step by step, and go through the mistakes that cause most FFI crashes. I'll assume you know basic Rust, but I'll explain the low-level parts as we go.

Note: All examples target x86_64 Linux, since that's where most people start. I'll flag where macOS, Windows, or ARM need changes.

Why Mix Rust With C and Assembly?

Before writing any code, it helps to know when this is actually worth doing.

Good reasons:

Reusing existing C libraries. OpenSSL, SQLite, zlib, and libcurl represent decades of work. Wrapping them is often smarter than rewriting them.
Talking to operating systems and hardware. Many drivers, SDKs, and system APIs expose C interfaces.
Gradual migration. You can move a C codebase to Rust one module at a time instead of in a risky big-bang rewrite.
Squeezing out performance. Some CPU instructions have no clean Rust equivalent, such as special vector instructions, cycle counters, or system-specific tricks.
Learning. Writing assembly for a Rust function teaches you a lot about how calling conventions really work.

Bad reasons:

"C is always faster." It isn't. Rust and C compile down to similar machine code, and LLVM optimizes both well.
"Hand-written assembly beats the compiler." It rarely does for general code. Always benchmark first.

The Big Picture: Ways to Integrate

Here are the main approaches you'll use:

Approach	Best For	Where the Code Lives	Difficulty
FFI with `extern "C"`	Calling C functions from Rust	Separate `.c` files or a system library	Easy
`build.rs` + `cc` crate	Compiling C or `.S` files as part of `cargo build`	Inside your project	Easy to medium
Inline `asm!` / `global_asm!`	Small snippets of assembly	Inside your Rust source	Medium
`bindgen` / `cbindgen`	Auto-generating bindings in either direction	Generated at build time	Medium
Standalone `.s`/`.S` files	Larger assembly routines	Separate assembly files	Advanced

All of these rely on one idea: the C ABI. It's the agreed-upon convention for how functions receive arguments and return values. Rust, C, and assembly can all speak it, and that shared language is what makes mixing them possible.

Understanding FFI in Rust

FFI stands for Foreign Function Interface. In Rust, it comes down to two things:

Declaring foreign functions inside an extern "C" block.
Calling them inside unsafe, because Rust can't verify what happens on the other side.

unsafe extern "C" {
    fn abs(input: i32) -> i32;
}

fn main() {
    let x = unsafe { abs(-42) };
    println!("{x}");
}

That works because the C standard library is already linked into every Rust program on most platforms.

A quick syntax note: Since Rust 1.82, you can write unsafe extern "C" { ... }, and it's required in the 2024 edition. Older code uses plain extern "C" { ... }. Both mean the same thing. The newer form lets you mark individual items as safe or unsafe.

Why `unsafe`?

The Rust compiler has no idea what a C function does. It can't check that pointers are valid, that lengths are correct, or that the function won't write past the end of a buffer. So you're making a promise: "I've checked this, and it's fine."

The best practice is to keep that promise in one place. Wrap each unsafe call in a small safe function, and let the rest of your program use the safe version. We'll do exactly that below.

Mapping Types Between Rust and C

Getting types wrong is the number one source of subtle FFI bugs. Here are the common mappings:

C Type	Rust Type	Notes
`int`	`std::ffi::c_int`	Don't assume it's `i32` on every platform
`unsigned int`	`c_uint`
`long`	`c_long`	32-bit on Windows, 64-bit on 64-bit Linux
`size_t`	`usize`
`uint8_t`, `uint32_t`	`u8`, `u32`	Fixed-width types map cleanly
`char *` (string)	`*const c_char`	Use `CStr`/`CString` to convert
`void *`	`*mut c_void`
`const T *`	`*const T`
`T *`	`*mut T`
`struct`	`#[repr(C)] struct`	Without `repr(C)`, layout is not guaranteed
function pointer	`Option<extern "C" fn(...)>`	`Option` allows null

Two rules to remember:

Always use #[repr(C)] on structs you share with C. Rust is free to reorder fields in normal structs, and C won't expect that.
Prefer fixed-width types (u32, i64) in your own C code when you control both sides. It removes a whole class of "works on my machine" problems.

Step-by-Step: Adding C and Assembly to a Rust Project

Let's build something real. Our small project will:

Call a C function that computes a checksum.
Call an assembly function that adds two numbers.
Compile both automatically with cargo build.

Step 1: Create the Project

cargo new rust-ffi-demo
cd rust-ffi-demo
mkdir csrc asm

Your layout will end up like this:

rust-ffi-demo/
├── Cargo.toml
├── build.rs
├── csrc/
│   ├── checksum.c
│   └── checksum.h
├── asm/
│   └── add.S
└── src/
    └── main.rs

Step 2: Write the C Code

csrc/checksum.h

#ifndef CHECKSUM_H
#define CHECKSUM_H

#include <stddef.h>
#include <stdint.h>

uint32_t simple_checksum(const uint8_t *data, size_t len);

#endif

csrc/checksum.c

#include "checksum.h"

uint32_t simple_checksum(const uint8_t *data, size_t len) {
    uint32_t sum = 0;
    for (size_t i = 0; i < len; i++) {
        // rotate left by 1, then XOR in the next byte
        sum = (sum << 1) | (sum >> 31);
        sum ^= data[i];
    }
    return sum;
}

Nothing fancy. It's a small function that's easy to verify by hand.

Step 3: Write the Assembly Code

We'll use a .S file (capital S). That capital matters: it tells the compiler to run the C preprocessor first, and it's the file type the cc crate handles well.

asm/add.S

    .intel_syntax noprefix
    .text
    .globl add_asm
    .type add_asm, @function

add_asm:
    lea rax, [rdi + rsi]
    ret

    .size add_asm, .-add_asm
    .section .note.GNU-stack,"",@progbits

What's happening here?

On x86_64 Linux (the System V ABI), the first two integer arguments arrive in rdi and rsi.
The return value goes in rax.
lea rax, [rdi + rsi] computes the sum without touching the flags register. It's a common trick.
The .note.GNU-stack line tells the linker your code doesn't need an executable stack. Without it, newer linkers may warn.

Heads up for other platforms: On macOS, C symbols get a leading underscore (_add_asm), and Windows uses a different calling convention entirely. ARM64 uses different registers (x0, x1) and different syntax. Assembly is not portable, and that's normal.

Step 4: Compile Everything With `build.rs`

Add the cc crate as a build dependency:

Cargo.toml

[package]
name = "rust-ffi-demo"
version = "0.1.0"
edition = "2024"

[build-dependencies]
cc = "1"

Now create build.rs in the project root. Cargo runs this before compiling your main crate.

fn main() {
    // Compile the C library
    cc::Build::new()
        .file("csrc/checksum.c")
        .include("csrc")
        .opt_level(2)
        .warnings(true)
        .compile("checksum");

    // Compile assembly only where it makes sense
    let arch = std::env::var("CARGO_CFG_TARGET_ARCH").unwrap();
    let os = std::env::var("CARGO_CFG_TARGET_OS").unwrap();

    if arch == "x86_64" && os == "linux" {
        cc::Build::new()
            .file("asm/add.S")
            .compile("addasm");
    }

    // Only re-run this script when these files change
    println!("cargo:rerun-if-changed=csrc/checksum.c");
    println!("cargo:rerun-if-changed=csrc/checksum.h");
    println!("cargo:rerun-if-changed=asm/add.S");
}

Notice we check the target architecture using CARGO_CFG_TARGET_ARCH, not cfg!(target_arch). Inside build.rs, cfg! describes the machine running the build script, not the machine you're compiling for. It makes no difference in a normal build, but it breaks silently when you cross-compile.

The cc crate finds a C compiler (gcc, clang, or MSVC), compiles your files into a static library, and tells Cargo to link it. You don't need to write any linker flags yourself.

Step 5: Call Everything From Rust

src/main.rs

unsafe extern "C" {
    fn simple_checksum(data: *const u8, len: usize) -> u32;

    #[cfg(all(target_arch = "x86_64", target_os = "linux"))]
    fn add_asm(a: i64, b: i64) -> i64;
}

/// Safe wrapper around the C checksum function.
pub fn checksum(data: &[u8]) -> u32 {
    // SAFETY: the pointer and length come from a valid slice,
    // and the C function only reads `len` bytes.
    unsafe { simple_checksum(data.as_ptr(), data.len()) }
}

#[cfg(all(target_arch = "x86_64", target_os = "linux"))]
pub fn add(a: i64, b: i64) -> i64 {
    // SAFETY: add_asm is a pure function with no memory access.
    unsafe { add_asm(a, b) }
}

fn main() {
    let msg = b"hello from Rust";
    println!("checksum = {:#010x}", checksum(msg));

    #[cfg(all(target_arch = "x86_64", target_os = "linux"))]
    println!("2 + 40 = {}", add(2, 40));
}

Run it:

cargo run

You should see the checksum printed, followed by 2 + 40 = 42. That's the whole loop: write C or assembly, describe it in an extern block, wrap it safely, and let Cargo build it all.

Pro tip: Put the extern block and the safe wrappers in their own module, such as ffi.rs. The rest of your codebase should never see the word unsafe.

Using Inline Assembly Directly in Rust

You don't always need a separate file. For short snippets, Rust has built-in support through the asm! macro, which has been stable since Rust 1.59.

use std::arch::asm;

#[cfg(target_arch = "x86_64")]
fn add_inline(a: u64, b: u64) -> u64 {
    let mut result = a;
    unsafe {
        asm!(
            "add {0}, {1}",
            inout(reg) result,
            in(reg) b,
            options(pure, nomem, nostack),
        );
    }
    result
}

Let's break that down:

{0} and {1} are placeholders. Rust picks the actual registers for you, which is much safer than hard-coding them.
inout(reg) result means "this value goes in and comes back out."
in(reg) b means "read-only input."
options(pure, nomem, nostack) are promises to the compiler: no side effects, no memory access, no stack use. These let it optimize aggressively, so only add them if they're true. If you lie, you get bugs that are very hard to trace.

Inline `asm!` vs. Separate `.S` Files

	Inline `asm!`	Separate `.S` file
Register allocation	Compiler handles it	You handle it
Inlining	Can be inlined into callers	Always a real function call
Setup	None	Needs `build.rs`
Best for	A few instructions	Whole functions or routines
Syntax	Intel by default on x86	Whatever your assembler accepts

Two More Tools Worth Knowing

global_asm! lets you emit a whole block of assembly at module level, which is handy for defining entire functions without a build script.
Naked functions give you full control over a function's prologue and epilogue. They were stabilized in Rust 1.88 using #[unsafe(naked)] and naked_asm!. Check your compiler version before relying on them.

Generating Bindings Automatically With bindgen

Hand-writing extern blocks is fine for three functions. For a library with three hundred, it's a recipe for typos.

That's where bindgen comes in. It reads your C header and generates the Rust declarations for you.

Cargo.toml

[build-dependencies]
cc = "1"
bindgen = "0.71"   # check crates.io for the latest version

csrc/wrapper.h

#include "checksum.h"

build.rs (bindgen part)

use std::{env, path::PathBuf};

fn main() {
    // ... cc::Build code from before ...

    let bindings = bindgen::Builder::default()
        .header("csrc/wrapper.h")
        .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))
        .generate()
        .expect("failed to generate bindings");

    let out = PathBuf::from(env::var("OUT_DIR").unwrap());
    bindings
        .write_to_file(out.join("bindings.rs"))
        .expect("failed to write bindings");
}

src/ffi.rs

#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
#![allow(dead_code)]

include!(concat!(env!("OUT_DIR"), "/bindings.rs"));

A few things to know about bindgen:

It needs libclang installed on your machine. On Ubuntu or Debian, that's sudo apt install libclang-dev.
The generated code is raw and unsafe. You still need to write safe wrappers on top.
For very large libraries, commit the generated file to your repo so contributors don't all need libclang.

Going the Other Way: Calling Rust From C

Integration works in both directions. If you're migrating a C project to Rust, you'll want C code to call your new Rust functions.

#[unsafe(no_mangle)]
pub extern "C" fn rust_multiply(a: i32, b: i32) -> i32 {
    a * b
}

extern "C" gives the function the C calling convention.
#[unsafe(no_mangle)] stops Rust from renaming the symbol, so C can find it. On editions before 2024, write it as plain #[no_mangle].

To make C happy, you also need a header. Instead of writing it by hand, use cbindgen, which reads your Rust code and generates a .h file.

cargo install cbindgen
cbindgen --lang c --output rust_api.h

To build a library that C can link against, set the crate type in Cargo.toml:

[lib]
crate-type = ["staticlib"]   # or "cdylib" for a shared library

The Panic Problem

What happens if Rust code panics while being called from C? Historically, unwinding across an extern "C" boundary was undefined behavior. Modern Rust makes extern "C" functions abort the process if a panic tries to escape. That's safer than undefined behavior, but it still kills your program.

The fix is to catch panics at the boundary:

use std::panic::catch_unwind;

#[unsafe(no_mangle)]
pub extern "C" fn rust_safe_divide(a: i32, b: i32) -> i32 {
    catch_unwind(|| a / b).unwrap_or(-1)
}

Return an error code instead of letting a panic escape. C programmers already expect that style.

Handling Strings, Memory, and Ownership

This is where most real-world FFI bugs live. The rule of thumb is simple: whoever allocates the memory must free it.

Passing Strings to C

Rust strings aren't null-terminated. C strings are. Use CString:

use std::ffi::{CString, c_char};

unsafe extern "C" {
    fn puts(s: *const c_char) -> i32;
}

fn main() {
    let s = CString::new("hello from Rust").expect("no interior null bytes");
    unsafe { puts(s.as_ptr()); }
}

Keep s alive for as long as C uses the pointer. A classic mistake is writing CString::new("hi").unwrap().as_ptr(), which drops the CString immediately and hands C a dangling pointer.

Reading Strings From C

use std::ffi::{CStr, c_char};

unsafe fn read_c_string(ptr: *const c_char) -> String {
    unsafe { CStr::from_ptr(ptr) }.to_string_lossy().into_owned()
}

Memory Ownership Rules

Memory allocated by C (with malloc) must be freed by C (free). Never pass it to Rust's allocator.
Memory allocated by Rust (like a Box or Vec) must be freed by Rust. If you hand it to C, give C a matching free_thing() function to call back.
Borrowed pointers should never be stored by C beyond the call unless you've guaranteed the data lives long enough.

Real-World Use Cases

Here's where this kind of integration shows up in practice:

Wrapping system libraries such as libc, libpcap, or libusb, which is how many *-sys crates work.
Embedded and OS development, where startup code and interrupt handlers are often small assembly routines.
Cryptography, where libraries pair a Rust API with hand-tuned assembly for hot loops.
CLI and developer tools, where you might reuse an existing C parser or compression library instead of reimplementing it.
Performance experiments, where you replace one function with an assembly version and benchmark the difference.

Best Practices

Isolate unsafe. Keep FFI declarations in one module and expose only safe functions.
Document every unsafe block with a // SAFETY: comment explaining why it's sound.
Use #[repr(C)] on every shared struct.
Never let panics cross the boundary. Catch them and return error codes.
Check for null pointers before dereferencing anything that came from C.
Benchmark before writing assembly. Use cargo bench or Criterion, and compare against plain Rust first.
Gate platform-specific code with cfg attributes and always provide a portable fallback.
Test under sanitizers. Tools like Valgrind and AddressSanitizer catch memory errors that Rust can't see across FFI.
Add rerun-if-changed lines so build.rs doesn't recompile everything on every build.
Consider a -sys crate if you're wrapping a library others might use. Keep raw bindings in foo-sys and the safe API in foo.

Conclusion

Mixing Rust with C and assembly sounds intimidating, but the workflow is quite consistent once you've seen it. Declare the foreign functions, compile the foreign code through build.rs and the cc crate, wrap the unsafe parts in safe functions, and test carefully.

Here are the takeaways worth remembering:

Use cc to compile C and .S files during cargo build.
Use bindgen for big headers and cbindgen when C needs to call Rust.
Match types carefully and add #[repr(C)] to shared structs.
Keep unsafe in one small module and document why it's sound.
Never let panics cross the boundary, and always follow the "whoever allocates, frees" rule.
Reach for assembly only after a benchmark tells you to.

Start small. Wrap one C function, get it running, then grow from there. Once that first cargo run prints the right answer, the rest is repetition.

Friendly Errors in a Rust CLI with anyhow

2026-09-22T00:00:00.000Z

The default failure message from a lot of Rust code is technically correct and completely unhelpful: No such file or directory (os error 2). Which file? Doing what? In a command-line tool, the error message is the user interface, so it's worth a few extra lines.

The anyhow crate is built for exactly this in application code. It gives you one catch-all Result type, and a way to attach context as an error travels up the call stack.

cargo add anyhow

Add context at each step

use std::fs;

use anyhow::{bail, Context, Result};

fn read_port(path: &str) -> Result<u16> {
    let text = fs::read_to_string(path)
        .with_context(|| format!("could not read config file `{path}`"))?;

    let port: u16 = text
        .trim()
        .parse()
        .with_context(|| format!("`{path}` does not contain a valid port number"))?;

    if port < 1024 {
        bail!("port {port} is reserved; choose 1024 or higher");
    }

    Ok(port)
}

fn main() -> Result<()> {
    let port = read_port("port.txt")?;
    println!("listening on port {port}");
    Ok(())
}

Three pieces do the work:

anyhow::Result<T> is shorthand for Result<T, anyhow::Error>. Any error type that implements std::error::Error converts into it automatically, so the ? operator just works.
.with_context(|| ...) wraps the original error with your message. The closure form only builds the string if there actually was an error.
bail! returns early with a brand-new error, for problems that aren't wrapping anything, like the range check above.

What the user sees

Returning Result from main means Rust prints the error and exits with status 1. If port.txt is missing:

Error: could not read config file `port.txt`

Caused by:
    No such file or directory (os error 2)

And if the file contains abc:

Error: `port.txt` does not contain a valid port number

Caused by:
    invalid digit found in string

Your message comes first and the underlying cause follows. Nothing was lost, and the user now knows what to fix.

A note on where to use it

anyhow is a great fit for binaries, where you mostly want to report an error and exit. If you're writing a library, callers often need to match on specific failures. That's where a typed error, usually derived with the thiserror crate, is the better tool. Many projects use both: thiserror inside the library, anyhow in the main.rs that calls it.

Parsing CLI Arguments in Rust with clap's Derive API

2026-09-15T00:00:00.000Z

Every command-line tool starts the same way: it needs to read some arguments. You can loop over std::env::args() by hand, but you'll be rewriting help text, validation and error messages within the hour. The clap crate handles all of that, and its derive API lets you describe your whole CLI as a plain struct.

Set it up

cargo new linecount
cd linecount
cargo add clap --features derive

Describe the arguments as a struct

use std::path::PathBuf;

use clap::Parser;

/// A tiny example CLI
#[derive(Parser, Debug)]
#[command(version)]
struct Cli {
    /// File to read
    path: PathBuf,

    /// Print extra detail
    #[arg(short, long)]
    verbose: bool,

    /// Stop after this many lines
    #[arg(short = 'n', long, default_value_t = 1000)]
    limit: usize,
}

fn main() {
    let cli = Cli::parse();

    if cli.verbose {
        eprintln!("verbose mode on");
    }
    println!("would read up to {} lines from {}", cli.limit, cli.path.display());
}

That's the whole parser. A few things are happening here:

A field with no attribute (path) becomes a required positional argument.
A bool field becomes a flag. short and long give you -v and --verbose.
The field's type is the validation. Pass --limit abc and clap rejects it with a clear error, because abc isn't a usize.
Doc comments (///) become the help text, so your documentation and your --help never drift apart.

Try it

cargo run -- --help now prints something like this, with no extra code:

A tiny example CLI

Usage: linecount [OPTIONS] 

Arguments:
    File to read

Options:
  -v, --verbose        Print extra detail
  -n, --limit   Stop after this many lines [default: 1000]
  -h, --help           Print help
  -V, --version        Print version

Cli::parse() also handles the failure path for you: on bad input it prints the error and exits with status 2, the conventional code for a usage error. If you'd rather handle that yourself, Cli::try_parse() returns a Result instead.

From here, the natural next steps are subcommands (put #[derive(Subcommand)] on an enum) and value validation with value_parser. Both are just more attributes on the same struct.

Rajeev Edmonds — Blog

How Async Rust Works Under the Hood: Futures, Executors, and Pinning Explained

Introduction

The Big Idea: Async Rust Is Lazy and Cooperative

What Is a Future, Really?

Polling vs. Callbacks

What the Compiler Does With async fn

A Practical Consequence: Future Size

Wakers: How a Future Says "Try Me Again"

Executors and Reactors: Who Actually Drives Everything?

Build a Tiny Executor From Scratch

Step 1: A Hand-Written Future

Step 2: A Minimal block_on

Step 3: Run It

Why Does Pin Exist?

The Problem: Self-Referential Futures

The Solution: Pin

Unpin: The Escape Hatch

When You'll Actually Meet Pin in Daily Code

How Tokio Schedules Your Tasks

Choosing a Runtime

Common Async Rust Pitfalls (and How to Fix Them)

1. Blocking the Executor

2. Holding a Lock Across .await

3. Forgetting to .await

4. Cancellation Surprises

5. Accidentally Sequential Code

Best Practices Checklist

Conclusion

Make Your Rust CLI Pipe-Friendly: stdin, stdout and Broken Pipes

Read from a file or stdin

The broken pipe trap

How to Integrate Assembly and C Code in Your Rust Projects (The Practical Guide)

Introduction

Why Mix Rust With C and Assembly?

The Big Picture: Ways to Integrate

Understanding FFI in Rust

Why unsafe?

Mapping Types Between Rust and C

Step-by-Step: Adding C and Assembly to a Rust Project

Step 1: Create the Project

Step 2: Write the C Code

Step 3: Write the Assembly Code

Step 4: Compile Everything With build.rs

Step 5: Call Everything From Rust

Using Inline Assembly Directly in Rust

Inline asm! vs. Separate .S Files

Two More Tools Worth Knowing

Generating Bindings Automatically With bindgen

Going the Other Way: Calling Rust From C

The Panic Problem

Handling Strings, Memory, and Ownership

Passing Strings to C

Reading Strings From C

Memory Ownership Rules

Real-World Use Cases

Best Practices

Conclusion

Friendly Errors in a Rust CLI with anyhow

Add context at each step

What the user sees

A note on where to use it

Parsing CLI Arguments in Rust with clap's Derive API

Set it up

Describe the arguments as a struct

Try it

What the Compiler Does With `async fn`

Step 2: A Minimal `block_on`

The Solution: `Pin`

2. Holding a Lock Across `.await`

3. Forgetting to `.await`

Why `unsafe`?

Step 4: Compile Everything With `build.rs`

Inline `asm!` vs. Separate `.S` Files