Qubit DCL

A standalone crate for double-checked locking over generic lock handles. It packages the usual “test outside the lock, lock, test again, run the task” sequence into a reusable DoubleCheckedLockExecutor, with an optional prepare / rollback / commit pipeline and structured results.

The crate re-exports ArcMutex and the Lock trait from qubit-lock so a typical app can depend on qubit-dcl alone.

Features

DoubleCheckedLockExecutor: one builder-built executor, many invocations; integrates with the qubit-function Tester and runnable traits.
DoubleCheckedLock: one-shot convenience entry for on(...).when(...).call* style execution without keeping an executor variable.
Double-checked flow: first condition check without the lock, optional pre-lock prepare, write lock, second check, then task; after the lock is released, optional prepare commit or rollback.
Execution API: call / execute (no direct &mut T in the closure) and call_with / execute_with (mutable access to protected data).
Typed outcomes: ExecutionContext and ExecutionResult distinguish success, “condition not met,” task failure, and prepare finalization failures (ExecutorError).
Logging hooks via log and configurable ExecutionLogger on the builder for unmet conditions and prepare-step failures; each event can also be disabled from the builder chain.

How it works

The condition tester runs twice (outside the lock, then again under the write lock). Anything the first read relies on must remain safe without this executor’s lock (for example atomics with appropriate orderings).
If the first test passes, an optional prepare runnable may run; then the lock is taken, the second test runs, and the user task runs with &mut T if applicable.
If prepare ran successfully, after releasing the lock the executor may run commit on full success, or rollback when the inner check or task did not succeed.

Panics from the tester, prepare callbacks, or task are not caught by default. Enable capture with .catch_panics(), or use .with_panic_capture(flag) when the setting comes from a boolean. Built executors also support .with_panic_capture(flag) and return a reconfigured executor. Tester and task panics become ExecutorError::Panic; prepare lifecycle panics become PrepareFailed, PrepareCommitFailed, or PrepareRollbackFailed. When prepare already succeeded, rollback can still run for captured task or second-check panics. When cloned executors run concurrently, several calls may complete prepare before one call wins the second condition check; losing calls run prepare rollback if it is configured.

Installation

[dependencies]
qubit-dcl = "0.9"

qubit-dcl already depends on qubit-lock and re-exports ArcMutex and Lock; add a direct qubit-lock dependency only if you use types beyond those re-exports.

Public API paths

Import the lock trait from the crate root:

use qubit_dcl::Lock;

The old compatibility path qubit_dcl::lock::Lock is no longer provided. Use the root re-export above, or import qubit_lock::Lock directly when your code intentionally depends on qubit-lock.

Quick start

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

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

Side-effect–only run (`finish`)

For execute or call with no meaningful return value, you can use ExecutionContext::finish on ExecutionContext<(), E> to get a bool success:

use qubit_dcl::{DoubleCheckedLockExecutor, ArcMutex};

let data = ArcMutex::new(());
let ok = DoubleCheckedLockExecutor::builder()
    .on(data)
    .when(|| true)
    .build()
    .execute(|| Ok::<(), std::io::Error>(()))
    .finish();
assert!(ok);

finish() is intentionally lossy: both condition-not-met and execution failure return false. Use try_finish() when you need to preserve task or prepare errors:

use qubit_dcl::{DoubleCheckedLockExecutor, ArcMutex};

let data = ArcMutex::new(());
let ok = DoubleCheckedLockExecutor::builder()
    .on(data)
    .when(|| true)
    .build()
    .execute(|| Ok::<(), std::io::Error>(()))
    .try_finish()
    .expect("execution should not fail");
assert!(ok);

One-shot convenience (`DoubleCheckedLock`)

When you do not need to keep a reusable executor, use DoubleCheckedLock for a shorter chain:

use std::sync::{Arc, atomic::{AtomicBool, Ordering}};
use qubit_dcl::{DoubleCheckedLock, ArcMutex, ExecutionResult, Lock};

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

let updated = DoubleCheckedLock::on(data.clone())
    .when({
        let skip = skip.clone();
        move || !skip.load(Ordering::Acquire)
    })
    .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);

Example program

A runnable sample is under examples/double_checked_lock_executor_demo.rs:

cargo run --example double_checked_lock_executor_demo

Builder API (summary)

Start with DoubleCheckedLockExecutor::builder().
Attach a lock: .on(lock) where L: Lock<T>.
Set the double-checked condition: .when(tester).
Configure panic capture with .catch_panics(), .with_panic_capture(flag), or .disable_catch_panics().
Optionally: .prepare, .rollback_prepare, .commit_prepare for the prepare pipeline.
Configure diagnostics with .log_unmet_condition, .log_prepare_failure, .log_prepare_commit_failure, .log_prepare_rollback_failure; disable them with the matching .disable_*_logging methods.
Finish with .build().

Project layout

src/double_checked: executor, builders, ExecutionContext, ExecutionResult, errors, and logging.
tests/double_checked and tests/docs: unit and README consistency tests.

Quality checks

cargo +nightly fmt -- --check --config-path .rs-ci/rustfmt.toml
cargo clippy --all-targets --all-features -- -D warnings
cargo test
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
./align-ci.sh
./ci-check.sh
./coverage.sh json

License

Apache-2.0

qubit-dcl 0.9.3