r3bl-open-core: Skill for Claude Code

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.