Async Synchronization Primitives

21 min read

When several Rust tasks share mutable state, you reach for a lock — but in async code you have a choice JavaScript never forces on you: a blocking lock from the standard library, or an async-aware lock from Tokio. Picking the wrong one leads to subtle deadlocks, performance cliffs, or a confusing future cannot be sent between threads safely error. This page explains the difference and the one rule that drives the whole decision.

Quick Overview

Tokio provides async-aware versions of the standard library’s synchronization types: tokio::sync::Mutex, tokio::sync::RwLock, and tokio::sync::Semaphore. Unlike their std::sync counterparts, their locking methods are async — you write lock().await — so a task that cannot acquire the lock yields to the runtime instead of blocking the OS thread. The decisive question is whether you need to hold a lock across an .await point: if you do, you usually need the Tokio version; if you do not, the plain std::sync lock is faster and simpler.

Note: Every Rust snippet on this page was compiled and run with cargo/rustc 1.96.0 (current stable; 2024 edition). Async examples use tokio = { version = "1.52", features = ["full"] }. Rust ships no built-in async runtime, so the runtime is always explicit — see Tokio Setup.

TypeScript/JavaScript Example

JavaScript has no concept of a lock, because Node runs your code on a single thread with a cooperative event loop. Two async functions can interleave at await points, but they never truly run at the same instant, so there is no data race on a plain object. Developers instead reach for ad-hoc concurrency control like a “mutex” promise chain, or a p-limit-style semaphore to cap concurrent I/O.

1
// TypeScript / JavaScript (Node v22)
2
// There is no real shared-memory race here: the event loop is single-threaded.
3
// But we DO need to limit concurrency, and to serialize a read-modify-write
4
// that spans multiple awaits.
5

6
// A hand-rolled async mutex: each acquire() waits for the previous release().
7
class AsyncMutex {
8
  private tail: Promise<void> = Promise.resolve();
9

10
  async runExclusive<T>(fn: () => Promise<T>): Promise<T> {
11
    const prev = this.tail;
12
    let release!: () => void;
13
    this.tail = new Promise((resolve) => (release = resolve));
14
    await prev; // wait our turn
15
    try {
16
      return await fn();
17
    } finally {
18
      release(); // let the next waiter proceed
19
    }
20
  }
21
}
22

23
// A semaphore: at most `max` operations run concurrently.
24
class Semaphore {
25
  private permits: number;
26
  private waiters: Array<() => void> = [];
27
  constructor(max: number) {
28
    this.permits = max;
29
  }
30
  async acquire(): Promise<void> {
31
    if (this.permits > 0) {
32
      this.permits--;
33
      return;
34
    }
35
    await new Promise<void>((resolve) => this.waiters.push(resolve));
36
    this.permits--;
37
  }
38
  release(): void {
39
    this.permits++;
40
    this.waiters.shift()?.();
41
  }
42
}
43

44
const stats = { completed: 0, bytes: 0 };
45
const lock = new AsyncMutex();
46
const limit = new Semaphore(2);
47

48
async function download(id: number): Promise<number> {
49
  await new Promise((r) => setTimeout(r, 20));
50
  return id * 1000;
51
}
52

53
async function worker(id: number): Promise<void> {
54
  await limit.acquire();
55
  try {
56
    const bytes = await download(id);
57
    // A read-modify-write that crosses an await must be serialized.
58
    await lock.runExclusive(async () => {
59
      stats.completed += 1;
60
      stats.bytes += bytes;
61
    });
62
  } finally {
63
    limit.release();
64
  }
65
}
66

67
await Promise.all([1, 2, 3, 4, 5].map(worker));
68
console.log(stats); // { completed: 5, bytes: 15000 }

Two things to notice, because they map directly onto the Rust version:

The AsyncMutex exists to serialize an operation that spans awaits, not to prevent a CPU-level data race (Node’s single thread already prevents those).
The Semaphore exists to cap concurrency — limit how many downloads are in flight.

Rust Equivalent

Rust gives you these primitives as battle-tested library types instead of hand-rolled classes. Because tasks can run on different OS threads under Tokio’s multi-thread scheduler, the lock is also doing real memory-safety work, not just ordering.

1
// Rust — tokio::sync primitives for shared async state
2
use std::sync::Arc;
3
use tokio::sync::{Mutex, Semaphore};
4
use tokio::time::{sleep, Duration};
5

6
/// Shared, mutable counters updated by every worker.
7
struct Stats {
8
    completed: u32,
9
    bytes: u64,
10
}
11

12
async fn download(id: u32) -> u64 {
13
    sleep(Duration::from_millis(20)).await; // pretend this is a network call
14
    (id as u64) * 1000
15
}
16

17
#[tokio::main]
18
async fn main() {
19
    // At most 2 downloads may run at the same time (like the JS Semaphore).
20
    let limit = Arc::new(Semaphore::new(2));
21
    // Shared mutable state guarded by an async-aware Mutex.
22
    let stats = Arc::new(Mutex::new(Stats { completed: 0, bytes: 0 }));
23

24
    let mut handles = Vec::new();
25
    for id in 1..=5 {
26
        let limit = Arc::clone(&limit);
27
        let stats = Arc::clone(&stats);
28
        handles.push(tokio::spawn(async move {
29
            // Acquire a permit; this future waits if 2 are already running.
30
            let _permit = limit.acquire().await.unwrap();
31

32
            let bytes = download(id).await;
33

34
            // Lock the stats just long enough to update them.
35
            let mut s = stats.lock().await;
36
            s.completed += 1;
37
            s.bytes += bytes;
38
        }));
39
    }
40

41
    for h in handles {
42
        h.await.unwrap();
43
    }
44

45
    let s = stats.lock().await;
46
    println!("completed = {}, bytes = {}", s.completed, s.bytes);
47
}

Real output (Rust 1.96.0, Tokio 1.52.3):

1
completed = 5, bytes = 15000

The Arc<...> wrapping is what lets multiple tasks own a handle to the same value — that pattern has its own page, Arc + Mutex pattern. Here we focus on which lock goes inside the Arc.

Detailed Explanation

The `std` vs `tokio` lock families

For every common lock, there are two implementations:

Job	`std::sync` (blocking)	`tokio::sync` (async-aware)
Exclusive access	`std::sync::Mutex<T>`	`tokio::sync::Mutex<T>`
Many readers / one writer	`std::sync::RwLock<T>`	`tokio::sync::RwLock<T>`
Cap concurrency	(none in std)	`tokio::sync::Semaphore`

The standard library’s Mutex::lock() returns a LockGuard directly and blocks the current OS thread if the lock is taken. Tokio’s Mutex::lock() is an async fn returning a future; awaiting it suspends only the current task and lets the runtime schedule other tasks on that thread while it waits.

1
// std: synchronous, blocks the thread
2
let guard = std_mutex.lock().unwrap(); // .unwrap() because std locks can be "poisoned"
3

4
// tokio: asynchronous, yields the task
5
let guard = tokio_mutex.lock().await;  // no Result — tokio locks are not poisoned

Tip: A small but real ergonomic difference: std::sync::Mutex::lock() returns a Result because a std lock becomes poisoned if a thread panics while holding it. tokio::sync::Mutex::lock() returns the guard directly — Tokio locks are not poisonable — so there is no .unwrap().

The one rule: holding a guard across `.await`

This is the heart of the page. A std::sync::MutexGuard is not Send — it cannot be moved to another thread. A Tokio task may be paused at an .await and resumed on a different worker thread. So if you hold a std guard across an .await, the compiler refuses to let that future be spawned, with a future cannot be sent between threads safely error (shown in Common Pitfalls).

The decision tree is therefore:

Do you keep the lock locked while you .await something? → use tokio::sync::Mutex / RwLock.
Do you only lock, touch the data, and unlock — with no .await in between? → use std::sync::Mutex. It is faster and avoids dragging async machinery into a tiny critical section.

Why `std` locks are often the better choice

It is a common misconception that “async code must use async locks everywhere.” In fact, for a short critical section that does no .await, std::sync::Mutex is the idiomatic and faster choice — even Tokio’s own documentation recommends it. The async Mutex carries extra bookkeeping (a wait queue of tasks) and lets the task yield, which is pure overhead if you never actually need to yield while holding the lock.

1
// std: drop the guard in a tight scope BEFORE any .await
2
use std::sync::{Arc, Mutex};
3
use tokio::time::{sleep, Duration};
4

5
#[tokio::main]
6
async fn main() {
7
    let data = Arc::new(Mutex::new(0_u32));
8
    let d = Arc::clone(&data);
9
    let handle = tokio::spawn(async move {
10
        // Compute under the lock, then release it before awaiting.
11
        {
12
            let mut guard = d.lock().unwrap();
13
            *guard += 1;
14
        } // guard dropped here — lock released
15

16
        sleep(Duration::from_millis(10)).await; // no lock held across await
17
    });
18
    handle.await.unwrap();
19
    println!("{}", *data.lock().unwrap());
20
}

Real output:

1
1

The explicit { ... } scope is the workhorse pattern: it forces the guard’s Drop (which releases the lock) to run before the .await, keeping the future Send.

`RwLock`: many readers, one writer

When reads vastly outnumber writes (a config map, a cache index), an RwLock lets many readers proceed concurrently and only serializes writers.

1
use std::sync::Arc;
2
use tokio::sync::RwLock;
3

4
#[tokio::main]
5
async fn main() {
6
    let config = Arc::new(RwLock::new(vec!["a".to_string()]));
7

8
    // Many readers can hold the read lock at once.
9
    let r1 = Arc::clone(&config);
10
    let reader = tokio::spawn(async move {
11
        let guard = r1.read().await;
12
        guard.len()
13
    });
14

15
    // A single writer needs exclusive access.
16
    {
17
        let mut guard = config.write().await;
18
        guard.push("b".to_string());
19
    }
20

21
    println!("reader saw len in [1,2]: {}", reader.await.unwrap());
22
    println!("final len = {}", config.read().await.len());
23
}

Real output:

1
reader saw len in [1,2]: 2
2
final len = 2

Note: The reader’s result is 1 or 2 depending on whether it ran before or after the writer — both are correct. The point is that read().await and write().await coordinate access; you never observe a torn, half-written Vec.

`Semaphore`: capping concurrency

A Semaphore hands out a fixed number of permits. A task calls acquire().await; if no permit is free, the task waits. When the returned permit is dropped, a permit is returned to the pool. This is the direct analog of the JavaScript p-limit / hand-rolled semaphore above, and std has no equivalent.

1
use std::sync::Arc;
2
use tokio::sync::Semaphore;
3
use tokio::time::{sleep, Duration};
4

5
#[tokio::main]
6
async fn main() {
7
    let sem = Arc::new(Semaphore::new(2)); // 2 concurrent permits
8
    let mut handles = Vec::new();
9
    for id in 1..=4 {
10
        let sem = Arc::clone(&sem);
11
        handles.push(tokio::spawn(async move {
12
            let _permit = sem.acquire().await.unwrap();
13
            println!("task {id} acquired permit");
14
            sleep(Duration::from_millis(10)).await;
15
            println!("task {id} releasing permit");
16
            // _permit dropped at end of scope -> permit returned
17
        }));
18
    }
19
    for h in handles {
20
        h.await.unwrap();
21
    }
22
}

Real output (one possible interleaving):

1
task 1 acquired permit
2
task 2 acquired permit
3
task 2 releasing permit
4
task 1 releasing permit
5
task 3 acquired permit
6
task 4 acquired permit
7
task 4 releasing permit
8
task 3 releasing permit

Notice that tasks 3 and 4 do not even start their work until 1 and 2 release their permits — exactly two run at a time.

Key Differences

Concept	TypeScript / JavaScript (Node)	Rust + Tokio
Need for locks at all	No data races (single-threaded event loop); locks only order async ops	Real shared-memory concurrency across worker threads; locks enforce safety
Built-in mutex	None (hand-rolled or `async-mutex` / `p-limit` npm packages)	`std::sync::Mutex` and `tokio::sync::Mutex` in the standard toolset
Acquire semantics	`await` a promise chain	`.lock().await` (async) or `.lock().unwrap()` (blocking)
Holding across `await`	Always fine — same thread	Fine with `tokio` lock; a compile error with `std` lock (`!Send` guard)
Releasing the lock	Manual `release()` in a `finally`	Automatic — the guard’s `Drop` releases it (RAII), no `finally` needed
Read/write split	Not built in	`tokio::sync::RwLock` (and `std::sync::RwLock`)
Concurrency cap	`p-limit` / hand-rolled	`tokio::sync::Semaphore`
Poisoning	N/A	`std` locks poison on panic (returns `Result`); `tokio` locks do not

The deepest conceptual difference is RAII release: there is no release() to forget. The lock is tied to the lifetime of the guard value. When the guard goes out of scope, the lock is freed — which is precisely why “scope the guard” is the fix for the across-await problem.

Warning: “Use tokio::sync::Mutex because I’m in async code” is a reflex worth resisting. The right reflex is: do I .await while holding it? If not, std::sync::Mutex is the leaner, faster, idiomatic choice. See async vs sync for the broader “when is async even the right tool” discussion.

Common Pitfalls

Pitfall 1: Holding a `std` guard across `.await`

This is the error nearly every TypeScript/JavaScript developer hits first. It looks innocent:

1
// does not compile (future cannot be sent between threads safely)
2
use std::sync::{Arc, Mutex};
3
use tokio::time::{sleep, Duration};
4

5
#[tokio::main]
6
async fn main() {
7
    let data = Arc::new(Mutex::new(0_u32));
8
    let d = Arc::clone(&data);
9
    let handle = tokio::spawn(async move {
10
        let mut guard = d.lock().unwrap();       // std::sync::MutexGuard
11
        sleep(Duration::from_millis(10)).await;  // held across .await — !Send
12
        *guard += 1;
13
    });
14
    handle.await.unwrap();
15
    println!("{}", *data.lock().unwrap());
16
}

The real cargo build error:

1
error: future cannot be sent between threads safely
2
   --> src/bin/std_across_await.rs:9:18
3
    |
4
  9 |       let handle = tokio::spawn(async move {
5
    |  __________________^
6
 10 | |         let mut guard = d.lock().unwrap(); // std::sync::MutexGuard
7
 11 | |         sleep(Duration::from_millis(10)).await; // hold the guard across .await
8
 12 | |         *guard += 1;
9
 13 | |     });
10
    | |______^ future created by async block is not `Send`
11
    |
12
    = help: within `{async block@src/bin/std_across_await.rs:9:31: 9:41}`, the trait `Send` is not implemented for `std::sync::MutexGuard<'_, u32>`
13
note: future is not `Send` as this value is used across an await
14
   --> src/bin/std_across_await.rs:11:42
15
    |
16
 10 |         let mut guard = d.lock().unwrap();
17
    |             --------- has type `std::sync::MutexGuard<'_, u32>` which is not `Send`
18
 11 |         sleep(Duration::from_millis(10)).await;
19
    |                                          ^^^^^ await occurs here, with `mut guard` maybe used later
20
note: required by a bound in `tokio::spawn`

Two valid fixes:

Drop the guard before the .await by scoping it (shown earlier) — keeps the cheap std lock.
Switch to tokio::sync::Mutex, whose guard is Send, when you genuinely must stay locked across the .await:

1
// tokio::sync::Mutex guard is Send, so holding across .await compiles
2
use std::sync::Arc;
3
use tokio::sync::Mutex;
4
use tokio::time::{sleep, Duration};
5

6
#[tokio::main]
7
async fn main() {
8
    let data = Arc::new(Mutex::new(0_u32));
9
    let d = Arc::clone(&data);
10
    let handle = tokio::spawn(async move {
11
        let mut guard = d.lock().await;          // tokio MutexGuard IS Send
12
        sleep(Duration::from_millis(10)).await;  // OK to hold across .await
13
        *guard += 1;
14
    });
15
    handle.await.unwrap();
16
    println!("{}", *data.lock().await);
17
}

Real output: 1.

Pitfall 2: Locking the same lock twice in one task (self-deadlock)

Unlike Node, where there is no real lock to deadlock on, a Tokio Mutex is not reentrant. If a task holds the guard and then tries to lock the same mutex again, it waits forever — the permit it is waiting for is held by itself.

1
use tokio::sync::Mutex;
2
use tokio::time::{timeout, Duration};
3

4
#[tokio::main]
5
async fn main() {
6
    let m = Mutex::new(0);
7
    let _g1 = m.lock().await;
8
    // Second lock on the SAME mutex while _g1 is alive -> blocks forever.
9
    // The timeout wrapper lets the demo terminate instead of hanging.
10
    let res = timeout(Duration::from_millis(50), m.lock()).await;
11
    match res {
12
        Ok(_) => println!("acquired again (unexpected)"),
13
        Err(_) => println!("timed out: second lock() never succeeded (self-deadlock)"),
14
    }
15
}

Real output:

1
timed out: second lock() never succeeded (self-deadlock)

The fix is to restructure so the lock is acquired once, or release the first guard (drop(_g1)) before locking again.

Pitfall 3: Trusting the compiler to catch every across-`await` hold

The !Send error only fires when the future must be Send — for example when you tokio::spawn it. On a current-thread runtime, or for a future that never crosses a thread boundary, holding a std guard across .await compiles but is still a latent deadlock risk and almost always a bug. Clippy’s await_holding_lock lint catches it regardless:

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

4
async fn bump(m: &Mutex<u32>) {
5
    let mut g = m.lock().unwrap();
6
    sleep(Duration::from_millis(1)).await; // holding std guard across await
7
    *g += 1;
8
}

Real cargo clippy warning:

1
warning: this `MutexGuard` is held across an await point
2
 --> src/bin/clippy_hold.rs:5:9
3
  |
4
5 |     let mut g = m.lock().unwrap();
5
  |         ^^^^^
6
  |
7
  = help: consider using an async-aware `Mutex` type or ensuring the `MutexGuard` is dropped before calling `await`
8
note: these are all the await points this lock is held through
9
 --> src/bin/clippy_hold.rs:6:37
10
  |
11
6 |     sleep(Duration::from_millis(1)).await; // holding std guard across await
12
  |                                     ^^^^^
13
  = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#await_holding_lock
14
  = note: `#[warn(clippy::await_holding_lock)]` on by default

Tip: Run cargo clippy in CI. The await_holding_lock lint is on by default and is your best defense against the latent (non-spawned) version of Pitfall 1.

Pitfall 4: Reaching for a lock when an atomic or channel is simpler

A Mutex<u64> counter incremented under a lock works, but for a single integer an AtomicU64 (no lock at all) or a tokio::sync::mpsc channel (no shared mutable state at all) is often clearer and faster. Locks are not the only tool — see Channels for the “share by communicating” alternative.

Best Practices

Default to std::sync::Mutex/RwLock for non-await critical sections. Only reach for tokio::sync locks when you must hold the guard across an .await. This is Tokio’s own recommendation.
Keep critical sections tiny. Compute outside the lock; lock only to read or commit the result. A long critical section serializes your tasks and erases the benefit of async.
Use an explicit { } scope (or drop(guard)) to release a guard before an .await when using a std lock.
Prefer RwLock only when reads dominate and writes are rare. For balanced or write-heavy access, a plain Mutex is simpler and frequently faster (an RwLock has more bookkeeping).
Use Semaphore for backpressure / concurrency limits, e.g. capping simultaneous outbound HTTP requests or database connections.
For spawned tasks, prefer the owned variants — Mutex::lock_owned, Semaphore::acquire_owned — to sidestep guard-lifetime issues with 'static futures:

1
use std::sync::Arc;
2
use tokio::sync::Semaphore;
3

4
#[tokio::main]
5
async fn main() {
6
    let sem = Arc::new(Semaphore::new(1));
7
    let sem2 = Arc::clone(&sem);
8
    let handle = tokio::spawn(async move {
9
        // acquire_owned consumes the Arc clone -> an owned permit with no borrow.
10
        let _permit = sem2.acquire_owned().await.unwrap();
11
        "did work"
12
    });
13
    println!("{}", handle.await.unwrap());
14
    println!("available permits = {}", sem.available_permits());
15
}

Real output:

1
did work
2
available permits = 1

Run cargo clippy to catch held-across-await guards that the type checker lets slip on current-thread runtimes.
Never hold two locks in different orders across tasks — that is the classic lock-ordering deadlock, identical to the threaded-Rust case.

Real-World Example

A small client that fetches user records from a slow “API”, caches them behind an RwLock (many concurrent readers, occasional writers), and throttles outbound calls with a Semaphore so it never makes more than MAX_INFLIGHT requests at once. This is the production-flavored combination of all three primitives.

1
use std::collections::HashMap;
2
use std::sync::Arc;
3
use tokio::sync::{RwLock, Semaphore};
4
use tokio::time::{sleep, Duration};
5

6
/// Fetches user records, caches them, and rate-limits concurrent requests.
7
#[derive(Clone)]
8
struct UserClient {
9
    cache: Arc<RwLock<HashMap<u32, String>>>,
10
    limiter: Arc<Semaphore>,
11
}
12

13
const MAX_INFLIGHT: usize = 3;
14

15
impl UserClient {
16
    fn new() -> Self {
17
        UserClient {
18
            cache: Arc::new(RwLock::new(HashMap::new())),
19
            limiter: Arc::new(Semaphore::new(MAX_INFLIGHT)),
20
        }
21
    }
22

23
    async fn fetch_remote(id: u32) -> String {
24
        sleep(Duration::from_millis(20)).await; // simulate network latency
25
        format!("user#{id}")
26
    }
27

28
    async fn get(&self, id: u32) -> String {
29
        // Fast path: a read lock lets many tasks check the cache concurrently.
30
        if let Some(name) = self.cache.read().await.get(&id) {
31
            return name.clone();
32
        }
33

34
        // Slow path: throttle concurrent network calls with the semaphore.
35
        let _permit = self.limiter.acquire().await.unwrap();
36
        let name = Self::fetch_remote(id).await;
37

38
        // Take the write lock only briefly to insert the result.
39
        self.cache.write().await.insert(id, name.clone());
40
        name
41
    }
42
}
43

44
#[tokio::main]
45
async fn main() {
46
    let client = UserClient::new();
47

48
    // Ten concurrent lookups over four distinct ids.
49
    let mut handles = Vec::new();
50
    for i in 0..10 {
51
        let client = client.clone();
52
        let id = (i % 4) + 1;
53
        handles.push(tokio::spawn(async move { client.get(id).await }));
54
    }
55

56
    let mut results: Vec<String> = Vec::new();
57
    for h in handles {
58
        results.push(h.await.unwrap());
59
    }
60
    results.sort();
61
    results.dedup();
62
    println!("distinct users fetched: {:?}", results);
63
    println!("cache size: {}", client.cache.read().await.len());
64
}

Real output:

1
distinct users fetched: ["user#1", "user#2", "user#3", "user#4"]
2
cache size: 4

Note how the locks are held across .await here (the read lock spans the .get(), the write lock spans the .insert()) — which is exactly why these are tokio::sync locks and not std ones. The Semaphore guarantees at most three fetch_remote calls overlap, regardless of how many of the ten tasks miss the cache.

Note: A subtle real-world refinement (omitted for clarity) is the “double-check after acquiring the permit”: between the cache miss and getting the permit, another task may have populated the cache. Production code often re-reads the cache after acquire().await to avoid duplicate fetches — an instance of the classic check-then-act race.

Exercises

Exercise 1

Difficulty: Beginner

Objective: Use a std::sync::Mutex correctly inside spawned async tasks by keeping the lock out of any .await.

Instructions: Create an Arc<Mutex<u64>> total. Spawn four tasks; each first sleeps (an .await), then adds its own number (1 through 4) to the total. Make sure the program compiles (no across-await hold) and prints total = 10.

Solution

1
use std::sync::{Arc, Mutex};
2
use tokio::time::{sleep, Duration};
3

4
#[tokio::main]
5
async fn main() {
6
    let total = Arc::new(Mutex::new(0_u64));
7
    let mut handles = Vec::new();
8
    for i in 1..=4 {
9
        let total = Arc::clone(&total);
10
        handles.push(tokio::spawn(async move {
11
            sleep(Duration::from_millis(5)).await; // await BEFORE locking
12
            let mut g = total.lock().unwrap();      // lock, no await while held
13
            *g += i;                                 // guard dropped at scope end
14
        }));
15
    }
16
    for h in handles {
17
        h.await.unwrap();
18
    }
19
    println!("total = {}", *total.lock().unwrap());
20
}

Real output:

1
total = 10

The .await happens before the lock is taken, so the std MutexGuard never lives across an await point — the future stays Send and tokio::spawn accepts it.

Exercise 2

Difficulty: Intermediate

Objective: Use a tokio::sync::RwLock to coordinate concurrent writers and readers over a shared counter.

Instructions: Create an Arc<RwLock<u64>> hit counter. Spawn five writer tasks that each take the write lock and increment by 1. After they all finish, spawn three reader tasks that take the read lock and return the value; assert each reads 5. Print the final value.

Solution

1
use std::sync::Arc;
2
use tokio::sync::RwLock;
3

4
#[tokio::main]
5
async fn main() {
6
    let hits = Arc::new(RwLock::new(0_u64));
7

8
    // Five concurrent writers each increment once.
9
    let mut writers = Vec::new();
10
    for _ in 0..5 {
11
        let hits = Arc::clone(&hits);
12
        writers.push(tokio::spawn(async move {
13
            let mut w = hits.write().await;
14
            *w += 1;
15
        }));
16
    }
17
    for w in writers {
18
        w.await.unwrap();
19
    }
20

21
    // Three concurrent readers all share the read lock.
22
    let mut readers = Vec::new();
23
    for _ in 0..3 {
24
        let hits = Arc::clone(&hits);
25
        readers.push(tokio::spawn(async move { *hits.read().await }));
26
    }
27
    for r in readers {
28
        assert_eq!(r.await.unwrap(), 5);
29
    }
30
    println!("final hits = {}", *hits.read().await);
31
}

Real output:

1
final hits = 5

The writers serialize (each needs exclusive write() access), so all five increments land. The readers run after the writers and can share the read lock, all observing the final value.

Exercise 3

Difficulty: Advanced

Objective: Use a tokio::sync::Semaphore to cap concurrency, and prove the cap holds by tracking the maximum number of simultaneously running tasks.

Instructions: With a semaphore of limit 2, spawn six tasks. Each acquires an owned permit (acquire_owned), increments a shared AtomicUsize “current” counter, updates an AtomicUsize “max seen” with fetch_max, sleeps briefly, then decrements “current”. After all tasks finish, print the maximum concurrency observed and assert it never exceeded 2.

Solution

1
use std::sync::atomic::{AtomicUsize, Ordering};
2
use std::sync::Arc;
3
use tokio::sync::Semaphore;
4
use tokio::time::{sleep, Duration};
5

6
#[tokio::main]
7
async fn main() {
8
    const LIMIT: usize = 2;
9
    let sem = Arc::new(Semaphore::new(LIMIT));
10
    let current = Arc::new(AtomicUsize::new(0));
11
    let max_seen = Arc::new(AtomicUsize::new(0));
12

13
    let mut handles = Vec::new();
14
    for _ in 0..6 {
15
        let sem = Arc::clone(&sem);
16
        let current = Arc::clone(&current);
17
        let max_seen = Arc::clone(&max_seen);
18
        handles.push(tokio::spawn(async move {
19
            let _permit = sem.acquire_owned().await.unwrap();
20
            let now = current.fetch_add(1, Ordering::SeqCst) + 1;
21
            max_seen.fetch_max(now, Ordering::SeqCst);
22
            sleep(Duration::from_millis(10)).await;
23
            current.fetch_sub(1, Ordering::SeqCst);
24
            // _permit dropped here -> a permit is returned
25
        }));
26
    }
27
    for h in handles {
28
        h.await.unwrap();
29
    }
30
    println!("max concurrent = {}", max_seen.load(Ordering::SeqCst));
31
    println!(
32
        "never exceeded limit: {}",
33
        max_seen.load(Ordering::SeqCst) <= LIMIT
34
    );
35
}

Real output:

1
max concurrent = 2
2
never exceeded limit: true

acquire_owned returns a permit that owns its slice of the semaphore with no borrow lifetime, so it can live inside a 'static spawned task. The AtomicUsize counters (no lock needed for a single integer) record that at most two tasks ever held a permit at once.

Async Synchronization Primitives

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

The std vs tokio lock families

The one rule: holding a guard across .await

Why std locks are often the better choice

RwLock: many readers, one writer

Semaphore: capping concurrency

Key Differences

Common Pitfalls

Pitfall 1: Holding a std guard across .await

Pitfall 2: Locking the same lock twice in one task (self-deadlock)

Pitfall 3: Trusting the compiler to catch every across-await hold

Pitfall 4: Reaching for a lock when an atomic or channel is simpler

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1

Exercise 2

Exercise 3

The `std` vs `tokio` lock families

The one rule: holding a guard across `.await`

Why `std` locks are often the better choice

`RwLock`: many readers, one writer

`Semaphore`: capping concurrency

Pitfall 1: Holding a `std` guard across `.await`

Pitfall 3: Trusting the compiler to catch every across-`await` hold