Arc<Mutex>

Guides

Rust walkthroughs

← Back to all guides

What are the trade-offs between parking_lot::RwLock::read and read_recursive for allowing read re-entrancy?

RwLock::read acquires a standard read lock that will deadlock if the same thread attempts to acquire another read lock recursively, while read_recursive allows the same thread to acquire multiple read locks simultaneously by tracking recursive acquisitions. The trade-off is between correctness guarantees and convenience: read enforces strict ownership semantics that prevent accidental deadlocks from re-entrant calls, but requires careful lock ordering in callback-heavy code. read_recursive permits re-entrant read locks within the same thread, eliminating certain deadlock scenarios at the cost of weaker guarantees about lock state and the potential for holding a read lock while calling code that might deadlock elsewhere.

Standard read Lock Behavior

use parking_lot::RwLock;
 
fn standard_read_lock() {
    let lock = RwLock::new(42);
    
    // Acquire a read lock
    let read_guard = lock.read();
    
    // Access the data
    let value = *read_guard;
    println!("Value: {}", value);
    
    // Read guard automatically releases when dropped
}
 
fn standard_multiple_readers() {
    let lock = RwLock::new(vec![1, 2, 3]);
    
    // Multiple read locks can coexist
    let read1 = lock.read();
    let read2 = lock.read();
    
    // Both can read simultaneously
    println!("read1: {:?}", *read1);
    println!("read2: {:?}", *read2);
    
    drop(read1);
    drop(read2);
}

Standard read allows multiple concurrent readers but not recursive acquisition by the same thread.

The Deadlock with Recursive read Calls

use parking_lot::RwLock;
 
fn deadlock_example() {
    let lock = RwLock::new(42);
    
    let read_guard = lock.read();
    
    // This would deadlock!
    // let read_guard2 = lock.read();  // Thread already holds read lock
    
    // The thread blocks waiting for a read lock
    // But it already holds a read lock
    // Classic deadlock
}
 
fn callback_deadlock() {
    let lock = RwLock::new(vec![1, 2, 3]);
    
    fn callback(lock: &RwLock<Vec<i32>>) {
        // Callback doesn't know caller holds a read lock
        let _read = lock.read();  // Deadlock!
        // ...
    }
    
    let _read = lock.read();
    callback(&lock);  // Deadlocks because callback tries to read
}

read blocks if the current thread already holds any lock on the same RwLock.

Using read_recursive for Re-entrancy

use parking_lot::RwLock;
 
fn recursive_read_lock() {
    let lock = RwLock::new(42);
    
    let read_guard1 = lock.read_recursive();
    
    // This works! Same thread can acquire additional read locks
    let read_guard2 = lock.read_recursive();
    
    // Both guards are valid
    println!("Value: {}", *read_guard1);
    println!("Value: {}", *read_guard2);
    
    // Guards can be dropped in any order
    drop(read_guard1);
    drop(read_guard2);
}

read_recursive allows the same thread to acquire multiple read locks.

Practical Callback Scenario

use parking_lot::RwLock;
 
struct Cache {
    data: RwLock<Vec<String>>,
}
 
impl Cache {
    fn process_with_callback<F>(&self, callback: F) 
    where
        F: Fn(&[String]),
    {
        let data = self.data.read_recursive();  // Use recursive
        callback(&data);
    }
    
    fn get_and_process(&self) {
        let data = self.data.read_recursive();
        
        // If callback also tries to read, it works with read_recursive
        self.process_with_callback(|items| {
            // This would deadlock with regular read()
            // But works with read_recursive()
            let inner = self.data.read_recursive();
            println!("Inner: {:?}", *inner);
        });
    }
}
 
fn callback_chain() {
    let cache = Cache {
        data: RwLock::new(vec!["a".to_string(), "b".to_string()]),
    };
    
    // With read_recursive, nested calls work
    cache.get_and_process();
}

read_recursive solves callback-related deadlock scenarios.

Recursive Lock Counting

use parking_lot::RwLock;
 
fn recursive_counting() {
    let lock = RwLock::new(0);
    
    // RwLock tracks recursion depth for read_recursive
    let _guard1 = lock.read_recursive();
    let _guard2 = lock.read_recursive();
    let _guard3 = lock.read_recursive();
    
    // Three read locks held by same thread
    // Internally tracked as recursive count
    
    // All must be dropped before write lock can be acquired
    drop(_guard1);
    drop(_guard2);
    drop(_guard3);
    
    // Now write lock can proceed
    let _write = lock.write();
}

read_recursive maintains a recursion count per thread.

Trade-off: Lock Semantics

use parking_lot::RwLock;
 
fn semantics_comparison() {
    let lock = RwLock::new(vec![1, 2, 3]);
    
    // read(): Strict ownership
    // - One read guard per thread
    // - Clear ownership boundaries
    // - Enforces at call site
    
    // read_recursive(): Relaxed ownership
    // - Multiple read guards per thread
    // - Less clear ownership boundaries
    // - Allows re-entrancy
    
    // With read(), if you need re-entrancy, you must refactor
    // With read_recursive(), re-entrancy "just works"
}

read enforces stricter ownership; read_recursive allows flexibility.

Trade-off: Potential for Confusion

use parking_lot::RwLock;
 
fn confusion_example() {
    let lock = RwLock::new(vec![1, 2, 3]);
    
    // With read_recursive, you might lose track of lock state
    fn deep_call(lock: &RwLock<Vec<i32>>, depth: usize) {
        if depth == 0 {
            return;
        }
        
        let _read = lock.read_recursive();
        println!("Depth: {}, holding read lock", depth);
        deep_call(lock, depth - 1);
        // Lock held for entire recursion
    }
    
    deep_call(&lock, 10);
    // Lock held 10 times during recursion
    // Memory overhead for tracking
    // May prevent write locks longer than expected
}

read_recursive can lead to unexpectedly long lock holdings.

Trade-off: Interaction with Write Locks

use parking_lot::RwLock;
 
fn write_interaction() {
    let lock = RwLock::new(42);
    
    // read_recursive still blocks write locks
    let read_guard = lock.read_recursive();
    
    // This would block (write waiting for all reads)
    // let write_guard = lock.write();  // Blocks
    
    // But recursive reads don't block each other
    let read_guard2 = lock.read_recursive();  // Works
    
    drop(read_guard);
    drop(read_guard2);
    
    // Now write can proceed
    let write_guard = lock.write();
}

Both read and read_recursive block write locks; the difference is re-entrancy.

Comparison with try_read

use parking_lot::RwLock;
 
fn try_variants() {
    let lock = RwLock::new(42);
    
    // try_read: Non-blocking, returns Option
    if let Some(guard) = lock.try_read() {
        println!("Got read lock: {}", *guard);
    } else {
        println!("Read lock not available");
    }
    
    // try_read_recursive: Non-blocking, allows re-entrancy
    let guard1 = lock.read_recursive();
    
    if let Some(guard2) = lock.try_read_recursive() {
        println!("Got recursive read lock");
        drop(guard2);
    }
    
    // try_read would fail here (thread already holds lock)
    assert!(lock.try_read().is_none());
    
    // But try_read_recursive succeeds
    assert!(lock.try_read_recursive().is_some());
}

try_read and try_read_recursive mirror the blocking variants' re-entrancy behavior.

Deadlock Scenarios

use parking_lot::RwLock;
use std::sync::Arc;
use std::thread;
 
fn deadlock_with_read() {
    let lock1 = Arc::new(RwLock::new(1));
    let lock2 = Arc::new(RwLock::new(2));
    
    // Thread 1: holds lock1, wants lock2
    let l1 = lock1.clone();
    let l2 = lock2.clone();
    
    let h1 = thread::spawn(move || {
        let _g1 = l1.read();
        // If another thread holds lock2...
        let _g2 = l2.read();  // Could block
    });
    
    // Thread 2: holds lock2, wants lock1
    let h2 = thread::spawn(move || {
        let _g2 = l2.read();
        let _g1 = l1.read();  // Could block
    });
    
    // Classic deadlock scenario (different from recursive)
}
 
fn recursive_deadlock_solved() {
    let lock = RwLock::new(42);
    
    let _g1 = lock.read();
    // With read(): this would deadlock
    // let _g2 = lock.read();
    
    // With read_recursive(): this works
    // Must use read_recursive consistently
    drop(_g1);
    
    let _g1 = lock.read_recursive();
    let _g2 = lock.read_recursive();  // Works
}

read_recursive solves same-thread recursion deadlocks, not cross-thread deadlocks.

Memory and Performance Considerations

use parking_lot::RwLock;
 
fn performance_comparison() {
    let lock = RwLock::new(42);
    
    // read(): Simple atomic counter increment
    // - Minimal overhead
    // - No thread-local storage
    // - Fast path for uncontended locks
    
    // read_recursive(): Thread-local tracking
    // - Tracks recursion depth per thread
    // - Slight overhead for thread-local lookup
    // - Additional state management
    
    // For most cases, the difference is negligible
    // But in tight loops, read() is slightly faster
    
    let iterations = 1_000_000;
    
    // Standard read loop
    for _ in 0..iterations {
        let _guard = lock.read();
        // Fast
    }
    
    // Recursive read loop
    for _ in 0..iterations {
        let _guard = lock.read_recursive();
        // Slightly more overhead, but still fast
    }
}

read has marginally less overhead; read_recursive tracks thread-local state.

When to Use Each

use parking_lot::RwLock;
 
fn when_to_use_read() {
    let lock = RwLock::new(vec![1, 2, 3]);
    
    // Use read() when:
    // 1. Single-threaded access pattern
    // 2. No callback-based re-entrancy
    // 3. Want strict ownership enforcement
    // 4. Performance-critical tight loops
    // 5. Simple lock patterns
    
    let _guard = lock.read();
    // Clear: one guard, one thread, strict ownership
}
 
fn when_to_use_read_recursive() {
    let lock = RwLock::new(vec![1, 2, 3]);
    
    // Use read_recursive() when:
    // 1. Callback-based APIs where callbacks need to read
    // 2. Recursive function patterns
    // 3. Complex call graphs with shared state
    // 4. Observer/event patterns
    // 5. Framework code with uncertain call patterns
    
    let _guard = lock.read_recursive();
    // Flexible: callbacks can acquire read locks
}

Choose based on call pattern complexity and ownership clarity needs.

Real-World Pattern: Observer System

use parking_lot::RwLock;
use std::collections::HashMap;
 
struct EventEmitter {
    handlers: RwLock<HashMap<String, Vec<Box<dyn Fn(&str) + Send + Sync>>>>,
}
 
impl EventEmitter {
    fn on(&self, event: &str, handler: Box<dyn Fn(&str) + Send + Sync>) {
        let mut handlers = self.handlers.write();
        handlers.entry(event.to_string()).or_default().push(handler);
    }
    
    fn emit(&self, event: &str, data: &str) {
        // Use read_recursive so handlers can also emit events
        let handlers = self.handlers.read_recursive();
        
        if let Some(callbacks) = handlers.get(event) {
            for callback in callbacks {
                callback(data);
                // If callback calls emit(), it needs to acquire read lock
                // read_recursive allows this; read() would deadlock
            }
        }
    }
}
 
fn observer_pattern() {
    let emitter = EventEmitter {
        handlers: RwLock::new(HashMap::new()),
    };
    
    emitter.on("test", Box::new(|data| {
        println!("Received: {}", data);
    }));
    
    // If a handler needs to emit another event:
    emitter.on("chain", Box::new(|data| {
        // Handler can call emit() which acquires read_recursive()
        println!("Chain: {}", data);
    }));
    
    emitter.emit("test", "hello");
}

read_recursive enables recursive event emission patterns.

Real-World Pattern: GUI Framework

use parking_lot::RwLock;
 
struct Widget {
    state: RwLock<WidgetState>,
}
 
struct WidgetState {
    children: Vec<Widget>,
    properties: HashMap<String, String>,
}
 
impl Widget {
    fn render(&self) {
        // read_recursive allows render to call into child widgets
        let state = self.state.read_recursive();
        
        // Render self
        println!("Rendering widget");
        
        // Render children (each needs its own read lock)
        for child in &state.children {
            child.render();  // This works with read_recursive
        }
    }
    
    fn update(&self) {
        let state = self.state.read_recursive();
        
        // Update might trigger re-render
        for child in &state.children {
            child.render();  // Needs read lock on child's state
        }
    }
}

GUI frameworks benefit from read_recursive for hierarchical access patterns.

Anti-Pattern: Mixing read and read_recursive

use parking_lot::RwLock;
 
fn mixing_anti_pattern() {
    let lock = RwLock::new(42);
    
    // DON'T mix read() and read_recursive() inconsistently
    let _guard1 = lock.read();
    
    // This would deadlock!
    // let _guard2 = lock.read_recursive();  // Still blocks
    
    // read_recursive() is a separate acquisition mode
    // It doesn't make read() re-entrant
    
    // Be consistent within a codebase
}
 
fn consistent_pattern() {
    let lock = RwLock::new(42);
    
    // Either use read() everywhere (strict)
    // Or read_recursive() where needed (flexible)
    
    // Consistent approach:
    let _guard1 = lock.read_recursive();
    let _guard2 = lock.read_recursive();  // Works
    
    // Or consistent approach:
    let _guard1 = lock.read();
    // let _guard2 = lock.read();  // Would deadlock if in same thread
}

Be consistent: read and read_recursive have different re-entrancy semantics.

Debugging Lock Issues

use parking_lot::RwLock;
 
fn debugging_recursive() {
    let lock = RwLock::new(vec![1, 2, 3]);
    
    // parking_lot provides deadlock detection in debug builds
    // Use parking_lot::deadlock detection for more information
    
    // With read_recursive, track how many times lock is held:
    
    fn deep_function(lock: &RwLock<Vec<i32>>, depth: usize) {
        let _read = lock.read_recursive();
        println!("At depth {}, holding lock", depth);
        
        if depth > 0 {
            deep_function(lock, depth - 1);
        }
        
        // Lock held until end of function
        println!("Exiting depth {}", depth);
    }
    
    deep_function(&lock, 5);
    // Notice: Lock held for entire call chain
    // This is visible in the output
}

Debug builds help identify lock holding duration and patterns.

Comparison Table

use parking_lot::RwLock;
 
fn comparison_table() {
    // | Feature | read() | read_recursive() |
    // |---------|--------|------------------|
    // | Re-entrant | No | Yes |
    // | Same-thread deadlock | Yes | No |
    // | Overhead | Lower | Slightly higher |
    // | Use case | Simple | Callback/re-entrant |
    // | Ownership | Strict | Relaxed |
    // | Thread tracking | No | Yes |
    // | Blocks writes | Yes | Yes |
    // | Multiple per thread | No | Yes |
}

Synthesis

Quick reference:

use parking_lot::RwLock;
 
fn quick_reference() {
    let lock = RwLock::new(42);
    
    // read(): Standard read lock
    // - Blocks if thread already holds any lock
    // - Minimal overhead
    // - Strict ownership
    let _guard = lock.read();
    
    // read_recursive(): Re-entrant read lock
    // - Allows same thread to acquire multiple times
    // - Slightly more overhead
    // - Relaxed ownership for callbacks
    
    // Use read() when:
    // - Simple, linear code paths
    // - No callback-based re-entrancy
    // - Want strict ownership enforcement
    
    // Use read_recursive() when:
    // - Callbacks might need to read same data
    // - Recursive function patterns
    // - Framework/library code with uncertain callers
    
    // Both:
    // - Block write locks while held
    // - Allow concurrent reads from different threads
    // - Require dropping before write can proceed
}

Key insight: The read_recursive method exists specifically to solve the callback re-entrancy problem—when code holding a read lock calls into code that also needs a read lock on the same data. Standard read() would deadlock because the thread already holds the lock, and the lock implementation sees itself as blocking. read_recursive() tracks a recursion count per thread, allowing the same thread to "acquire" multiple read locks without blocking itself. The trade-off is semantic: read() enforces a clear model where each thread's read acquisition has a definite scope, making lock ownership explicit. read_recursive() relaxes this model, allowing lock ownership to span multiple nested call frames. For library and framework code where you don't control the caller's behavior—particularly event systems, GUI frameworks, or plugin architectures—read_recursive() prevents entire classes of deadlocks. For application code with clear, controlled call graphs, read() provides stronger guarantees about lock state. The choice is between strictness (fail fast on re-entrancy, forcing architectural solutions) and convenience (allow re-entrancy, accepting longer lock holds).