I had no idea how to evaluate this claim. A quick search online returned results favoring parking_lot. This felt wrong to me. Why? It contradicted my belief that std should be the gold standard. The standard library team knows what they’re doing, right? And if parking_lot’s mutex really was the performance winner, there had to be trade-offs between the two implementations that people weren’t talking about.

That mystery haunted me. I couldn’t just take it on faith. So I jumped down the rabbit hole: read both implementations, wrote the benchmarks, and here we are. In this post, I will:

• Explain how std implements the mutex (v1.90.0)

• Explain how parking_lot implements their mutex (v0.12.5)

• Show you the benchmark with key findings

• Give you a decision guide for when to use each

But first, let’s ground our foundation on mutexes (skim it if you’re already familiar).

What Is a Mutex, Really?

A classic example of the kind of problem that mutex solves is withdrawing and receiving money at the same time. Imagine you have $100 in your account. Thread A tries to withdraw $80, and Thread B tries to deposit $50. Without proper synchronization, both threads might read the balance as $100 simultaneously, then write back their results independently:

Mutex solves this nicely by having a thread wait until the other finishes its update:

The operations that read and write the balance are what we need to protect - these are called critical sections. Any code that accesses shared data needs to be inside a critical section, guarded by a mutex.

Simple enough, right? Now let’s see how to use a mutex. (Again, skim this if it’s too basic for you)

How to use mutex

In languages other than Rust, you typically declare a mutex separately from your data, then manually lock it before entering the critical section and unlock it afterward. Here’s how it looks in C++:

The problem? Nothing stops you from accessing account without locking the mutex first. The compiler won’t catch this bug.

Rust takes a completely different approach - the mutex wraps and owns the data:

Three things to pay close attention to:

• The mutex wraps the data: This makes it impossible to access account without holding the lock. The compiler enforces this.

• Automatic unlock: When you lock, you receive a guard. When the guard goes out of scope, it automatically unlocks. No manual cleanup needed.

• Lock can fail: Notice the .unwrap() on .lock()? It returns a Result because locking can fail due to poisoning. I’ll explain this shortly.

That’s enough of the basics. Let’s have some fun. Here is how mutex is implemented, starting with Rust std.

How Rust’s std::Mutex Works

Overview

A quick look into std::Mutex gives us this

• data is the easy part. Since the mutex enforces exclusive access, Rust uses UnsafeCell to give you safe mutable access once it’s locked.

• poison is just Atomic<bool> flag to tell if the last thread acquired the lock panic. So, maybe you would want to handle it next time you lock it.

inner is interesting part, let’s look at it next. The code is really long, so I just show a simplified version here

The main idea is that for different OS (and OS version), Rust uses different Mutex implementation. However, we can divide these implementation to 2 big groups: Futex and other platform primitive.

• Futex (short for “fast userspace mutex”) is used where the OS kernels expose a “wait on this address” API. We will dive deeper into this one soon.

• When that API is missing, Rust falls back to the best available platform traditional locks.

(I’m in awe btw - that’s a lot of different implementations. Writing and maintaining all this platform-specific stuff must be exhausting. Major respect to whoever’s doing this.)

Since Futex is the most used and is quite a typical implementation for Mutex. Let’s look inside it.

Futex

At its heart, futex is just an atomic u32 (simplified here):

Atomic type has this powerful operation called “Compare And Swap” (CAS) where the CPU executes it in an atomic call. It works by first comparing the value, if the value equals what is asked for, then it sets the value.

In other words, if we use value 0 for Unlocked state, and 1 for Locked state, we have a simple mutex where the thread can simply try to compare the state to 0 (Unlocked), and set to 1 (Locked). If the state is currently 1, keep doing that until successful.

So, a simplified version of mutex look like this:

But you might ask: if the first thread holds the lock for a long time, then the second thread needs to keep trying (like a infinite loop)? How about if there are hundreds or thousands of them? Maybe the CPU will soon be burnt.

Of course, there is the solution to this problem. In real implementation, Rust futex has 3 states:

• 0: Unlocked

• 1: Locked

• 2: Contended - locked, but there are waiter.

Notice the Contended state? A thread will try its best to acquire the lock. But if it can’t, it will mark the lock as contended and go to sleep, waiting for the process to wake it up when the mutex is released.

Note: See that spinning part in the diagram? Before a thread goes to sleep, it keeps checking the lock state for about 100 loops - if it becomes unlocked, the thread immediately tries CAS. This avoids the expensive syscall if the lock is released quickly.

What happens when a thread goes to sleep? The kernel helps us put these sleeping threads into a queue. Take a look at the system call on Linux and Android to put the thread into sleeping state (this is usually called “park a thread”):

The key part is futex as *const Atomic<u32> - you give the kernel a memory address, and it queues your thread there. Later, when you want to wake a thread, you give the kernel that same address, and it dequeues and wakes a sleeper.

When a thread finishes, it sets the state to unlocked. If the state was contended, it wakes one waiting thread via syscall. This continues until the queue empties.

The final piece of std’s mutex is poisoning, a unique feature you won’t find in most other languages.

Poisoning: Panic Safety in Mutexes

One unique feature of Rust’s standard mutex is poisoning. When a thread panics while holding a lock, the mutex becomes “poisoned.” Any subsequent attempts to lock it will return an Err(PoisonError), but you still get the guard inside the error:

How does poisoning work? Conceptually, it happens in the MutexGuard::drop() path (simplified here for clarity):

The guard captures whether the thread was panicking when the lock was acquired. If we weren’t panicking then but we are now, a panic must have occurred in the critical section. The mutex is marked as poisoned with a simple atomic store.

This is a “best effort” mechanism. It won’t catch all cases (like double panics or non-Rust exceptions), but it provides a useful safety net. The key insight is that you still get access to the data even if the mutex is poisoned, allowing you to inspect and potentially recover from the corrupted state.

Big note: mutex poisoning gets both love and hate. It catches data corruption but feels awkward compared to other languages (Me too, I know it’s helpful. But I still hate it, lol). The Rust team is adding a non-poisoning variant - see issue#134645

How parking_lot does it differently?

parking_lot takes a fundamentally different approach. Two key differences:

• std uses different mutex implementations per platform. parking_lot uses one algorithm everywhere, calling platform-specific code only for sleep/wake.

• std’s queues live in the kernel. parking_lot manages its own queues in user space via a global hash table.

A Mutex That Fits in One Byte

parking_lot’s mutex is remarkably small:

Why can parking_lot use just one byte while std needs more? It comes down to how queues work.

std’s futex uses the kernel to manage wait queues. When you call the futex syscall, you pass the memory address of your atomic variable, and the kernel uses that address as the queue ID. But there’s a catch: the kernel requires this address to be aligned to a 32-bit boundary. So std’s mutex must use AtomicU32, even though it only needs a few bits for state.

parking_lot manages its own queues in user space. It hashes the mutex’s memory address to find the right queue bucket. Since it doesn’t need to satisfy kernel alignment requirements, it can use a single AtomicU8.

More states for queue bookkeeping

Using separate bits gives parking_lot four possible states:

• 00: Unlocked, no waiters

• 01: Locked, no waiters

• 10: Unlocked, but threads still waiting

• 11: Locked with waiters

That third state (10) might seem odd at first. Why would a mutex be unlocked but still have waiting threads? This is a transient state that happens during parking_lot’s unlock process. Because parking_lot manages its own queue, it uses the PARKED_BIT as bookkeeping to track whether threads are still in the queue. This helps avoid lost wakeups where a thread might miss its notification. It’s not an advantage over std, just a consequence of managing queues in user space rather than delegating to the kernel.

The Global Queue and Fairness Mechanism

When a thread can’t acquire the lock, it needs somewhere to wait. This is where parking_lot’s global hash table comes in.

How the global queue works

Instead of each mutex maintaining its own queue (like kernel futexes do), parking_lot uses a single global hash table shared by all mutexes in your program. When a thread needs to wait:

1. Hash the mutex’s memory address to find a bucket in the global table

2. Add the thread to the bucket’s wait queue

3. Go to sleep

Being able to manage the thread queue itself is important for parking_lot to enforce fairness. As you can see right away in the next section.

Eventual fairness

Here’s where parking_lot differs from std in behavior. std’s futex uses a “barging” strategy where any active thread can grab the lock when it’s released, even if others have been waiting in the queue longer. This maximizes throughput but can cause starvation.

When a thread unlocks, there are two sources of threads that can lock again:

• An active thread that is calling for locking

• A sleeping thread in the queue

As you can see, the active thread will tend to win the fight of “who locks first”. So if a thread keeps calling for lock, finishes its work, then locks right away, it keeps all other threads starved.

As you can see, thread A keeps grabbing the lock immediately after releasing it. Threads B and C do get woken up by the syscall, but by the time they try to acquire the lock, thread A has already grabbed it again. They’re completely starved.

parking_lot implements “eventual fairness” to prevent this.

Each bucket in the hash table has a timer that fires approximately every 0.5 milliseconds. When the timer fires, the next unlock becomes a “fair unlock”:

1. The unlocker keeps the LOCKED_BIT set

2. The woken thread receives the lock directly (a “handoff”)

3. That thread owns the lock immediately without racing with other active threads

So this means, instead of letting anyone who is fast grab the lock, parking_lot forces the lock to be given directly to the next one in the queue (it keeps the LOCKED_BIT set and hands off; it doesn’t even unlock).

This timer-based approach means parking_lot is unfair most of the time (for performance), but guarantees fairness every ~0.5ms to prevent any thread from being starved indefinitely. You can also force a fair unlock explicitly with unlock_fair() if needed.

This eventual fairness technique from parking_lot is pretty clever, isn’t it?

How parking_lot actually parks threads

You might wonder by now: how does parking_lot put threads to sleep without storing a 32-bit futex word inside every mutex? The answer is thread-local storage.

parking_lot still uses the same futex syscall as std, but it doesn’t pass the mutex address to the kernel. Instead, each thread owns a ThreadData record containing a reusable i32. Because this integer lives in thread-local storage, each thread has a unique address to use for the syscall. In the kernel, every blocked thread sits in its own single-entry queue.

The code looks almost identical to std’s futex path. The only difference? parking_lot points the syscall at the thread-local integer instead of the mutex:

When unlocking, parking_lot uses the same per-thread integer and issues FUTEX_WAKE on that address. This way, the mutex stays just one byte while the thread-local helper handles all the sleeping and waking.

On platforms without futexes, the parker swaps in the local blocking primitive (pthread_cond_t on macOS/BSD, Windows’ WaitOnAddress/keyed events, or a plain spin loop) while keeping the same per-thread queue design.

Benchmark Results: The Real Performance Story

Now let’s see how these implementations perform in practice. I ran benchmarks across four scenarios that reveal different aspects of mutex behavior. All benchmarks ran on Linux with the futex backend for std. You can find the source code and full report at https://github.com/cuongleqq/mutex-benches.

For each scenario, you’ll see:

• Per-thread operation counts: Shows how many lock acquisitions each thread completed

• Performance metrics: Throughput, wait latencies (median, mean, P99), and standard deviation

• Analysis: What the results tell us about each mutex’s behavior

(If the numbers feel overwhelming, just read the scenario configuration and skip straight to the takeaway.)

Scenario 1: Short Hold (Moderate Contention)

Configuration: 4 threads, 10 seconds, minimal work in critical section

Scenario: This simulates a typical application where threads frequently acquire and release locks with very little work inside the critical section. Each thread simply increments a counter, representing the common case of protecting small data structures or quick state updates.

Takeaway: In moderate contention with short critical sections, std’s futex shines with 9% higher throughput and lower average latency. The uncontended fast path and efficient kernel-managed queues work well here. However, look at the per-thread operations: std has 5.6% variation (20.6M vs 19.4M) while parking_lot has only 3.9% (18.9M vs 18.2M). Even in this favorable scenario for std, parking_lot’s fairness mechanism ensures more even work distribution across threads.

Scenario 2: Long Hold (Heavy Contention)

Configuration: 8 threads, 10 seconds, 500µs sleep while holding lock

Scenario: This tests heavy contention where threads hold the lock for a long time (500 microseconds). This simulates scenarios like I/O operations, slow computation, or accessing remote resources while holding a lock. With 8 threads competing for a lock that’s held for 500µs each time, contention is severe.

Takeaway: This benchmark reveals std’s critical weakness under heavy contention. Look at thread 3 in std: it completed only 66 operations while thread 5 completed 1,394. That’s a 95.3% variation - complete starvation. The extremely low median (125ns) combined with massive standard deviation (188.73ms) shows most lock attempts are fast, but some threads suffer extreme delays and essentially never get the lock.

parking_lot tells a different story. Every thread completed 860-877 operations (1.9% variation). The fairness mechanism worked exactly as designed. Yes, parking_lot has 7.5% lower throughput and higher median wait time, but that’s because it’s ensuring all threads make progress. The 51x more stable wait times (3.67ms vs 188.73ms standard deviation) show the predictability benefit. When fairness matters, parking_lot prevents the pathological starvation that std exhibits.

Scenario 3: Burst (Periodic Contention Spikes)

Configuration: 8 threads, 15 seconds, 200ms active / 800ms idle

Scenario: This simulates bursty workloads where threads alternate between periods of high activity (200ms of rapid lock acquisitions) and idle periods (800ms sleep). Think of web servers handling traffic spikes, batch processing systems, or applications with periodic activity patterns. This tests how mutexes handle sudden contention spikes followed by quiet periods.

Takeaway: parking_lot excels in bursty workloads, achieving 18.5% higher throughput than std. During activity bursts, all 8 threads compete intensely for the lock. parking_lot’s adaptive spinning and fairness mechanisms handle these periodic spikes better, ensuring more even work distribution (9.9% variation vs 13.6%). The 24.8% more stable wait times show parking_lot handles the transitions between idle and active periods more smoothly. While std has lower tail latencies, parking_lot’s better stability and fairness during bursts translate to higher overall throughput.

Scenario 4: Hog (Monopolization Scenario)

Configuration: 6 threads, 15 seconds, one thread monopolizes (sleeps 500µs while holding lock)

Scenario: This tests the worst-case scenario: one “hog” thread repeatedly acquires the lock and holds it for 500µs, while 5 other threads compete normally. This simulates real-world situations like priority inversion, where a high-priority or busy thread keeps grabbing the lock immediately after releasing it, potentially starving other threads. Can the mutex prevent monopolization?

Takeaway: This is the smoking gun that demonstrates std’s fundamental unfairness. The hog thread completed 12,242 operations while the other threads completed only 6-16 operations each. That’s complete starvation - the non-hog threads essentially never got the lock. The 100% variation and 130ms standard deviation show the extreme unpredictability.

parking_lot’s fairness timer prevented this catastrophe. The hog still got more operations (9,168) but nowhere near monopolization. All other threads made meaningful progress (7,023-7,109 operations). The result: 261.6% higher overall throughput because all 6 threads contributed work instead of 5 threads sitting idle. The 120x more stable wait times (1.09ms vs 130.76ms) show parking_lot’s predictability. The 0.5ms fairness timer does exactly what it promises: prevent any thread from monopolizing the lock indefinitely.

Decision Guide

After diving deep into the implementations and running comprehensive benchmarks, here’s when to use each:

Choose std::Mutex When:

1. You need zero dependencies - It’s in std, always available

2. Low to moderate contention with short critical sections - futex implementation is excellent here (9% faster throughput in our short-hold test)

3. You want poisoning for debugging - Helps catch panic-related bugs during development

4. Platform-specific optimizations matter - Gets priority inheritance on Fuchsia, etc.

Choose parking_lot::Mutex When:

1. Fairness is critical - Prevents thread starvation (49x better fairness in heavy contention)

2. Risk of monopolization exists - The hog scenario showed 261.6% better throughput by preventing starvation

3. Bursty workloads - 18.5% faster in our burst scenario

4. You need predictable behavior - 51x more stable latency under heavy load

5. Memory footprint matters - Always 1 byte regardless of platform

6. You want timeouts or fairness control - try_lock_for(), unlock_fair(), etc.

7. Cross-platform consistency is important - Same behavior everywhere

Share

Key Takeaways

The benchmarks reveal a fundamental trade-off: std::Mutex optimizes for throughput in the average case, while parking_lot::Mutex optimizes for fairness and predictability in the worst case.

For most applications, where contention is light and critical sections are short, std::Mutex performs excellently. But if your application has any of these characteristics:

• Long-running critical sections

• Risk of lock monopolization (e.g., one high-priority thread)

• Need for predictable latency across all threads

• Requirement that all threads make forward progress

Then parking_lot::Mutex’s eventual fairness mechanism becomes invaluable. The 0.5ms fairness timer is a small price to pay for preventing complete thread starvation.

If you made it this far, you’re probably as obsessed with understanding how things really work as I am. I’m Cuong, and I write about Rust and programming. If you share the same passion, I’d love to connect with you. Feel free to reach out on X, LinkedIn, or subscribe to my blog (substack, medium) to keep pushing the boundaries together!

Here’s what advanced pattern matching can look like (don’t worry if you don’t understand it now):

It took me way too long to discover these techniques. This post is so you don’t have to. I’ll cover:

• The basics (plus hidden details)

• Advanced techniques that matter

• Best practices I learned the hard way

Let’s start with the fundamentals.

Basic pattern matching

If you’re already comfortable with basic pattern matching, feel free to skim this section.

Matching literals, variables, and wildcards

The simplest patterns match exact values or capture anything:

This example shows:

• Literal matching (200)

• Or patterns for multiple values (301 | 302 | 307 | 308)

• Range matching (500..=599)

• Variable binding (code)

• Wildcard (_) to ignore the value

Destructuring tuples and structs

Pattern matching shines when breaking apart compound data:

Key points:

• .. ignores remaining fields you don’t care about

• Patterns are checked top-to-bottom, so active: false catches inactive users first

Working with arrays and slices

You can match on array and slice structure:

Notice the difference: The array match requires exactly 5 elements, while slice patterns adapt to any length. The .. matches however many elements are between the specified positions.

Advanced techniques

Time for the fun stuff. These techniques will make your code beautiful and a joy to write.

Taking references instead of consuming values

By default, pattern matching moves values, like this:

When we match Some(s), Rust transfers ownership of the String to variable s. This leaves data partially moved since the Option wrapper exists but its contents are gone. Rust prevents using partially moved values.

But you can work with references using two approaches below.

First approach: Match on a reference

Notice the match is on &data, Rust automatically borrows the inner fields for you.

Second approach: Use ref

You can achieve the same goal using ref:

But wait, if using & and ref is just doing the same thing, why do we even need ref?

Ref shines when you want to mix move and borrow of the same object. Look at this example:

In this example, we move user_id (cheap to copy) but borrow image (potentially large) for the quota check, and keep task intact for passing to do_task later.

Why ref works better than alternatives:

• &task approach: Forces user_id to be &u64 instead of u64, adding unnecessary indirection for a Copy type

• Owned matching: Consumes the entire task, making it unavailable for do_task(task) later

Match guards

So far, patterns let us match exact values or ranges. But what about much more complicated conditions?

Guards let you add any boolean expression after the pattern matches:

Important: Rust evaluates patterns first, then guards. The pattern extracts values (like url or path from Some), making them available for the guard condition. If the guard fails, Rust moves to the next pattern.

Binding the whole value with @

So far, patterns let you destructure data into its components. But what if you want to match on structure while keeping the whole value for function calls? Enter the @ symbol. Not sure why they picked that particular character, but here’s how it works:

Now that you’ve seen the advanced techniques, let’s step back and look at the bigger picture. Pattern matching isn’t limited to match expressions—Rust lets you use patterns in several different contexts, each with its own rules.

Where patterns are allowed

Rust divides pattern contexts into two categories based on whether the pattern must always succeed.

• Irrefutable patterns: Destructure data with known structure (let bindings, function parameters)

• Refutable patterns: Handle multiple possibilities with conditional logic (match, if let)

Irrefutable patterns

These contexts require patterns that always succeed:

Refutable patterns

These contexts handle patterns that might not match:

let-else is interesting. It’s relatively new (Rust 1.65). It requires the else block to diverge (it must return, panic!, or exit the function). This ensures the variable is definitely assigned if execution continues.

Best practices

Here are some guidelines for using pattern matching effectively in real-world Rust code.

Consider performance for hot paths

Match patterns are checked top-down, so put specific patterns before general ones to avoid unreachable arms. For complex conditions where order doesn’t affect logic, prioritize hot paths or cheaper conditions first (see example below).

Note: For simple enum or integer matches, the compiler generates efficient jump tables regardless of arm order. So this rule doesn’t apply.

Prefer match over if/else chains for enums

When handling enums, prefer match over if/else chains for better compiler optimization and exhaustiveness checking. While both approaches often compile to similar code in release mode, match gives the compiler more information to work with, and there are cases where if/else chains prevent certain optimizations that match enables.

Destructure multiple fields in one pattern

When you need several fields from a struct, destructure them all in the pattern instead of accessing them individually:

This makes the data dependencies explicit and often reads more clearly than repeated field access.

Use matches! for simple boolean checks

For yes/no questions, matches! is more concise than single-arm match:

These practices help you write pattern matching code that’s both performant and maintainable. The key is choosing the right tool for each situation rather than defaulting to complex match expressions everywhere.

Key takeaways

Pattern matching is one of Rust’s most distinctive features, and mastering it transforms how you write Rust code. If you can’t remember everything from this post, bookmark it and come back when you need any of these:

• Advanced destructuring with tuples, structs, arrays, and slices

• Reference patterns and match ergonomics for ownership control

• Strategic use of guards, and @ bindings

• Best practices for choosing the right pattern matching tool

With these techniques in your toolkit, you’ll write more expressive, safer, and more maintainable Rust code.

If you made it this far, you’re probably as obsessed with understanding how things really work as I am. I’m Cuong, and I write about Rust and programming. If you share the same passion, I’d love to connect with you. Feel free to reach out on X, LinkedIn, or subscribe to my blog (substack, medium) to keep pushing the boundaries together!

Example 1: Function and Closure Confusion

process_data expects a function that takes an i32 and returns an i32. Both closures match this signature exactly. The first closure |x| x + 1 works perfectly, but the second closure |x| x * multiplier fails. What's the difference?

Error: error[E0308]: mismatched types (expected fn pointer, found closure)

Example 2: Variable Capturing Confusion

Both closures use data, but one works multiple times while the other stops working after the first call. What's the difference?

Error: error[E0382]: use of moved value: 'closure2'

If you've encountered any of these scenarios, you're not alone. In this post, I'll:

• Explain what functions and closures (with their traits) really are

• Show the relationships between them

• Dive into the internals that explain these confusing behaviors

By the end, you'll have mastered one of Rust's most difficult topics inside out. Let's go.

Function & Function Pointer

Let's start by examining how Rust handles regular functions. There are some surprising details about function types that most developers never encounter.

Function

A function in Rust is exactly what you'd expect:

Simple enough. But here's where it gets interesting: when you mention a function by name like add_one, you don't get a pointer to it. Instead, you get a special zero-sized value that represents that exact function, and calling it is a direct call. This zero-sized value is called a function item.

Function Item

Every function you define creates a unique, zero-sized type called a function item. This type is compiler-generated and cannot be named directly in your code:

f1 and f2 have different function item types even though they have identical function signatures. When you assign add_two to f1 at the end of the example, you get a type mismatch error because of that.

This unique typing enables powerful compiler optimizations. Since the compiler knows exactly which function will be called at compile time, it can:

• Inline the function call - Replace the call with the function's body directly

• Use static dispatch - No runtime lookup needed to find the function

• Apply aggressive optimizations - Dead code elimination, constant folding, etc.

For example, f1(x) gets replaced by x + 1 directly, eliminating the function call overhead entirely.

Function Pointer

So how do we store different functions in the same variable? We convert them to function pointers:

Now, we explicitly tell the compiler that we want function pointers fn(i32) -> i32 for f1 and f2. Rust coerces add_one and add_two (function items) to function pointers and assigns them to f1 and f2. You can see at the end that I am able to assign both add_two and even f2 to f1 just fine, unlike the previous example.

The trade-off is that function pointer calls use dynamic dispatch (indirect calls through the pointer), which typically prevents inlining unlike direct calls from function items, but we gain flexibility.

Closure & Trait

Now let's understand closures and why they're different from functions.

Closure

A closure is an anonymous function that can capture variables from its surrounding environment:

The key difference: closures can access variables from their enclosing scope, while regular functions cannot.

The Three Closure Traits

Closures don't all capture variables in the same way. The manner of capture depends on what the closure does with those variables, and this directly determines which traits the closure implements.

The Rust compiler automatically assigns one of three traits to each closure based on how it uses captured variables:

FnOnce - Moves Captured Variables

Once data is dropped, calling the closure again would attempt to drop the same memory twice, leading to undefined behavior. Rust prevents this by making such closures callable only once.

FnMut - Mutates Captured Variables

Fn - Only Reads Captured Variables

Note about the move keyword: Sometimes you'll see closures with the move keyword, which forces the closure to take ownership of captured variables. However, move doesn't always mean FnOnce. If the captured variables aren't dropped or consumed, the closure can still be called multiple times and won't be FnOnce.

Trait Hierarchy

Let's look at a function that accepts an FnOnce closure:

This function promises to call the closure only once. That's the only restriction it places on the closure.

Now, if you have an Fn closure that can be called multiple times, can you pass it to execute_once? Absolutely! A closure that can be called multiple times can certainly be called just once. The same logic applies to FnMut closures - they can be called multiple times, so they can also be called once.

This creates a hierarchy: Fn can be used anywhere, FnMut works where FnMut or FnOnce is needed, and FnOnce only works where FnOnce is required.

Alright, that's a lot of rules to remember about functions and closures. Remembering these rules is good, but we'll quickly forget them. That's why it's much better to understand what happens behind the scenes. Let's dive into how Rust actually implements closures.

Closure Behind the Scene

How Rust Desugars Closures

When you write a closure, the Rust compiler internally transforms it into a compiler-generated anonymous struct with trait implementations:

The compiler conceptually transforms this closure into something like:

In this transformation, the original data variable is moved into the ClosureEnvironment struct. When the closure is called, it consumes itself (self) and drops the moved data. This is why the closure can only be called once. After the first call, both the closure struct and its captured data are consumed.

The same idea applies for Fn and FnMut. Rust transforms every closure into a compiler-generated struct with the appropriate trait implementation based on how it uses captured variables.

The compiler chooses the least intrusive capture mode it can. For each captured variable, it starts with the most permissive option (immutable borrow) and only escalates to more restrictive modes (mutable borrow, then move) when the closure's body requires it.

Why the Trait Hierarchy Works

Earlier we saw that you can pass an Fn closure where FnOnce is expected, but how is this possible when they're different traits? The answer lies in how the traits are defined.

The three closure traits form a hierarchy through trait inheritance:

Notice the : FnOnce<Args> and : FnMut<Args> syntax, this means:

• Every type that implements FnMut must also implement FnOnce

• Every type that implements Fn must also implement both FnMut and FnOnce

Relation Between Function Pointer & Closure Trait

As we saw earlier in Example 1, sometimes we can pass closures to functions expecting function pointers, but sometimes we can't. Let's understand why.

Non-Capturing Closures Become Function Pointers

When a closure doesn't capture any variables, it doesn't need the hidden struct we saw earlier. Since there's no captured state to store, Rust can coerce such closures directly to plain function pointers:

But as soon as the closure captures variables, this coercion is no longer possible:

Note: There are additional restrictions (like the closure being non-async), but we won't cover those here.

Function Pointers Implement All Closure Traits

Functions are essentially like non-capturing closures, they have no state and can be called repeatedly without side effects. Therefore, function pointers implement all three closure traits (Fn, FnMut, and FnOnce):

This bidirectional compatibility (non-capturing closures can become function pointers, and function pointers can be used as closures) creates a seamless integration between Rust's function and closure systems.

Key Takeaways

Let's summarize what we've learned about Rust's function and closure system:

1. Function Items vs Function Pointers: Every function creates a unique, zero-sized, compiler-generated type that enables powerful optimizations through static dispatch. Function pointers use dynamic dispatch but allow storing different functions in the same variable.

2. Closure Capture Modes: Closures are categorized by how they capture variables. FnOnce moves captured variables, FnMut mutates them, and Fn only reads them. The compiler chooses the least intrusive capture mode possible.

3. Trait Hierarchy: The closure traits form a hierarchy through supertraits where Fn extends FnMut, which extends FnOnce. This means an Fn closure can be used anywhere FnMut or FnOnce is expected.

4. Compiler-Generated Structs: Closures are transformed into anonymous structs that hold captured variables and implement the appropriate closure traits.

5. Seamless Integration: Non-capturing closures can be coerced to function pointers, while function pointers implement all closure traits. This creates bidirectional compatibility between functions and closures.

If you made it this far, you're probably as obsessed with understanding how things really work as I am. I'm Cuong, and I write about Rust and programming. If you share the same passion, I'd love to connect with you. Feel free to reach out on X, LinkedIn, or subscribe to my blog (substack, medium) to keep pushing the boundaries together!

Then I saw what Rust did with enums: each option can hold real data inside it, the compiler makes sure you don't forget to handle any case, and the type system blocks you from creating combinations that don't make sense. And the kicker? It all compiles down to something efficient, with zero extra indirection and often memory-optimal layouts.

That's when it clicked: this isn't just an enum. This is one of Rust's secret weapons.

In this post, I'll show you why Rust's enums deserve your respect, how you've been relying on them without even noticing, and what makes them so efficient once you see how they're laid out in memory. By the end, I hope you'll never look at Rust enums the same way again.

What's different about enums in Rust?

In most languages, enums are just names slapped on top of integers. They don't hold data, and the compiler won't stop you from forgetting to handle a case.

Rust takes a very different approach.

The first big difference: Rust enums can carry data. A variant isn't just a label. It can bundle real, typed information right inside.

enum Shape {
    Circle(f64),
    Square(f64),
    Rectangle(f64, f64),
}

Here, Shape isn't just "Circle = 0, Square = 1." Each variant carries the exact data it needs: a radius for Circle, a side length for Square, and width + height for Rectangle. This way, you can't create an impossible state. Every variant has exactly the fields it should, nothing extra, nothing missing.

You can even give the data names if it makes your code clearer:

enum Shape {
    Circle { radius: f64 },
    Square { side: f64 },
    Rectangle { width: f64, height: f64 },
}

Now when you create a shape, it's obvious what each number represents: Shape::Rectangle { width: 10.0, height: 5.0 } instead of trying to remember whether Rectangle(10.0, 5.0) means width-then-height or height-then-width.

The second big difference: Rust forces you to handle every case. With pattern matching, you don't just check which variant you got. The compiler makes sure you didn't forget any.

fn area(shape: Shape) -> f64 {
    match shape {
        Shape::Circle(r) => std::f64::consts::PI * r * r,
        Shape::Square(s) => s * s,
        Shape::Rectangle(w, h) => w * h,
    }
}

If you leave out Rectangle, this won't even compile. That's a huge step up from enums in other languages, where forgetting a case often triggers runtime bugs you might never notice.

Historical note: Rust didn't invent this magic. These ideas (variants that carry data and pattern matching) originated in the ML family (think Standard ML and OCaml) back in the 1970s, which pioneered what we now call tagged unions. Rust borrowed that power, but tailored it for systems programming.

These two differences (data inside variants and compiler-enforced case coverage) already set Rust's enums apart. But the real magic isn't just in the syntax. It's in the kinds of problems enums can solve for you. That's where their true power shows up.

Why enum in Rust is powerful

Imagine you're designing a configuration for a file uploader. You want to support two modes: anonymous upload (no username needed) or authenticated upload (which requires a username and password). You might try this with a struct:

pub struct UploadConfig {
    pub destination: String,
    pub anonymous: bool,
    // username and password should only be set if anonymous == false
    pub username: Option<String>,
    pub password: Option<String>,
}

This compiles, but it's awkward. Nothing prevents someone from setting anonymous = true and also filling in a username and password. Now you've got nonsense states your code has to tiptoe around. You're left relying on comments or runtime checks.

Enums fix this cleanly:

pub enum Auth {
    Anonymous,
    Credentials { username: String, password: String },
}

pub struct UploadConfig {
    pub destination: String,
    pub auth: Auth,
}

Now the invalid combination simply can't exist. If you have Anonymous, there's no username or password field lurking around. If you need credentials, you're forced to provide both. The compiler ensures every UploadConfig is valid by construction.

And that's the deeper point: Rust enums let you make invalid states impossible to represent. Entire categories of bugs disappear before your code even compiles. You're not just writing programs — you're encoding correctness into the design itself.

Two most common enums you use every day: Option and Result

Even if you've never written your own enum, you've been using them constantly. Option<T> is Rust's way of saying a value may or may not exist, without resorting to null. Its variants are simple:

enum Option<T> {
    Some(T),
    None,
}

Because it's an enum, you can't ignore the None case. The compiler forces you to deal with it. That's why null pointer exceptions (the nightmare bug that haunts every other language) simply don't exist in Rust.

Similarly, Result<T, E> encodes success or failure as an enum:

enum Result<T, E> {
    Ok(T),
    Err(E),
}

This design turns error handling into an explicit part of your program's flow. You can't accidentally forget that something might fail. The type system reminds you at every call site.

These two enums alone account for a huge amount of Rust's safety and reliability, and they're built on the same principles you can use in your own code.

If you're building systems software, you probably care about memory usage. So let's ask the practical question: how much space do these powerful enums actually take?

Dive deeper into Rust enum memory layout

The answer might surprise you. Despite all their flexibility, Rust enums are remarkably compact. The compiler uses a clever layout strategy that minimizes waste while keeping access fast.

Here's how it works. For any enum, Rust needs to track two pieces of information in memory:

1. Which variant is currently active (the tag)

2. The data for that variant (the payload)

Rather than storing these separately, Rust packs them together as efficiently as possible. Let me show you exactly what this looks like.

Important Note: These memory layouts show how the current Rust compiler typically arranges enums, but this isn't guaranteed to stay the same. With the default repr(Rust) representation, the compiler is free to change layout across different versions to optimize performance. You can rely on size_of::<T>() and align_of::<T>() for your compiled program, but the specific field arrangement and internal layout may change. Use these examples to understand concepts, not for low-level memory manipulation.

Example 1: Simple enum with no data

Start with the simplest case, an enum where variants carry no data:

enum Simple {
    A,
    B,
}

The memory layout is straightforward:

Since there's no payload data to store, Rust only needs a single byte to remember which variant you chose. No wasted space at all.

Example 2: Enum with data of different sizes

Now let's see what happens when variants carry data:

enum SingleOrPair {
    One(u8),        // needs 1 byte for the u8
    Pair(u8, u8),   // needs 2 bytes for two u8s
}

Here, Rust has to accommodate the largest possible variant (Pair), plus space for the tag:

Since all components (u8 tag and u8 data fields) have 1-byte alignment, no padding is needed. The enum takes exactly 3 bytes: 1 for the tag plus 2 for the largest variant (Pair).

The key insight: Rust allocates enough space for the largest variant, then reuses that same space for smaller variants. When you store One(42), it uses just 1 byte of the payload space. When you store Pair(10, 20), it uses both payload bytes. The enum always takes exactly 3 bytes regardless of which variant is active.

Example 3: Advanced optimization with niche-filling

Now for the really clever part. Sometimes Rust can eliminate the tag entirely through a technique called niche-filling. The compiler frequently applies this optimization when it detects unused bit patterns (though this behavior isn't guaranteed and may vary between compiler versions).

enum ByteOrText {
    Byte(u8),
    Text(String),
}

A String in Rust contains three usize fields: a pointer to the data, the length, and the capacity. On a 64-bit system, that's 3 × 8 = 24 bytes.

Normally you'd expect this enum to be 25 bytes (24 for String + 1 for tag). But here's what actually happens:

The magic: in a valid String, the pointer is never null. It always points to allocated memory. Rust exploits this by using the null pointer value as a signal meaning "this is actually the Byte variant, not the Text variant."

So when you have:

• Text("hello"): pointer is non-null, so this is the String variant

• Byte(42): pointer is null, so this is the Byte variant, and the actual 42 value is stored in the length field

The tag disappeared entirely. Rust encoded the "which variant" information inside the existing data, using a bit pattern that would otherwise be invalid. The enum takes no more memory than a plain String would.

This optimization happens automatically whenever Rust finds "impossible" bit patterns it can repurpose. You get the benefits without changing your code.

Here's proof straight from the compiler.

use std::mem::size_of;

enum Simple {
    A,
    B,
}

enum SingleOrPair {
    One(u8),
    Pair(u8, u8),
}

enum ByteOrText {
    Byte(u8),
    Text(String),
}

fn main() {
    println!("Size of Simple: {} bytes", size_of::<Simple>());
    println!("Size of SingleOrPair: {} bytes", size_of::<SingleOrPair>());
    println!("Size of ByteOrText: {} bytes", size_of::<ByteOrText>());
}

These memory optimizations aren't just compiler tricks - they're what make Rust's powerful enum features practical for systems programming. When you can encode rich type information with minimal overhead, you get safety without sacrificing performance.

Key takeaway

• Rust enums go far beyond the enums you may know from other languages. They carry data, enforce exhaustive handling, and make invalid states impossible. At the same time, their memory layout is compact and efficient, thanks to compiler tricks like niche-filling.

• You already rely on enums every day through Option and Result. But the real magic happens when you use them in your own types: modeling states, encoding invariants, and letting the compiler protect you from whole categories of bugs.

If you made it this far, you're probably as obsessed with understanding how things really work as I am. I'm Cuong, and I write about Rust and programming. If you share the same passion, I'd love to connect with you—feel free to reach out on X, LinkedIn , or subscribe to my blog (substack, medium) to keep pushing the boundaries together!

These aren't easy questions if you haven't been in the Rust ecosystem long enough. In fact, each constructor pattern solves specific problems, and once you understand the underlying design principles, they become just another tool in your toolbox. You stop asking "which patterns should I use?" and start asking "what problems am I solving?"

// When designing your own types, which patterns should you support?
struct MyConfig { /* ... */ }

impl MyConfig {
    pub fn new() -> Self { /* ... */ }       // Associated functions
    pub fn from_file(path: &str) -> Result<Self, Error> { /* ... */ }
}

impl Default for MyConfig { /* ... */ }      // Trait implementations

impl From<&str> for MyConfig { /* ... */ }   // Conversion traits

// Or chained construction?
let config = MyConfigBuilder::new()
    .timeout(30)
    .retries(3)
    .build()?;

In this post, we'll decode Rust's constructor approaches: associated functions, trait-based construction, and builder pattern. We'll explore the decision frameworks that guide when to use each.

But first, let's understand why this variety exists in the first place.

Why do all these patterns exist?

Unlike C++ or Java, Rust refuses to have a special constructor syntax and just uses regular functions instead. Rust dodged a bullet here. Traditional constructors are a mess, and Rust designers knew it. Let's look at a few:

• Traditional constructors let you initialize fields flexibly. You can do all sorts of magic with them, or you can forget to initialize some fields entirely. Then your program crashes at 2 AM on a Sunday, and you spend four hours hunting down a null pointer that could have been caught at compile time. Rust prevents this by requiring you to explicitly specify every field, catching mistakes at compile time. Predictability over convenience!

• Traditional constructors can only express their intent through parameter lists. Try reading Server("localhost", 8080, 30) six months later. Is that 30 a timeout? A retry count? A connection limit? You'll waste 10 minutes just figuring out what your own code does. In contrast, Rust's explicit names like Server::with_timeout("localhost", 8080, 30) and Server::with_ssl("localhost", 8080) have much higher readability.

• Traditional constructors hide whether they can fail. Will FileReader("/tmp/data.txt") throw an exception? You can't tell from the call site, making error handling unpredictable. Rust constructors are just functions that can return whatever type expresses their behavior: Result<Self, Error> for fallible construction, Option<Self> for operations that might not produce a value.

Rust's language provides some solutions (associated functions and traits), while the community developed others (like builders). Together, they address three fundamental construction challenges:

• Simple custom initialization → Associated functions

• Ecosystem compatibility (so your types work with Option::unwrap_or_default(), generic functions, etc.) → Trait implementations

• Complex configuration with many options → Builder patterns

So where do you start? What's the foundation that every Rust type should have?

Associated functions.

Associated Functions: The Rust Way to "Constructor"

Associated functions are like class-level functions in other languages—they belong to the type but don't operate on a particular instance. (Regular methods take self to operate on a specific instance, while associated functions work at the type level.) They're Rust's primary way to create new instances, and you've probably used them without thinking about it:

let vec = Vec::new();
let vec_with_space = Vec::with_capacity(100);
let string = String::new();
let file = File::open("config.txt");

Unlike traditional constructors, each associated function has a descriptive name that tells you exactly what kind of construction is happening. Vec::new() creates an empty vector, while Vec::with_capacity(100) pre-allocates space for 100 elements.

When to use associated functions

Use associated functions when you have different ways to initialize the same type:

impl Vec<T> {
    pub fn new() -> Self { /* ... */ }
    pub fn with_capacity(capacity: usize) -> Self { /* ... */ }
    pub unsafe fn from_raw_parts(ptr: *mut T, length: usize, capacity: usize) -> Self { /* ... */ }
}

Each function name immediately communicates the construction strategy. The ::new() function is universally expected in Rust and these functions are usually tiny and often inlined in optimized builds, so overhead is negligible. Half the time, new() is just syntactic sugar for Default::default(). Technically useless. But skip it and developers will assume your API is broken. The convention is that strong.

Since associated functions are regular functions, they can return any type that expresses their behavior: Result<Self, Error> for operations that might fail, this is called 'fallible construction,' Option<Self> for operations that might not produce a value, or in special cases you might return Arc<Self> to enforce shared ownership (reference-counted smart pointer).

Common naming conventions

The Rust ecosystem has developed consistent naming patterns:

• new() - Basic constructor with sensible defaults that everyone expects

• with_*(...) - Constructor with specific configuration (Vec::with_capacity, ProgressBar::with_draw_target, Router::with_state)

• from_*(...) - Constructor from different data sources with validation/decoding (String::from_utf8, u32::from_be_bytes). This differs from the From trait, which is for simple, infallible conversions.

• Action verbs - For fallible operations (connect, open, load)

These aren't enforced by the compiler, but following them makes your API predictable to other Rust developers.

Trait-Based Construction: Standard Interfaces

Once you have basic constructors working, the next step is making your types feel native to Rust—that's where standardized trait-based construction shines.

While associated functions give you custom constructors, traits provide standardized ways to create values that work across the entire ecosystem. When you implement these traits, your types automatically work with standard library functions and other code.

Default: The zero-argument constructor

Default is Rust's closest equivalent to a parameterless constructor. You can derive it automatically for simple cases:

#[derive(Default)]
struct Config {
    host: String,        // defaults to ""
    port: u16,          // defaults to 0
    enabled: bool,      // defaults to false
}

Or implement it manually when you need custom default values:

impl Default for Config {
    fn default() -> Self {
        Self {
            host: "localhost".to_string(),
            port: 8080,
            enabled: true,
        }
    }
}

Default shines when working with functions that need to create instances of your type, and with collections. It enables your types to work seamlessly with APIs like Option::unwrap_or_default() (falls back to default value), mem::take(&mut value) (replaces value with default), HashMap::entry().or_default() (inserts default if key missing), and any generic function that needs to create instances of your type.

From, Into, TryFrom, and TryInto: Type conversions

From and Into handle infallible conversions between types (conversions that always succeed). When conversions might fail, use TryFrom and TryInto instead.

use std::net::{IpAddr, Ipv4Addr};
use std::convert::TryFrom;

// From the standard library: infallible conversion
impl From<Ipv4Addr> for IpAddr {
    fn from(ipv4: Ipv4Addr) -> IpAddr {
        IpAddr::V4(ipv4)
    }
}

// Usage works both ways automatically
let ipv4 = Ipv4Addr::new(127, 0, 0, 1);
let ip1 = IpAddr::from(ipv4);
let ip2: IpAddr = ipv4.into();  // Into is automatically available

// TryFrom example: fallible conversion between integer types
let big_number: i64 = 300;
let small_number: Result<u8, _> = u8::try_from(big_number); // Might fail if > 255
let converted: u8 = small_number?; // Use with ? operator

This pattern allows your types to integrate seamlessly with error handling using the ? operator and Result chains.

When to use trait-based construction

Use traits when:

• Your type has an obvious "default" or "empty" state (Default)

• You're converting from standard types like &str, u32, or Vec<T> (From/Into for infallible conversions, TryFrom/TryInto for fallible ones)

• You want your type to work seamlessly with generic code

Traits make your types feel native to Rust's ecosystem rather than foreign additions.

While associated functions and traits handle most constructor needs, sometimes you encounter types with many optional parameters or complex configuration requirements. So what do you do when you have 15 optional parameters? When your constructor call looks like Config::new(None, Some(30), false, None, Some("localhost"), true, None)?

For these scenarios, Rust developers turn to the builder pattern.

Builder Pattern: Taming Complex Construction

The builder pattern provides a fluent, readable interface for complex construction. Builders come with a cost. They're not free complexity—use them when the pain of not having them exceeds the pain of maintaining them. The complexity comes from additional types (the builder struct), and may introduce additional memory allocations depending on what data you store or convert during building, and more complex error handling (validation can happen at build time rather than construction time).

Basic builder pattern

Here's how reqwest (a popular HTTP client) implements its builder:

// From the reqwest crate
impl ClientBuilder {
    pub fn new() -> ClientBuilder { /* ... */ }
    pub fn timeout(mut self, timeout: Duration) -> ClientBuilder { /* ... */ }
    pub fn redirect(mut self, policy: redirect::Policy) -> ClientBuilder { /* ... */ }
    pub fn user_agent<V>(mut self, value: V) -> ClientBuilder { /* ... */ }
    pub fn build(self) -> Result<Client, Error> { /* ... */ }
}

// Usage becomes extremely readable:
let client = ClientBuilder::new()
    .timeout(Duration::from_secs(30))
    .redirect(redirect::Policy::limited(5))
    .user_agent("MyApp/1.0")
    .build()?;

Notice how we use a separate builder struct (ClientBuilder) to collect configuration parameters through method chaining, then call build() to construct the final target struct (Client). This separation allows for flexible parameter setting while maintaining type safety. The build() method returns a Result to handle any validation errors or construction failures that might occur during the final assembly.

Derive macros and automation

For simple builders, use the derive_builder crate:

use derive_builder::Builder;

#[derive(Builder)]
struct ServerConfig {
    host: String,
    #[builder(default = "8080")]
    port: u16,
    #[builder(default)]
    ssl_enabled: bool,
}

// Automatically generates ServerConfigBuilder with all methods
let config = ServerConfigBuilder::default()
    .host("localhost".to_string())
    .port(3000)
    .ssl_enabled(true)
    .build()?;

Note that we use the #[derive(Builder)] macro to automatically generate the builder struct and methods, and #[builder(...)] attributes to configure default values.

Use derive macros for straightforward builders, hand-written builders when you need custom logic or validation.

When to use builders

Use the builder pattern when:

• You have many optional parameters (typically 4+ for simple types, or fewer if parameters are complex or need validation)

• The parameter combinations create cognitive overhead when reading constructor calls

• Parameter combinations need validation

• The construction process has multiple steps (like connecting to a database, then authenticating, then configuring)

• You need a fluent, self-documenting API for complex configuration (method names make intent clear: .timeout(30) vs a positional parameter)

Builders excel at making complex APIs approachable and self-documenting.

Bringing It All Together

Now that we've explored the three main constructor patterns in Rust, you might wonder: do I have to choose just one? The answer is no. In practice, well-designed types often combine multiple patterns to serve different use cases.

Combining Patterns

Most well-designed types implement multiple constructor patterns:

impl MyConfig {
    pub fn new() -> Self { Self::default() }  // Convenience wrapper
    pub fn from_file(path: &str) -> Result<Self, Error> { /* ... */ }
    pub fn builder() -> MyConfigBuilder { /* ... */ }
}

impl Default for MyConfig { /* ... */ }

This gives users flexibility: Default for generic code, new() for common cases, from_file() for specific sources, and builder() for complex configuration. Each pattern serves its purpose, and together they create a comprehensive API that feels natural to Rust developers.

Key Takeaways

We've covered a lot of ground—from simple associated functions to complex builders. Here are the essential insights to guide your constructor design decisions:

• Choose the right pattern for your needs: Use associated functions for different initialization strategies, trait implementations when you want ecosystem integration, and builders for complex types with many optional parameters.

• Follow established naming conventions (new(), with_*(), from_*()) and make error handling explicit through return types like Result.

• Start simple with basic associated functions (new()) and trait implementations (Default), then evolve to builders as your API's complexity grows.

If you made it this far, you're probably as obsessed with understanding how things really work as I am. I'm Cuong, and I write about Rust and programming. If you share the same passion, I'd love to connect with you—feel free to reach out on X, LinkedIn , or subscribe to my blog (substack, medium) to keep pushing the boundaries together!

That was, until I hit the traits Send and Sync—still ownership and borrowing but in the multithreaded context. I'd spend hours reading documentation, only to feel more lost than when I started. At one point, I genuinely thought about switching back to Go just to avoid the headache.

The official Rustonomicon definition only made things worse:

• A type is Send if it's safe to send it to another thread.

• A type is Sync if it's safe to share between threads.

This definition failed me badly because it told me what but never why. I could follow examples mechanically, but I couldn't reason about new types. Sure, I could memorize that Rc isn't Send and Arc usually is—but I had no idea why. I felt like I was just collecting random facts instead of actually understanding anything.

This motivates me to dig deeper and find the underlying principles that I will present to you today in this post.

Here's what finally clicked for me: these traits aren't arbitrary—they're Rust's way of encoding specific thread safety concerns into the type system. All those hours of confusion suddenly made sense when I stopped trying to memorize and started understanding the underlying danger. To grasp Send and Sync, we need to understand what makes threading dangerous in the first place.

Send and Sync Are About Thread Safety

The core danger in multithreaded programming is data races. A data race happens when multiple threads access the same memory at the same time, with at least one thread changing the data, and nothing to coordinate that access.

Picture a website hit counter at 1000 visits when two users arrive simultaneously. Both requests read "1000", both compute "1001", both write "1001". Expected result after two visitors: 1002. Actual result: 1001.

Rust's Send and Sync traits are designed to prevent data races by encoding thread safety rules directly into the type system:

• Send: You can move this value to another thread without causing data races. (Think: unique ownership + thread safety)

• Sync: Multiple threads can hold references to this value without causing data races. (Think: shared access + thread safety)

The key insight is that Send is about unique ownership across threads, while Sync is about shared access across threads. When you move a value (Send), you're transferring complete control to another thread. When you share references (Sync), multiple threads have access but need coordination to avoid conflicts.

Let's see how this plays out with concrete examples.

A Type That's Both Send and Sync

Consider String—it's both Send and Sync. Here's why this makes sense:

Send example:

// Send: Safe to move to another thread
let s = String::from("hello");
thread::spawn(move || {
    println!("{}", s); // s is now owned by this thread
});
// s is no longer accessible in the original thread

Why this is safe: Moving gives the new thread unique ownership of the string's data. Since only one thread can access it at a time, there's no possibility of a data race. The original thread can't touch the string anymore, it's been completely transferred.

Sync example:

// Sync: Safe to share references across threads
let s = String::from("hello");
let s_ref = &s;

thread::scope(|scope| {
    scope.spawn(|| {
        println!("{}", s_ref); // Reading via shared reference
    });
    scope.spawn(|| {
        println!("{}", s_ref); // Multiple threads can read simultaneously
    });
});

Why this is safe: Multiple threads have shared access to the string, but they can only read it. Since nobody can modify the data (you'd need &mut s for that), the shared access is thread-safe. Multiple readers don't conflict with each other.

From this String example, we can extract a general pattern. Most types are both Send and Sync because:

1. Send: Moving creates unique ownership in the new thread. Since only one thread can access the data at any time, there's no possibility of conflicts.

2. Sync: Shared references only allow reading. Multiple threads reading the same data simultaneously doesn't cause problems.

This simple model works perfectly for basic types like i32, String, Vec<T>, and most structs you'll create. The thread safety comes from Rust's ownership rules: either one thread owns the data (Send), or multiple threads can read but none can write (Sync).

I really wish Rust's type system were this simple. But of course, Rust wouldn't let us off that easy. Interior mutability breaks all our nice assumptions about "move = unique ownership" and "shared = read-only." Let's dive in.

What Makes a Type !Sync

Here's where our simple "shared references = read-only" rule breaks down. Some types in Rust allow interior mutability—they let you change data even when you only have a shared reference. If you'd like a deeper explanation of interior mutability and why Rust needs it, let me know in the comments—I'll write a dedicated post about it. For now, just understand that it breaks the usual "shared reference = read-only" rule.

To understand why this is problematic, let's look at Cell<u64>:

use std::cell::Cell;

let cell = Cell::new(42);
let cell_ref = &cell; // Just a shared reference, no &mut
cell_ref.set(100);    // But we can still modify the value inside!
println!("{}", cell_ref.get());

Notice what's happening here: we have a shared reference (&cell), not a mutable one (&mut cell), but we can still change the data inside through set(). This breaks Rust's usual rule that shared references are read-only.

Cell<T> exists because sometimes you need to modify simple values (like counters or flags) even when you only have shared access to the containing structure. It's particularly useful when you need to track simple state like hit counters, flags, or retry attempts within otherwise immutable structures. Cell allows you to replace the entire value atomically without complex borrowing.

Now here's the threading problem: Cell<u64> lets you change data through a shared reference, but it has no protection against multiple threads doing this at the same time. If two threads both tried to call set(), you'd get a data race:

// This WILL NOT compile
let cell = Cell::new(0);
thread::scope(|scope| {
    // error[E0277]: `Cell<i32>` cannot be shared between threads safely
    scope.spawn(|| cell.set(1)); // Thread 1 writing
    scope.spawn(|| cell.set(2)); // Thread 2 writing simultaneously
});

That's why Cell<T> is !Sync, it can't be safely shared between threads. The interior mutability breaks our "shared references are safe" assumption.

But interior mutability doesn't automatically make a type !Sync. If the type can prevent data races, it can still be Sync. Some types solve this problem by adding their own synchronization. That's the case with AtomicU64 and Mutex<T>:

use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Mutex;

// AtomicU64: Uses hardware-level atomic operations
let atomic = AtomicU64::new(0);
thread::scope(|scope| {
    scope.spawn(|| atomic.store(1, Ordering::Relaxed)); // Safe
    scope.spawn(|| atomic.store(2, Ordering::Relaxed)); // Safe
});

// Mutex: Uses locking to serialize access
let mutex = Mutex::new(0);
thread::scope(|scope| {
    scope.spawn(|| *mutex.lock().unwrap() = 1); // Safe
    scope.spawn(|| *mutex.lock().unwrap() = 2); // Safe
});

Both types allow interior mutability with protection against data races, so they stay Sync. The key difference is that AtomicU64 uses hardware-level atomic operations that happen in a single step, while Mutex<T> makes threads take turns—only one thread can hold the lock at a time, so changes happen one after another instead of simultaneously.

The refined model for Sync:

• If shared references can't change the data → Sync

• If shared references can change the data without synchronization → !Sync

• If shared references can change the data with synchronization (atomics, locks) → Sync

Now, time for !Send—let's go.

What Makes a Type !Send

You might think that Send would be simpler than Sync. After all, when you move a value to another thread, you're giving that thread complete ownership—what could go wrong?

The problem is that some types maintain hidden shared state even after being moved. The move operation transfers the obvious data, but there might be invisible connections to the original thread that create thread safety issues.

The classic example is Rc<T> (reference-counted pointer):

use std::rc::Rc;

let rc1 = Rc::new(42);
let rc2 = rc1.clone(); // Both point to the same data

// If we could send rc1 to another thread (we can't!)...
thread::spawn(move || {
    drop(rc1); // Decrements reference count
});

// ...while rc2 exists on the original thread
drop(rc2); // Also decrements the same reference count

Here's what's happening: Rc<T> works by keeping a reference counter—when you clone an Rc, it increases the counter, and when you drop an Rc, it decreases the counter. When the counter reaches zero, the data gets cleaned up.

The critical insight: even after moving rc1 to another thread, you don't have unique ownership of the reference counter—it's still shared with rc2 on the original thread. Since Rc<T> uses a non-atomic reference counter, if two threads change that counter at the same time, you get a data race.

That's why Rc<T> is !Send, moving it doesn't actually create unique ownership of all the relevant data. There's hidden shared state (the reference counter) that remains unsafe.

So how do we fix this? How can we have reference counting that works across threads?

The solution is Arc<T> (atomic reference-counted pointer), which makes the shared reference counter thread-safe:

use std::sync::Arc;

let arc1 = Arc::new(42);
let arc2 = arc1.clone();

// This works because Arc makes the shared state thread-safe
thread::spawn(move || {
    drop(arc1); // Atomically decrements counter
});

drop(arc2); // Also atomically decrements counter

Arc solves the problem by making the reference counter atomic, multiple threads can safely increment and decrement it simultaneously without data races.

Note: Arc<T> is only Send + Sync if T is also Send + Sync. For example, Arc<Cell<T>> is not Sync because Cell<T> isn't Sync. Arc makes the counter thread-safe, but the data it contains still depends on the inner type's thread safety properties. I won't dive too deep into this in this post—let me know in the comments if you'd like a dedicated post about it.

Note: There's another category of !Send types with thread-local constraints (like MutexGuard<T>), but Rc<T>-style shared state is the most common case you'll encounter.

The refined model for Send:

- If moving creates true unique ownership (no hidden shared state) → Send

- If moving still leaves shared state that isn't thread-safe → !Send

- If moving leaves shared state that is thread-safe → Send

Now that we understand the underlying principles, let's turn these insights into a practical decision-making tool.

Practical Decision Tree: Is Type X Send/Sync?

Instead of memorizing every type's Send/Sync status, you can reason through it systematically. Here's the mental framework I use, built from the principles we just explored:

Pro tip: You can always double-check by trying to use the type across threads. The compiler will tell you if it's not Send/Sync with a clear error message!

Key Takeaway

Here's the mental model that makes Send and Sync predictable:

They're Rust's way of encoding thread safety into the type system.

• Send asks: "Can I move this to another thread without creating hidden shared state that isn't thread-safe?"

• Sync asks: "Can multiple threads hold references to this without racing on mutations?"

When you think about it this way, the traits become logical rather than arbitrary. Rc<T> isn't Send because moving it still leaves shared (non-atomic) state with the original thread. Cell<T> isn't Sync because it allows unsynchronized mutation through shared references.

Once you internalize this mental model, you'll find yourself correctly predicting a type's Send/Sync status just by understanding what the type does. And when you design your own types, you'll naturally think about thread safety from the ground up.

What I didn't cover

This post focused on the most common Send/Sync patterns. There are edge cases like MutexGuard<T> (which is !Send due to thread-local constraints, not shared state) and raw pointers, but the mental model here handles 95% of real-world cases.

If you made it this far, you're probably as obsessed with understanding how things really work as I am. I'm Cuong, and I write about Rust and programming. If you share the same passion, I'd love to connect with you—feel free to reach out on X, LinkedIn , or subscribe to my blog (substack, medium) to keep pushing the boundaries together!

The classic fix? Mock those dependencies.

In this post, you’ll learn how to mock external calls in Rust, and how to do it effectively.

First, let’s see why this problem shows up with a concrete example.

The Need for Mocking

Suppose you’re building an e-commerce backend: before restocking an item, you need to pay your supplier in Bitcoin.

Let's say the BitcoinWallet type comes from an external crate you can't edit:

pub struct BitcoinWallet;
impl BitcoinWallet {
    pub fn send(&mut self, to: &str, amount: f64) -> Result<Txid> {
        /* broadcasts a transaction */
    }
}

(Notice the send function that reaches out to the network)

Your business logic call the send function from the BitcoinWallet like this:

pub fn fill_inventory(wallet: &mut BitcoinWallet, item_id: u64, qty: u32) -> anyhow::Result<()> {
    let cost_btc = calculate_cost(item_id, qty); // calculate_cost is defined elsewhere
    wallet.send(SUPPLIER_ADDR, cost_btc)?; // interacts with network
    Ok(())
}

And here’s a test:

#[test]
fn test_fill_inventory() {
    let mut wallet = BitcoinWallet::new();
    let result = fill_inventory(&mut wallet, 1000, 5);
    assert!(result.is_ok());
}

But here’s the catch:

If you run this test, it might take forever, waiting for network confirmations, or it might fail because your test wallet is empty, or the testnet node is down, even though your logic is solid.

What you want is to simulate this call so your tests stay fast and reliable.

In this post, our mission is to test the fill_inventory function without a real Bitcoin wallet.

Mocking in Rust

Why can’t we just swap the wallet for a dummy object, like in some other languages?

• Rust doesn’t let you swap out objects at runtime (no reflection).

• Types and lifetimes are fixed at compile time.

The solution: Introduce a trait ,  so you can inject either the real wallet or a mock as needed.

The Indirection Layer

Here’s the trick:

Instead of talking directly to the external wallet, your code will use a trait. Then you implement that trait for both the real wallet (for production) and your mock (for testing).

Is there other approach?

You might see other patterns in the wild:

• Passing closures or function pointers (okay for very simple cases).

• Compiling in different modules for tests with feature flags or `cfg(test)`.

• HTTP record/replay tools (good for web APIs, but not for Bitcoin).

In real-world Rust, traits are the most flexible and reliable way to swap dependencies for testing.

How Do We Mock BitcoinWallet? (Step by Step)

For this demo, the code for BitcoinWallet is simplified.

Define the Trait and Use It for our code

pub trait BtcWallet {
    fn send(&mut self, address: &str, amount_btc: f64) -> Result<Txid>;
}

Note that we use the exact signature as the send function from the real BitcoinWallet type.

Next update your business logic to use the trait:

pub const SUPPLIER_ADDR: &str = "bc1q-supplier-addr";

pub fn fill_inventory<W: BtcWallet>(
    wallet: &mut W,
    item_id: u64,
    qty: u32,
) -> anyhow::Result<()> {
    let cost_btc = calculate_cost(item_id, qty);
    wallet.send(SUPPLIER_ADDR, cost_btc)?;
    update_inventory_db(item_id, qty)?;
    Ok(())
}

Now, let’s extend our original BitcoinWallet so it implements our trait.

Implement the Trait for the Real Wallet

use external_crate::BitcoinWallet as RealBitcoinWallet;
use anyhow::Context;

impl BtcWallet for RealBitcoinWallet {
    fn send(&mut self, address: &str, amount_btc: f64) -> Result<Txid> {
        RealBitcoinWallet::send(self, address, amount_btc)
    }
}

Look at this line: RealBitcoinWallet::send(self, address, amount_btc), we specifically call send function defined on the RealBitcoinWallet type.

Now everything works just like before, let’s create our mock wallet for testing.

Our Mock Object for Testing

#[derive(Default)]
pub struct MockBitcoinWallet {
    pub called: bool,
    pub last_addr: String,
    pub last_amt: f64,
}

impl BtcWallet for MockBitcoinWallet {
    fn send(&mut self, address: &str, amount_btc: f64) -> Result<Txid> {
        self.called = true;
        self.last_addr = address.to_owned();
        self.last_amt = amount_btc;
        Ok("mock-tx-hash".into())
    }
}

Because we use &mut self, we can track calls using simple struct fields (bool, String, f64). If we don't have a &mut self, a simple trick is to use iterior mutability types, such as: AtomicBool and Mutex.

And finally, our test can run with the mock:

#[test]
fn test_fill_inventory_calls_send() {
    let mut wallet = MockBitcoinWallet::default();
    fill_inventory(&mut wallet, 42, 3).unwrap();

    let expected = calculate_cost(42, 3);
    assert!(wallet.called);
    assert_eq!(wallet.last_addr, SUPPLIER_ADDR);
    assert!((wallet.last_amt - expected).abs() < 1e-8);
}

Pro-tip: You can check not only that a method was called, with what arguments, but you can also return different outputs to verify if your code handles cases correctly, e.g: return an error if amount is negative.

If writing these mocks by hand feels tedious, there’s a better way.

Using Mockall for Less Boilerplate

As your codebase grows, you might want to avoid writing mocks by hand. Try mockall.

First, add this to your Cargo.toml:

[dev-dependencies]
mockall = "0.13.1"

Here’s how you use it:

#[cfg_attr(test, mockall::automock)]
pub trait BtcWallet {
    fn send(&mut self, address: &str, amount_btc: f64) -> Result<Txid>;
}

#[test]
fn test_fill_inventory() {
    let mut mock = MockBtcWallet::new();
    let expected = calculate_cost(42, 3);
    mock.expect_send()
        .withf(|addr, amt| addr == SUPPLIER_ADDR && (*amt - expected).abs() < 1e-8)
        .times(1);

    fill_inventory(&mut mock, 42, 3).unwrap();
}

How does this work?

Notice the line #[cfg_attr(test, mockall::automock)]. This tells Rust: “When running in the test environment, use the mockall::automock macro to generate a mock implementation for this trait.” The macro creates a new mock type ,  MockBtcWallet ,  that implements the BtcWallet trait for you. With just this one line, you get a fully functional mock (with all the trait methods) ready for your tests.

automock is just a useful macro that mockall support to quickly create a mock type. There are plenty of useful things it exposes. Please checkout the documentation here if you need more powerful features.

When Should You Mock?

You might be wondering: Should I mock everything? The answer: mock the pain, not the world.

• Use mocks for unit tests, especially when external calls would slow down or break your tests.

• For end-to-end QA before release, use regtest/testnet or the real wallet to catch integration bugs.

• For pure calculation functions, there’s no need to mock,  just test them directly.

• If you need to check the real wallet RPC protocol, always test against the actual service at least once.

Pro-tip: If your tests are slow or flaky because of network calls, use mocks. But always keep at least one integration test that hits the real thing, just in case.

Summary

• Mocks let you test code that talks to the outside world ,  quickly and safely.

• In Rust, a trait layer lets you swap between the real wallet and a test mock.

• Hand-written mock is only for your understanding; use mockall to save time.

• Always keep a few real integration tests to catch surprises.

If you enjoyed this post or found it helpful, I'm Cuong, and I regularly write about Rust and other interesting programming topics. I'd love to connect with you, feel free to reach out on X, LinkedIn, or subscribe to my blog for more insights!

When I first started learning Rust, I kept seeing code that used String, str, &String, and &str, sometimes all in the same function. Sometimes I could pass a &String to a function that wanted a &str, and other times I had to use .to_string() just to get things to compile. Honestly, it felt pretty messy.

Let me show you what I mean:

fn print_message(msg: &str) {
    println!("{}", msg);
}

fn main() {
    let s1 = String::from("hello");
    let s2 = "world";

    print_message(&s1); // works!
    print_message(s2);  // also works!
    // print_message(s1); // error: expected `&str`, found `String`
    print_message(&s1[0..3]); // works! (a slice of s1)
}

Why does Rust let you pass some things, but not others? Why do we need so many string types? If you've ever been confused by this, you're not alone.

In this post, I'll explain why Rust strings work this way (and why it actually makes sense). Then we'll dive deeper to see what's really going on inside, right down to how these types are stored in memory.

1. What Do We Actually Need from Strings?

Let's step back and think about what we typically need strings to do:

• Create and modify strings: Imagine building a dynamic welcome message. You have the text "Welcome," and you want to add different usernames depending on who logs in.

• Efficiently borrow existing strings: Suppose you want to read a user's name directly from a configuration file or from a JSON response without making extra copies.

• Use fixed text efficiently: Consider situations like logging simple messages such as "Operation completed successfully," which remain unchanged during the program's life.

A good string type in any programming language should handle these tasks efficiently. But using just one type usually forces compromises in performance, simplicity, or safety.

Rust addresses these needs clearly by providing two separate types. But how exactly?

2. What Exactly Are String and str?

String: Owned, Flexible, Heap-Allocated Text

A String owns its data, meaning it stores text on the heap and can grow or shrink as needed.

let mut message = String::new();
message.push_str("hello");
message.push('!'); // message is now "hello!"

str: Borrowed, Read-Only Views of Text

str is known as a "string slice", an immutable view into UTF-8 text. You can't directly create or store a bare str because Rust needs to know the size of variables at compile time. That's why it's always used as &str, a borrowed reference.

let full_message = String::from("hello world");
let first_word: &str = &full_message[0..5]; // "hello"

A &str can reference text from anywhere: the heap (like a String), stack memory, or static memory embedded in your program.

To help you understand the differences between them better and when to use each one, let's peek inside, what do they look like in memory?

3. Diving Deeper: Memory Layout

Here's how these types appear internally:

Memory Layout of String:

let mut s1 = String::with_capacity(6);
s1.push_str("hello");

Memory Layout of &str:

let mut s1 = String::with_capacity(6);
s1.push_str("hello");
let s2 = &s1[..4];
let s3 = "world";

Because of this straightforward layout, Rust efficiently uses &str without extra copying or allocations.

But why exactly can you pass a &String to a function expecting a &str? Let's explore this next.

4. Why Can We Pass &String to Functions Expecting &str?

You can pass a &String to any function expecting a &str because String implements the Deref trait, targeting str. When Rust sees that you're using a &String in a place where a &str is required, it automatically and transparently calls deref to perform the conversion. Importantly, this is a zero-cost operation, no copying, no allocation, and no additional CPU instructions.

How is Deref implemented for String?

Here's the actual simplified Rust implementation:

impl Deref for String {
    type Target = str;

    fn deref(&self) -> &Self::Target {
        // SAFETY: String guarantees valid UTF-8 internally.
        unsafe { std::str::from_utf8_unchecked(&self.as_bytes()) }
    }
}

What this does is simply reinterpret the bytes inside a String as a &str. The underlying data doesn't move, change, or get copied.

Why is this truly zero-cost?

• String already stores a pointer to its data and its length. When you convert to &str, Rust simply reuses this pointer and length directly.

• No runtime overhead: Rust's compiler (and LLVM behind it) optimizes away this "conversion" entirely. The memory layout remains identical, so there's literally zero additional cost.

You can verify this yourself by printing memory addresses:

fn main() {
    let s = String::from("hello");
    let slice: &str = &s;

    println!("String data address: {:p}", s.as_ptr());
    println!("&str data address: {:p}", slice.as_ptr());
    // Both addresses will match, confirming no copying occurred.
}

Best practice: Using &str in function signatures

Even though you can use &String, you generally shouldn't. Prefer &str to ensure your functions are more versatile, handling both String and string literals seamlessly.

// Recommended
fn greet(name: &str) {
    println!("Hello, {}!", name);
}

// Less flexible (avoid)
fn greet_string(name: &String) {
    println!("Hello, {}!", name);
}

By consistently following this best practice, your Rust code becomes cleaner and more flexible.

• Rust's separation of String and str is carefully designed for speed, memory safety, and ease of use without hidden costs.

If you enjoyed this post or found it helpful, I'm Cuong, and I regularly write about Rust and other interesting programming topics. I'd love to connect with you, feel free to reach out on X, LinkedIn, or subscribe to my blog for more insights!