concurrent-data-structureslisted
Install: claude install-skill rustcircle/c101
# Concurrent data structures
Practice for shared-memory concurrency: pick the least dangerous design, get orderings right, prove it
with checkers. The theory summary stays in `cs-foundations` section 10; C++ atomics API detail in
`cpp-concurrency-atomics`; unsafe Rust soundness in `rust-unsafe-soundness`; runtimes in
`go-concurrency-context`, `java-virtual-threads`, `haskell-concurrency-stm`; replicated state across
machines in `distributed-consensus-consistency`.
Deep material: [SPSC ring buffer: full code, loom tests and benchmark](references/spsc-ring-example.md)
## 1. Decision ladder
Climb one rung only when a profile (perf, pprof mutex profile, JFR lock events) shows the current rung
is the bottleneck.
| Rung | Design | Use when | Examples |
|---|---|---|---|
| 0 | Don't share | work partitions by key, owner thread or pipeline stage | channels (`crossbeam-channel`, Go `chan`, `BlockingQueue`), per-thread state merged at the end, sharding, actors |
| 1 | One coarse lock | short critical sections, modest contention | `std::mutex`, `parking_lot::Mutex`, `sync.Mutex`, `ReentrantLock` |
| 2 | Finer locks | lock wait time dominates the profile | lock striping, per-bucket locks, `RwLock` for long read sections |
| 3 | Library concurrent structure | contention on a standard shape remains | `ConcurrentHashMap`, `DashMap`, crossbeam queues, folly, `LongAdder` |
| 4 | Custom lock-free | measured need, no library fits | only with model checking (section 9) and a second reviewer