Struct DoubleCheckedLockExecutor 

pub struct DoubleCheckedLockExecutor<L = (), T = ()> { /* private fields */ }

Reusable double-checked lock executor.

The executor owns the lock handle, condition tester, execution logger, and optional prepare lifecycle callbacks. Each execution performs:

1. A first condition check outside the lock.
2. Optional prepare action.
3. Lock acquisition.
4. A second condition check inside the lock.
5. The submitted task.
6. Optional prepare commit or rollback after the lock is released.

The tester is intentionally run both outside and inside the lock. Any state read by the first check must therefore use atomics or another synchronization mechanism that is safe without this executor’s lock.

Type Parameters

• L - The lock type implementing Lock<T>.
• T - The data type protected by the lock.

Examples

Use DoubleCheckedLockExecutor::builder to attach a lock (for example crate::ArcMutex), set a Tester with [ExecutorLockBuilder::when], then call Self::call, Self::execute, Self::call_with, or Self::execute_with on the built executor.

use std::sync::{Arc, atomic::{AtomicBool, Ordering}};

use qubit_dcl::{DoubleCheckedLockExecutor, Lock};
use qubit_lock::ArcMutex;
use qubit_dcl::double_checked::ExecutionResult;

fn main() {
    let data = ArcMutex::new(10);
    let skip = Arc::new(AtomicBool::new(false));

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

    let updated = executor
        .call_with(|value: &mut i32| {
            *value += 5;
            Ok::<i32, std::io::Error>(*value)
        })
        .get_result();

    assert!(matches!(updated, ExecutionResult::Success(15)));
    assert_eq!(data.read(|value| *value), 15);

    skip.store(true, Ordering::Release);
    let skipped = executor
        .call_with(|value: &mut i32| {
            *value += 1;
            Ok::<i32, std::io::Error>(*value)
        })
        .get_result();

    assert!(matches!(skipped, ExecutionResult::ConditionNotMet));
    assert_eq!(data.read(|value| *value), 15);
}

Author

Haixing Hu

Implementations

impl DoubleCheckedLockExecutor<(), ()>

pub fn builder() -> ExecutorBuilder

Creates a builder for a reusable double-checked lock executor.

Returns

A builder in the initial state. Attach a lock with ExecutorBuilder::on, then configure a tester with [ExecutorLockBuilder::when].

Examples found in repository

examples/double_checked_lock_executor_demo.rs (line 49)

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::<_, ServiceError>(*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::<_, ServiceError>(*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::<_, ServiceError>(*value)
        })
        .get_result();

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

    Ok(())
}

impl<L, T> DoubleCheckedLockExecutor<L, T>

where L: Lock<T>,

pub fn new(builder: ExecutorReadyBuilder<L, T>) -> Self

Assembles an executor from the ready builder state.

Parameters

• builder - Ready builder carrying the lock, tester, logger, and prepare lifecycle callbacks.

Returns

A reusable executor containing the supplied builder state.

pub fn call<C, R, E>(&self, task: C) -> ExecutionContext<R, E>

where C: Callable<R, E> + Send + 'static, R: Send + 'static, E: Display + Send + 'static,

Executes a zero-argument callable while holding the write lock.

Use Self::call_with when the task needs direct mutable access to the protected data.

Parameters

• task - The callable task to execute after both condition checks pass.

Returns

An ExecutionContext containing success, unmet-condition, or failure information.

pub fn execute<Rn, E>(&self, task: Rn) -> ExecutionContext<(), E>

where Rn: Runnable<E> + Send + 'static, E: Display + Send + 'static,

Executes a zero-argument runnable while holding the write lock.

Parameters

• task - The runnable task to execute after both condition checks pass.

Returns

An ExecutionContext containing success, unmet-condition, or failure information.

pub fn call_with<C, R, E>(&self, task: C) -> ExecutionContext<R, E>

where C: CallableWith<T, R, E> + Send + 'static, R: Send + 'static, E: Display + Send + 'static,

Executes a callable with mutable access to the protected data.

Parameters

• task - The callable receiving &mut T after both condition checks pass.

Returns

An ExecutionContext containing success, unmet-condition, or failure information.

Examples found in repository

examples/double_checked_lock_executor_demo.rs (lines 59-62)

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::<_, ServiceError>(*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::<_, ServiceError>(*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::<_, ServiceError>(*value)
        })
        .get_result();

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

    Ok(())
}

pub fn execute_with<Rn, E>(&self, task: Rn) -> ExecutionContext<(), E>

where Rn: RunnableWith<T, E> + Send + 'static, E: Display + Send + 'static,

Executes a runnable with mutable access to the protected data.

Parameters

• task - The runnable receiving &mut T after both condition checks pass.

Returns

An ExecutionContext containing success, unmet-condition, or failure information.

Trait Implementations

impl<L: Clone, T: Clone> Clone for DoubleCheckedLockExecutor<L, T>

fn clone(&self) -> DoubleCheckedLockExecutor<L, T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.