跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

rust-concurrency

Pick the concurrency model from the workload shape — rayon for data parallelism, scoped threads for borrowed stack data, channels for handoff, shared state last — and use the weakest correct atomic ordering. Use when writing or reviewing threaded Rust, when Mutex, RwLock, atomics, or manual Send/Sync appear, when a deadlock or data race is suspected, or when the user asks how to parallelize Rust code.

rewrite-rs · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add rewrite-rs/skills --skill rust-concurrency

技能说明


name: rust-concurrency description: Pick the concurrency model from the workload shape — rayon for data parallelism, scoped threads for borrowed stack data, channels for handoff, shared state last — and use the weakest correct atomic ordering. Use when writing or reviewing threaded Rust, when Mutex, RwLock, atomics, or manual Send/Sync appear, when a deadlock or data race is suspected, or when the user asks how to parallelize Rust code.

Rust Concurrency

The shape of the workload picks the model. This skill owns that pick for threads, and it stops where task concurrency begins — runtime, executors, spawn_blocking, and cancellation live in /async-rust.

The shape picks the model

  • The same operation over many independent items: data parallelism, rayon.
  • Independent units of work that are mostly waiting: task concurrency, /async-rust, not here.
  • State several threads read and write: shared state — the one to reach for last, because it is the only one of the three that can deadlock.

Data parallelism

par_iter() is a one-word change to an iterator chain that already exists — exactly why the chain was worth writing. The precondition: the per-item work has to be large enough to pay for the scheduling. A par_iter over a million cheap closures is often slower, and is the standard disappointment.

Scoped threads

std::thread::scope lets a thread borrow stack data, because the scope guarantees the join before the stack unwinds — which is what removes the 'static bound that otherwise forces an Arc:

fn sum_halves(data: &[u64]) -> u64 {
    let (left, right) = data.split_at(data.len() / 2);
    std::thread::scope(|s| {
        let a = s.spawn(|| left.iter().sum::<u64>());
        let b = s.spawn(|| right.iter().sum::<u64>());
        a.join().unwrap() + b.join().unwrap()
    })
}

Reach for a scope before an Arc or a clone buys the second thread.

Channels for handoff

A channel moves ownership with the message — no lock to hold, nothing to poison. Sender-drop is the shutdown signal: recv reports disconnection. Bounded versus unbounded is backpressure: an unbounded channel silently converts a throughput problem into a memory problem.

Shared state

The compiler's guarantee is narrower than it feels: Send, Sync, and the borrow checker rule out data races in safe code. They do not rule out deadlocks, nor logic races — two threads each doing a correct step in an order the program did not intend. Message passing sidesteps most of this, so it is the first choice before a lock.

Mutex is the default; RwLock pays off only with genuinely read-heavy access, and can starve writers. Rules for using a lock well:

  • Put data whose parts must stay consistent with each other under one lock. Two locks for two halves of one invariant let another thread see them out of sync.
  • Hold the guard for the shortest possible scope, and never across a call into code that might lock again. That includes invoking a closure or callback while the guard is live: the caller decides what it does.
  • Do not return a MutexGuard to a caller. It leaks the locking discipline across an API boundary; return the value, or take a closure that runs inside the lock.
  • If two locks must be held together, take them in one agreed order. Fall back to a written lock hierarchy only once restructuring to need one lock, or none, has failed.

A Mutex whose holder panicked is poisoned, and lock() hands back an Err. Three positions exist, and which applies depends on what the protected data looks like after the panic:

PositionWhen it applies
Propagate the error, or recover with into_inner() and a written reasonThe default. The holder panicked, but the data is still consistent (a counter, a cache that can be rebuilt); say so in a comment
Never touch the data behind a poisoned lockThe stricter line, for state where a half-finished update could be mistaken for a good one
Panic on poison (lock().unwrap(), expect)A deliberate stop when the state cannot be trusted and nothing can repair it. Write the reason; it is a decision, not a shortcut

What is ruled out is the reflexive unwrap that was never weighed.

Libraries and threads

Library code does not start threads of its own. Spawning is a program-level decision about cost and shutdown; a library that does it hides threads from the caller and cannot be embedded in a runtime or sandbox that forbids them. Take a closure, an executor handle, or run work on the caller's thread, and let the binary decide.

Atomics and orderings

The rule: Relaxed for a counter nobody synchronises on, Acquire/Release for a paired handoff where one thread publishes and another observes, SeqCst when unsure and the cost is acceptable. The pair is the one that is wrong most often:

use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::Arc;

fn main() {
    let value = Arc::new(AtomicU64::new(0));
    let ready = Arc::new(AtomicBool::new(false));
    let (v, r) = (Arc::clone(&value), Arc::clone(&ready));
    let publisher = std::thread::spawn(move || {
        v.store(42, Ordering::Relaxed);
        r.store(true, Ordering::Release);
    });
    while !ready.load(Ordering::Acquire) {
        std::thread::yield_now();
    }
    assert_eq!(value.load(Ordering::Relaxed), 42);
    publisher.join().unwrap();
}

The Release store orders the write to value before ready flips, and the Acquire load pairs with it. If the ordering argument cannot be written down in two sentences, the code wants a Mutex.

Manual Send/Sync is an unsafe claim

unsafe impl Send for T asserts what the compiler could not prove; the // SAFETY: comment must hold an actual argument. The soundness review goes to /unsafe-rust — this skill only insists the claim is written. It is never a way to silence a Send bound error that the code really violates; fix the data cros

阅读完整来源 ↗