Rust Concurrency Primitives

Use this skill to design thread-based Rust concurrency with explicit ownership, sharing, and synchronization. Prefer the simplest primitive that matches the coordination requirement before adding shared mutable state.

Core Workflow

1. Classify the work: independent fork-join, producer/consumer pipeline, shared

state, one-time initialization, or low-level atomic coordination.

1. Prefer owned data per thread. Add shared ownership only when data must be

observed or mutated by multiple threads.

1. Use std::thread::scope when child threads can borrow stack data and must

finish before the function returns.

1. Use channels for ownership transfer and pipelines. Use Arc<Mutex<T>> or

Arc<RwLock<T>> only when shared state is the clearer model.

1. Keep lock scopes short and never call user-controlled or blocking code while

holding a lock unless that is the invariant being protected.

1. Use OnceLock or LazyLock for thread-safe one-time initialization instead

of ad hoc global mutable state.

1. Treat atomics as a specialized tool. Use SeqCst by default until a weaker

ordering is justified and documented.

Primitive Selection

Read references/threading-shared-state.md before introducing a new shared state primitive or reviewing deadlock-prone code.

| Need | Primitive | |------|-----------| | Borrow local data into short-lived threads | std::thread::scope | | Transfer work or results | std::sync::mpsc or project channel crate | | Shared read/write state | Arc<Mutex<T>> | | Many readers, rare writers | Arc<RwLock<T>> | | Wait for condition changes | Condvar with Mutex | | One-time global initialization | LazyLock or OnceLock | | Counters, flags, lock-free coordination | std::sync::atomic |

Safety And Review Rules

• Require Send for values crossing thread boundaries and Sync for shared

references used from multiple threads.

• Decide whether poisoning should propagate panic or recover with

PoisonError::into_inner.

• Establish a lock ordering when more than one lock can be acquired.
• Prefer Arc::clone(&value) over value.clone() when the cloned value is an

ownership handle and readability matters.

• Use Rayon for data parallel iteration when the problem is pure CPU data

parallelism and the project already accepts that dependency.

Tests

• Add deterministic tests around final state, message counts, and shutdown.
• Use barriers, channels, or scoped threads to coordinate tests; avoid sleeps.
• Add at least one test for panic, dropped sender/receiver, or cancellation

behavior when the code depends on it.