Struct ArcMutex 

pub struct ArcMutex<T> { /* private fields */ }

Synchronous Mutex Wrapper (Parking Lot)

Provides an encapsulation of synchronous mutex using parking_lot::Mutex for protecting shared data in synchronous environments. Supports safe access and modification of shared data across multiple threads. Compared to std::sync::Mutex, parking_lot::Mutex provides better performance and more ergonomic API.

Features

• Synchronously acquires locks, may block threads
• Supports trying to acquire locks (non-blocking)
• Thread-safe, supports multi-threaded sharing
• Automatic lock management through RAII ensures proper lock release
• Better performance compared to std::sync::Mutex
• More ergonomic API with no unwrap() calls
• Implements Deref and AsRef to expose the underlying parking_lot::Mutex API when guard-based access is needed

Usage Example

use qubit_lock::{ArcMutex, Lock};

let counter = ArcMutex::new(0);

// Synchronously modify data
counter.write(|c| {
    *c += 1;
    println!("Counter: {}", *c);
});

// Try to acquire lock
if let Ok(value) = counter.try_read(|c| *c) {
    println!("Current value: {}", value);
}

Implementations

impl<T> ArcMutex<T>

pub fn new(data: T) -> ArcMutex<T>

Creates a new synchronous mutex lock

Arguments

• data - The data to be protected

Returns

Returns a new ArcMutex instance

Example

use qubit_lock::ArcMutex;

let lock = ArcMutex::new(42);

Examples found in repository

examples/double_checked_lock_executor_demo.rs (line 32)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create shared state
    let running = Arc::new(AtomicBool::new(false));
    let data = ArcMutex::new(42);

    println!("Initial state: running = {}", running.load(Ordering::Acquire));
    println!("Initial data: {}", data.read(|d| *d));

    let executor = DoubleCheckedLockExecutor::builder()
        .on(data.clone())
        .when({
            let running = running.clone();
            move || running.load(Ordering::Acquire)
        })
        .build();

    // Try to execute when service is not running (should fail)
    let result = executor
        .call_with(|value: &mut i32| {
            *value += 1;
            Ok::<_, std::io::Error>(*value)
        })
        .get_result();

    if result.is_success() {
        println!("Unexpected success: {}", result.unwrap());
    } else {
        println!("Expected failure: Condition not met.");
    }

    // Start the service
    running.store(true, Ordering::Release);
    println!("Service started: running = {}", running.load(Ordering::Acquire));

    // Now execute should succeed
    let result = executor
        .call_with(|value: &mut i32| {
            *value += 1;
            Ok::<_, std::io::Error>(*value)
        })
        .get_result();

    if result.is_success() {
        println!("Success: new value = {}", result.unwrap());
    } else {
        println!("Unexpected failure: {:?}", result);
    }

    // Verify the data was updated
    println!("Final data: {}", data.read(|d| *d));

    // Stop the service
    running.store(false, Ordering::Release);
    println!("Service stopped: running = {}", running.load(Ordering::Acquire));

    // Try to execute when service is stopped (should fail)
    let result = executor
        .call_with(|value: &mut i32| {
            *value += 1;
            Ok::<_, std::io::Error>(*value)
        })
        .get_result();

    if result.is_success() {
        println!("Unexpected success: {}", result.unwrap());
    } else {
        println!("Expected failure: Condition not met.");
    }

    Ok(())
}

Methods from Deref<Target = Mutex<RawMutex, T>>

pub unsafe fn make_guard_unchecked(&self) -> MutexGuard<'_, R, T>

Creates a new MutexGuard without checking if the mutex is locked.

Safety

This method must only be called if the thread logically holds the lock.

Calling this function when a guard has already been produced is undefined behaviour unless the guard was forgotten with mem::forget.

pub fn lock(&self) -> MutexGuard<'_, R, T>

Acquires a mutex, blocking the current thread until it is able to do so.

This function will block the local thread until it is available to acquire the mutex. Upon returning, the thread is the only thread with the mutex held. An RAII guard is returned to allow scoped unlock of the lock. When the guard goes out of scope, the mutex will be unlocked.

Attempts to lock a mutex in the thread which already holds the lock will result in a deadlock.

pub fn try_lock(&self) -> Option<MutexGuard<'_, R, T>>

Attempts to acquire this lock.

If the lock could not be acquired at this time, then None is returned. Otherwise, an RAII guard is returned. The lock will be unlocked when the guard is dropped.

This function does not block.

pub fn is_locked(&self) -> bool

Checks whether the mutex is currently locked.

pub unsafe fn force_unlock(&self)

Forcibly unlocks the mutex.

This is useful when combined with mem::forget to hold a lock without the need to maintain a MutexGuard object alive, for example when dealing with FFI.

Safety

This method must only be called if the current thread logically owns a MutexGuard but that guard has been discarded using mem::forget. Behavior is undefined if a mutex is unlocked when not locked.

pub unsafe fn raw(&self) -> &R

Returns the underlying raw mutex object.

Note that you will most likely need to import the RawMutex trait from lock_api to be able to call functions on the raw mutex.

Safety

This method is unsafe because it allows unlocking a mutex while still holding a reference to a MutexGuard.

pub fn data_ptr(&self) -> *mut T

Returns a raw pointer to the underlying data.

This is useful when combined with mem::forget to hold a lock without the need to maintain a MutexGuard object alive, for example when dealing with FFI.

Safety

You must ensure that there are no data races when dereferencing the returned pointer, for example if the current thread logically owns a MutexGuard but that guard has been discarded using mem::forget.

pub unsafe fn force_unlock_fair(&self)

Forcibly unlocks the mutex using a fair unlock protocol.

This is useful when combined with mem::forget to hold a lock without the need to maintain a MutexGuard object alive, for example when dealing with FFI.

Safety

This method must only be called if the current thread logically owns a MutexGuard but that guard has been discarded using mem::forget. Behavior is undefined if a mutex is unlocked when not locked.

pub fn try_lock_for( &self, timeout: <R as RawMutexTimed>::Duration, ) -> Option<MutexGuard<'_, R, T>>

Attempts to acquire this lock until a timeout is reached.

If the lock could not be acquired before the timeout expired, then None is returned. Otherwise, an RAII guard is returned. The lock will be unlocked when the guard is dropped.

pub fn try_lock_until( &self, timeout: <R as RawMutexTimed>::Instant, ) -> Option<MutexGuard<'_, R, T>>

Attempts to acquire this lock until a timeout is reached.

If the lock could not be acquired before the timeout expired, then None is returned. Otherwise, an RAII guard is returned. The lock will be unlocked when the guard is dropped.

Trait Implementations

impl<T> AsRef<Mutex<RawMutex, T>> for ArcMutex<T>

fn as_ref(&self) -> &Mutex<RawMutex, T>

Returns a reference to the underlying parking_lot mutex.

This is useful when callers need guard-based APIs such as Mutex::lock or Mutex::try_lock instead of the closure-based Lock methods.

impl<T> Clone for ArcMutex<T>

fn clone(&self) -> ArcMutex<T>

Clones the synchronous mutex

Creates a new ArcMutex instance that shares the same underlying lock with the original instance. This allows multiple threads to hold references to the same lock simultaneously.

Returns

A new handle sharing the same underlying mutex and protected value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Default for ArcMutex<T>

where T: Default,

fn default() -> ArcMutex<T>

Creates an Arc-wrapped parking_lot mutex containing T::default().

Returns

A new ArcMutex protecting the default value for T.

impl<T> Deref for ArcMutex<T>

fn deref(&self) -> &<ArcMutex<T> as Deref>::Target

Dereferences this wrapper to the underlying parking_lot mutex.

Method-call dereferencing lets callers use native mutex APIs directly, while the wrapper continues to provide the Lock trait methods.

type Target = Mutex<RawMutex, T>

The resulting type after dereferencing.

impl<T> From<T> for ArcMutex<T>

fn from(value: T) -> ArcMutex<T>

Creates an Arc-wrapped parking_lot mutex from a value.

Arguments

• value - The value to protect.

Returns

A new ArcMutex protecting value.

impl<T> Lock<T> for ArcMutex<T>

fn read<R, F>(&self, f: F) -> R

where F: FnOnce(&T) -> R,

Acquires a read lock and executes an operation

For ArcMutex, this acquires the same exclusive lock as write operations, but provides immutable access to the data. This ensures thread safety while allowing read-only operations.

Arguments

• f - The closure to be executed while holding the read lock

Returns

Returns the result of executing the closure

Example

use qubit_lock::{ArcMutex, Lock};

let counter = ArcMutex::new(42);

let value = counter.read(|c| *c);
println!("Current value: {}", value);

fn write<R, F>(&self, f: F) -> R

where F: FnOnce(&mut T) -> R,

Acquires a write lock and executes an operation

Synchronously acquires the exclusive lock, executes the provided closure with mutable access, and then automatically releases the lock. This is the recommended usage pattern for modifications.

Arguments

• f - The closure to be executed while holding the write lock

Returns

Returns the result of executing the closure

Example

use qubit_lock::{ArcMutex, Lock};

let counter = ArcMutex::new(0);

let result = counter.write(|c| {
    *c += 1;
    *c
});

println!("Counter value: {}", result);

fn try_read<R, F>(&self, f: F) -> Result<R, TryLockError>

where F: FnOnce(&T) -> R,

Attempts to acquire a read lock without blocking

Attempts to immediately acquire the read lock. If the lock is unavailable, returns a detailed error. This is a non-blocking operation.

Arguments

• f - The closure to be executed while holding the read lock

Returns

• Ok(R) - If the lock was successfully acquired and the closure executed
• Err(TryLockError::WouldBlock) - If the lock is already held by another thread

Example

use qubit_lock::{ArcMutex, Lock};

let counter = ArcMutex::new(42);

if let Ok(value) = counter.try_read(|c| *c) {
    println!("Current value: {}", value);
} else {
    println!("Lock is unavailable");
}

fn try_write<R, F>(&self, f: F) -> Result<R, TryLockError>

where F: FnOnce(&mut T) -> R,

Attempts to acquire a write lock without blocking

Attempts to immediately acquire the write lock. If the lock is unavailable, returns a detailed error. This is a non-blocking operation.

Arguments

• f - The closure to be executed while holding the write lock

Returns

• Ok(R) - If the lock was successfully acquired and the closure executed
• Err(TryLockError::WouldBlock) - If the lock is already held by another thread

Example

use qubit_lock::{ArcMutex, Lock};

let counter = ArcMutex::new(0);

if let Ok(result) = counter.try_write(|c| {
    *c += 1;
    *c
}) {
    println!("New value: {}", result);
} else {
    println!("Lock is unavailable");
}