Concurrency

Layer 1: Language Mechanics

Core Question

Is this CPU-bound or I/O-bound, and what's the sharing model?

Before choosing concurrency primitives:

• What's the workload type?

• What data needs to be shared?

• What's the thread safety requirement?

Error → Design Question

Thinking Prompt

Before adding concurrency:

-

What's the workload?

• CPU-bound → threads (std::thread, rayon)

• I/O-bound → async (tokio, async-std)

• Mixed → hybrid approach

-

What's the sharing model?

• No sharing → message passing (channels)

• Immutable sharing → Arc

• Mutable sharing → Arc<Mutex> or Arc<RwLock>

-

What are the Send/Sync requirements?

• Cross-thread ownership → Send

• Cross-thread references → Sync

• Single-thread async → spawn_local

Trace Up ↑ (MANDATORY)

CRITICAL: Don't just fix the error. Trace UP to find domain constraints.

Domain Detection Table

Example: Web API + Rc Error

"Rc cannot be sent between threads" in Web API context

    ↑ DETECT: "Web API" → Load domain-web

    ↑ FIND: domain-web says "Shared state must be thread-safe"

    ↑ FIND: domain-web says "Rc in state" is Common Mistake

    ↓ DESIGN: Use Arc<T> with State extractor

    ↓ IMPL: axum::extract::State<Arc<AppConfig>>

Generic Trace

"Send not satisfied for my type"

    ↑ Ask: What domain is this? Load domain-* skill

    ↑ Ask: Does this type need to cross thread boundaries?

    ↑ Check: m09-domain (is the data model correct?)

Trace Down ↓

From design to implementation:

"Need parallelism for CPU work"

    ↓ Use: std::thread or rayon

"Need concurrency for I/O"

    ↓ Use: async/await with tokio

"Need to share immutable data across threads"

    ↓ Use: Arc<T>

"Need to share mutable data across threads"

    ↓ Use: Arc<Mutex<T>> or Arc<RwLock<T>>

    ↓ Or: channels for message passing

"Need simple atomic operations"

    ↓ Use: AtomicBool, AtomicUsize, etc.

Send/Sync Markers

Quick Reference

Decision Flowchart

What type of work?

├─ CPU-bound → std::thread or rayon

├─ I/O-bound → async/await

└─ Mixed → hybrid (spawn_blocking)

Need to share data?

├─ No → message passing (channels)

├─ Immutable → Arc<T>

└─ Mutable →

   ├─ Read-heavy → Arc<RwLock<T>>

   └─ Write-heavy → Arc<Mutex<T>>

   └─ Simple counter → AtomicUsize

Async context?

├─ Type is Send → tokio::spawn

├─ Type is !Send → spawn_local

└─ Blocking code → spawn_blocking

Common Errors

Anti-Patterns

Async-Specific Patterns

Avoid MutexGuard Across Await

// Bad: guard held across await

let guard = mutex.lock().await;

do_async().await;  // guard still held!

// Good: scope the lock

{

    let guard = mutex.lock().await;

    // use guard

}  // guard dropped

do_async().await;

Non-Send Types in Async

// Rc is !Send, can't cross await in spawned task

// Option 1: use Arc instead

// Option 2: use spawn_local (single-thread runtime)

// Option 3: ensure Rc is dropped before .await

Related Skills