m07-concurrency

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 | Don't Just Say | Ask Instead |

|-------|----------------|-------------|

| E0277 Send | "Add Send bound" | Should this type cross threads? |

| E0277 Sync | "Wrap in Mutex" | Is shared access really needed? |

| Future not Send | "Use spawn_local" | Is async the right choice? |

| Deadlock | "Reorder locks" | Is the locking design correct? |

---

Before adding concurrency:

1. What's the workload?

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

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

- Mixed → hybrid approach

1. What's the sharing model?

- No sharing → message passing (channels)

- Immutable sharing → Arc

- Mutable sharing → Arc> or Arc>

1. What are the Send/Sync requirements?

- Cross-thread ownership → Send

- Cross-thread references → Sync

- Single-thread async → spawn_local

---

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

Domain Detection Table

| Context Keywords | Load Domain Skill | Key Constraint |

|-----------------|-------------------|----------------|

| Web API, HTTP, axum, actix, handler | domain-web | Handlers run on any thread |

| 交易, 支付, trading, payment | domain-fintech | Audit + thread safety |

| gRPC, kubernetes, microservice | domain-cloud-native | Distributed tracing |

| CLI, terminal, clap | domain-cli | Usually single-thread OK |

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 with State extractor

↓ IMPL: axum::extract::State>

```

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?)

```

| Situation | Trace To | Question |

|-----------|----------|----------|

| Send/Sync in Web | domain-web | What's the state management pattern? |

| Send/Sync in CLI | domain-cli | Is multi-thread really needed? |

| Mutex vs channels | m09-domain | Shared state or message passing? |

| Async vs threads | m10-performance | What's the workload profile? |

---

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

"Need to share mutable data across threads"

↓ Use: Arc> or Arc>

↓ Or: channels for message passing

"Need simple atomic operations"

↓ Use: AtomicBool, AtomicUsize, etc.

```

---

| Marker | Meaning | Example |

|--------|---------|---------|

| Send | Can transfer ownership between threads | Most types |

| Sync | Can share references between threads | Arc |

| !Send | Must stay on one thread | Rc |

| !Sync | No shared refs across threads | RefCell |

| Pattern | Thread-Safe | Blocking | Use When |

|---------|-------------|----------|----------|

| std::thread | Yes | Yes | CPU-bound parallelism |

| async/await | Yes | No | I/O-bound concurrency |

| Mutex | Yes | Yes | Shared mutable state |

| RwLock | Yes | Yes | Read-heavy shared state |

| mpsc::channel | Yes | Optional | Message passing |

| Arc> | Yes | Yes | Shared mutable across threads |

```

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

└─ Mutable →

├─ Read-heavy → Arc>

└─ Write-heavy → Arc>

└─ Simple counter → AtomicUsize

Async context?

├─ Type is Send → tokio::spawn

├─ Type is !Send → spawn_local

└─ Blocking code → spawn_blocking

```

---

| Error | Cause | Fix |

|-------|-------|-----|

| E0277 Send not satisfied | Non-Send in async | Use Arc or spawn_local |

| E0277 Sync not satisfied | Non-Sync shared | Wrap with Mutex |

| Deadlock | Lock ordering | Consistent lock order |

| future is not Send | Non-Send across await | Drop before await |

| MutexGuard across await | Guard held during suspend | Scope guard properly |

---

| Anti-Pattern | Why Bad | Better |

|--------------|---------|--------|

| Arc> everywhere | Contention, complexity | Message passing |

| thread::sleep in async | Blocks executor | tokio::time::sleep |

| Holding locks across await | Blocks other tasks | Scope locks tightly |

| Ignoring deadlock risk | Hard to debug | Lock ordering, try_lock |

---

Avoid MutexGuard Across Await

```rust

// 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

```rust

// 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

```

---

| When | See |

|------|-----|

| Smart pointer choice | m02-resource |

| Interior mutability | m03-mutability |

| Performance tuning | m10-performance |

| Domain concurrency needs | domain-* |