concurrency-safety - SKILL.md Agent Skill

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.