---
name: concurrency-safety
description: Concurrency safety patterns for R3BL - Chain of Custody, Loud Lock Releases, and Ergonomic Atomics. Use when working with threads, locks, or atomics.
---

# Concurrency Safety Skill

Apply these principles to ensure thread safety, prevent deadlocks, and maintain high-performance, predictable execution in multi-threaded code.

## When to Use

- Proactively when working with `Mutex`, `RwLock`, `Atomic`, or `Condvar`.
- When designing thread-safe modules like `Reactor`, `Monitor`, or `Engine`.
- When refactoring state management to use `AtomicU8Ext`.
- When troubleshooting deadlocks or race conditions.

## Core Principles

### 1. Scoped Access (Deadlock Prevention)

For simple shared state, use closure-based access to structurally prevent deadlocks by making it impossible to hold a lock guard longer than necessary.

**Guidelines:**

- **Closure-Based Access**: Restrict state access to closures. The closure's scope *is* the lock's scope.
- **Recursion Detection**: Use recursion detection (Safety-First) to prevent terminal-hanging deadlocks. Panic with a clear message if a recursive lock is detected.
- **Performance Opt-out**: For hot paths, opt-out of recursion detection at compile-time for zero overhead.
- **Fail-Fast vs. Poison-Safe**: Use Fail-Fast (panic) for normal logic, but Poison-Safe (recover) for cleanup paths to avoid Double Panic Aborts.

### 2. Chain of Custody (Guard Passing)

For complex state machines requiring `Condvar`, ensure linear ownership of locks by passing and returning `MutexGuard` by value.

**Guidelines:**

- Pass `MutexGuard` as a parameter to internal helper functions to guarantee they operate within an existing critical section.
- Return `MutexGuard` from state-reading closures (e.g., `read_state`) to force the caller to be intentional about the lock's lifetime.
- Avoid "Stale Guards" by ensuring the guard is either consumed or explicitly dropped.

### 3. Loud Lock Releases

Make critical section boundaries explicit and easy to audit by using `drop(guard)`.

**Guidelines:**

- **Explicit Release**: Always call `drop(guard)` immediately when a critical section ends, especially before function returns, macro calls, or long-running operations.
- **Auditability**: Explicit drops make it clear to reviewers (and the compiler) exactly where a lock is held, preventing accidental deadlocks during refactoring.
- **No Implicit Drops**: Do not rely on scope-based implicit drops for complex logic or when calling into external code/macros.

### 4. Friction as a Feature (Ergonomic API Design)

Design APIs that make it harder to mismanage concurrency.

**Guidelines:**

- **Type-Safe Subscriptions**: Use specific enums (like `SubscriptionStrategy`) instead of generic types to map thread states to execution paths at compile time.
- **Ergonomic Atomics**: Always use `AtomicU8Ext` (e.g., `get()`, `set()`, `increment()`) instead of raw `load()`/`store()` with manual `Ordering`.

### 5. Visibility for Documentation

Balance encapsulation with discoverability for documentation.

**Guidelines:**

- Make internal fields `pub` if they are targets of public documentation links.
- Rely on the "Barrel Export" pattern (`mod.rs` re-exports) to maintain actual module-level encapsulation while allowing `cargo doc` to resolve links correctly.

## Supporting Files

- `patterns.md` - Good and Bad examples of concurrency safety patterns.

## Related Skills

- `design-philosophy` - Core principles (Cognitive Load, Progressive Disclosure).
- `check-code-quality` - Includes concurrency safety in its final checklist.