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.

Panics from the tester, prepare callbacks, or task can be captured by configuring the builder or by deriving a reconfigured executor with with_panic_capture. Tester and task panics are reported as super::ExecutorError::Panic. Prepare lifecycle panics are reported through the corresponding prepare, commit, or rollback error variants, so rollback can still be executed after captured task or second condition-check panics.

Cloned executors share their configured prepare callbacks. Concurrent calls may therefore complete prepare in several threads before one call wins the second condition check; calls that lose the second check run prepare rollback if it is configured.

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

use qubit_dcl::{ArcMutex, DoubleCheckedLockExecutor, Lock};
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);
}

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 40)

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(())
}

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>, E: Display,

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>, E: Display,

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>, E: Display,

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 50-53)

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(())
}

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

where Rn: RunnableWith<T, E>, E: Display,

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.

pub fn with_panic_capture(self, catch_panics: bool) -> Self

Derives an executor with panic capture enabled or disabled for tester, callbacks, and task execution.

Parameters

• catch_panics - true to convert panic payloads into execution errors, or false to let panics unwind normally.

Returns

A reconfigured executor with the updated panic-capture setting.

pub fn catch_panics(&self) -> bool

Returns whether panic capture is enabled.

Returns

true when tester, prepare callback, and task panics are converted into execution errors instead of unwinding.

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.