Struct ArcParkingLotMonitor 

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

Arc-wrapped monitor for shared condition-based state coordination.

ArcParkingLotMonitor stores a ParkingLotMonitor behind an Arc, so callers can clone the monitor handle directly without writing Arc::new(ParkingLotMonitor::new(...)). It preserves the same guard-based waiting and predicate-based waiting semantics as ParkingLotMonitor. It implements Deref and AsRef so callers can pass it to APIs that expect a ParkingLotMonitor reference.

Type Parameters

• T - The state protected by this monitor.

Example

use std::thread;

use qubit_lock::ArcParkingLotMonitor;

let monitor = ArcParkingLotMonitor::new(false);
let waiter_monitor = monitor.clone();

let waiter = thread::spawn(move || {
    waiter_monitor.wait_until(
        |ready| *ready,
        |ready| {
            *ready = false;
        },
    );
});

monitor.write(|ready| {
    *ready = true;
});
monitor.notify_all();

waiter.join().expect("waiter should finish");
assert!(!monitor.read(|ready| *ready));

Implementations

impl<T> ArcParkingLotMonitor<T>

pub fn new(state: T) -> Self

Creates an Arc-wrapped monitor protecting the supplied state value.

Arguments

• state - Initial state protected by the monitor.

Returns

A cloneable monitor handle initialized with the supplied state.

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

Acquires the shared monitor and returns a guard.

This delegates to ParkingLotMonitor::lock. The returned ParkingLotMonitorGuard keeps the monitor mutex locked until it is dropped. It can also wait on the monitor’s condition variable through ParkingLotMonitorGuard::wait or ParkingLotMonitorGuard::wait_timeout.

Returns

A guard that provides read and write access to the protected state.

Example

use qubit_lock::ArcParkingLotMonitor;

let monitor = ArcParkingLotMonitor::new(1);
{
    let mut value = monitor.lock();
    *value += 1;
}

assert_eq!(monitor.read(|value| *value), 2);

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

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

Acquires the monitor and reads the protected state.

This delegates to ParkingLotMonitor::read. The closure runs while the monitor mutex is held, so keep it short and avoid long blocking work.

Arguments

• f - Closure that receives an immutable reference to the state.

Returns

The value returned by f.

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

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

Acquires the monitor and mutates the protected state.

This delegates to ParkingLotMonitor::write. Callers should explicitly invoke Self::notify_one or Self::notify_all after changing state that a waiting thread may observe.

Arguments

• f - Closure that receives a mutable reference to the state.

Returns

The value returned by f.

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

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

Mutates the protected state and wakes one waiter.

This delegates to ParkingLotMonitor::write_notify_one. The closure runs while the monitor mutex is held; after it returns, the lock is released and one waiter is notified. If f panics, the panic is propagated and no notification is sent.

Arguments

• f - Closure that receives a mutable reference to the state.

Returns

The value returned by f.

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

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

Mutates the protected state and wakes all waiters.

This delegates to ParkingLotMonitor::write_notify_all. The closure runs while the monitor mutex is held; after it returns, the lock is released and all waiters are notified. If f panics, the panic is propagated and no notification is sent.

Arguments

• f - Closure that receives a mutable reference to the state.

Returns

The value returned by f.

pub fn wait(&self)

Waits for a notification without checking state.

This delegates to ParkingLotMonitor::wait.

pub fn wait_for(&self, timeout: Duration) -> WaitTimeoutStatus

Waits for a notification or timeout without checking state.

This delegates to ParkingLotMonitor::wait_for. Most coordination code should prefer Self::wait_while, Self::wait_until, or an explicit ParkingLotMonitorGuard loop.

WaitTimeoutStatus::Woken means the condition variable was notified, but it does not prove that the protected state changed in a useful way.

Arguments

• timeout - Maximum duration to wait for a notification.

Returns

WaitTimeoutStatus::Woken if the wait returned before the timeout, or WaitTimeoutStatus::TimedOut if the timeout elapsed.

Example

use std::time::Duration;

use qubit_lock::{ArcParkingLotMonitor, WaitTimeoutStatus};

let monitor = ArcParkingLotMonitor::new(false);
let status = monitor.wait_for(Duration::from_millis(1));

assert_eq!(status, WaitTimeoutStatus::TimedOut);

pub fn wait_while<R, P, F>(&self, waiting: P, f: F) -> R

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

Waits while a predicate remains true, then mutates the protected state.

This delegates to ParkingLotMonitor::wait_while. The predicate is evaluated while holding the monitor mutex, and the closure runs while the mutex is still held after the predicate stops blocking.

This method may block indefinitely if no thread changes the state so that waiting becomes false and sends a notification.

Arguments

• waiting - Predicate that returns true while the caller should keep waiting.
• f - Closure that receives mutable access after waiting is no longer required.

Returns

The value returned by f.

Example

use std::thread;

use qubit_lock::ArcParkingLotMonitor;

let monitor = ArcParkingLotMonitor::new(Vec::<i32>::new());
let worker_monitor = monitor.clone();

let worker = thread::spawn(move || {
    worker_monitor.wait_while(
        |items| items.is_empty(),
        |items| items.pop().expect("item should be ready"),
    )
});

monitor.write(|items| items.push(7));
monitor.notify_one();

assert_eq!(worker.join().expect("worker should finish"), 7);

pub fn wait_until<R, P, F>(&self, ready: P, f: F) -> R

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

Waits until the protected state satisfies a predicate, then mutates it.

This delegates to ParkingLotMonitor::wait_until. It may block indefinitely if no thread changes the state to satisfy the predicate and sends a notification.

Arguments

• ready - Predicate that returns true when the state is ready.
• f - Closure that receives mutable access to the ready state.

Returns

The value returned by f.

pub fn wait_while_for<R, P, F>( &self, timeout: Duration, waiting: P, f: F, ) -> WaitTimeoutResult<R>

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

Waits while a predicate remains true, with an overall time limit.

This delegates to ParkingLotMonitor::wait_while_for. If waiting becomes false before timeout expires, f runs while the monitor lock is still held. If the timeout expires first, the closure is not called.

Arguments

• timeout - Maximum total duration to wait.
• waiting - Predicate that returns true while the caller should continue waiting.
• f - Closure that receives mutable access when waiting is no longer required.

Returns

WaitTimeoutResult::Ready with the value returned by f when the predicate stops blocking before the timeout. Returns WaitTimeoutResult::TimedOut when the timeout expires first.

Example

use std::time::Duration;

use qubit_lock::{ArcParkingLotMonitor, WaitTimeoutResult};

let monitor = ArcParkingLotMonitor::new(Vec::<i32>::new());
let result = monitor.wait_while_for(
    Duration::from_millis(1),
    |items| items.is_empty(),
    |items| items.pop(),
);

assert_eq!(result, WaitTimeoutResult::TimedOut);

pub fn wait_until_for<R, P, F>( &self, timeout: Duration, ready: P, f: F, ) -> WaitTimeoutResult<R>

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

Waits until a predicate becomes true, with an overall time limit.

This delegates to ParkingLotMonitor::wait_until_for. If ready becomes true before timeout expires, f runs while the monitor lock is still held. If the timeout expires first, the closure is not called.

Arguments

• timeout - Maximum total duration to wait.
• ready - Predicate that returns true when the caller may continue.
• f - Closure that receives mutable access to the ready state.

Returns

WaitTimeoutResult::Ready with the value returned by f when the predicate becomes true before the timeout. Returns WaitTimeoutResult::TimedOut when the timeout expires first.

Example

use std::{
    thread,
    time::Duration,
};

use qubit_lock::{ArcParkingLotMonitor, WaitTimeoutResult};

let monitor = ArcParkingLotMonitor::new(false);
let worker_monitor = monitor.clone();

let worker = thread::spawn(move || {
    worker_monitor.wait_until_for(
        Duration::from_secs(1),
        |ready| *ready,
        |ready| {
            *ready = false;
            5
        },
    )
});

monitor.write(|ready| *ready = true);
monitor.notify_one();

assert_eq!(
    worker.join().expect("worker should finish"),
    WaitTimeoutResult::Ready(5),
);

pub fn notify_one(&self)

Wakes one thread waiting on this monitor’s condition variable.

Notifications do not carry state by themselves. A waiting thread only proceeds safely after rechecking the protected state. Call this after changing state that may make one waiter able to continue.

pub fn notify_all(&self)

Wakes all threads waiting on this monitor’s condition variable.

Notifications do not carry state by themselves. Every awakened thread must recheck the protected state before continuing. Call this after a state change that may allow multiple waiters to make progress.

Methods from Deref<Target = ParkingLotMonitor<T>>

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

Acquires the monitor and returns a guard for explicit state-machine code.

The returned ParkingLotMonitorGuard keeps the monitor mutex locked until the guard is dropped. It can also be passed through ParkingLotMonitorGuard::wait or ParkingLotMonitorGuard::wait_timeout to temporarily release the lock while waiting on this monitor’s condition variable.

Returns

A guard that provides read and write access to the protected state.

Example

use qubit_lock::ParkingLotMonitor;

let monitor = ParkingLotMonitor::new(1);
{
    let mut value = monitor.lock();
    *value += 1;
}

assert_eq!(monitor.read(|value| *value), 2);

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

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

Acquires the monitor and reads the protected state.

The closure runs while the mutex is held. Keep the closure short and do not call code that may block for a long time.

Arguments

• f - Closure that receives an immutable reference to the state.

Returns

The value returned by the closure.

Example

use qubit_lock::ParkingLotMonitor;

let monitor = ParkingLotMonitor::new(10_i32);
let n = monitor.read(|x| *x);
assert_eq!(n, 10);

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

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

Acquires the monitor and mutates the protected state.

The closure runs while the mutex is held. This method only changes the state; callers should explicitly call Self::notify_one or Self::notify_all after changing a condition that waiters may be observing.

Arguments

• f - Closure that receives a mutable reference to the state.

Returns

The value returned by the closure.

Example

use qubit_lock::ParkingLotMonitor;

let monitor = ParkingLotMonitor::new(String::new());
let len = monitor.write(|s| {
    s.push_str("hi");
    s.len()
});
assert_eq!(len, 2);

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

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

Acquires the monitor, mutates the protected state, and wakes one waiter.

The closure runs while the mutex is held. After the closure returns, the mutex guard is dropped and one thread waiting on this monitor’s condition variable is notified. This is a convenience method for the common “update state, then notify one waiter” pattern.

If f panics, the panic is propagated and no notification is sent.

Arguments

• f - Closure that receives a mutable reference to the state.

Returns

The value returned by the closure.

Example

use qubit_lock::ParkingLotMonitor;

let monitor = ParkingLotMonitor::new(Vec::<i32>::new());
let len = monitor.write_notify_one(|items| {
    items.push(7);
    items.len()
});

assert_eq!(len, 1);

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

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

Acquires the monitor, mutates the protected state, and wakes all waiters.

The closure runs while the mutex is held. After the closure returns, the mutex guard is dropped and all threads waiting on this monitor’s condition variable are notified. This is a convenience method for state changes that may allow multiple waiters to make progress.

If f panics, the panic is propagated and no notification is sent.

Arguments

• f - Closure that receives a mutable reference to the state.

Returns

The value returned by the closure.

Example

use qubit_lock::ParkingLotMonitor;

let monitor = ParkingLotMonitor::new(false);
let ready = monitor.write_notify_all(|ready| {
    *ready = true;
    *ready
});

assert!(ready);

pub fn wait(&self)

Waits for a notification without checking state.

This method locks the monitor, waits once on the condition variable, and returns after the wait is woken. Most coordination code should prefer Self::wait_while, Self::wait_until, or an explicit ParkingLotMonitorGuard loop that rechecks protected state.

This method may block indefinitely if no notification is sent.

pub fn wait_for(&self, timeout: Duration) -> WaitTimeoutStatus

Waits for a notification or timeout without checking state.

This convenience method locks the monitor, waits once on the condition variable, and returns why the timed wait completed. It is useful only when the caller genuinely needs a notification wait without inspecting state before or after the wait. Most coordination code should prefer Self::wait_while, Self::wait_until, or the explicit ParkingLotMonitorGuard::wait_timeout loop.

WaitTimeoutStatus::Woken means the condition variable was notified, but it does not prove that the protected state changed in a useful way.

Arguments

• timeout - Maximum duration to wait for a notification.

Returns

WaitTimeoutStatus::Woken if the wait returned before the timeout, or WaitTimeoutStatus::TimedOut if the timeout elapsed.

Example

use std::time::Duration;

use qubit_lock::{ParkingLotMonitor, WaitTimeoutStatus};

let monitor = ParkingLotMonitor::new(false);
let status = monitor.wait_for(Duration::from_millis(1));

assert_eq!(status, WaitTimeoutStatus::TimedOut);

pub fn wait_while<R, P, F>(&self, waiting: P, f: F) -> R

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

Waits while a predicate remains true, then mutates the protected state.

This is the monitor equivalent of the common while condition { wait } guarded-suspension pattern. The predicate is evaluated while holding the mutex. If it returns true, the current thread waits on the condition variable and atomically releases the mutex. After a notification, the mutex is reacquired and the predicate is evaluated again. When the predicate returns false, f runs while the mutex is still held.

This method may block indefinitely if no thread changes the state so that waiting becomes false and sends a notification.

Arguments

• waiting - Predicate that returns true while the caller should keep waiting.
• f - Closure that receives mutable access after waiting is no longer required.

Returns

The value returned by f.

Example

use std::{
    sync::Arc,
    thread,
};

use qubit_lock::ParkingLotMonitor;

let monitor = Arc::new(ParkingLotMonitor::new(Vec::<i32>::new()));
let worker_monitor = Arc::clone(&monitor);

let worker = thread::spawn(move || {
    worker_monitor.wait_while(
        |items| items.is_empty(),
        |items| items.pop().expect("item should be ready"),
    )
});

monitor.write(|items| items.push(7));
monitor.notify_one();

assert_eq!(worker.join().expect("worker should finish"), 7);

pub fn wait_until<R, P, F>(&self, ready: P, f: F) -> R

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

Waits until the protected state satisfies a predicate, then mutates it.

This is the positive-predicate counterpart of Self::wait_while. The predicate is evaluated while holding the mutex. If it returns false, the current thread waits on the condition variable and atomically releases the mutex. After a notification, the mutex is reacquired and the predicate is evaluated again. When the predicate returns true, f runs while the mutex is still held.

This method may block indefinitely if no thread changes the state to satisfy the predicate and sends a notification.

Arguments

• ready - Predicate that returns true when the state is ready.
• f - Closure that receives mutable access to the ready state.

Returns

The value returned by f after the predicate has become true.

Example

use std::{
    sync::Arc,
    thread,
};

use qubit_lock::ParkingLotMonitor;

let monitor = Arc::new(ParkingLotMonitor::new(false));
let waiter_monitor = Arc::clone(&monitor);

let waiter = thread::spawn(move || {
    waiter_monitor.wait_until(
        |ready| *ready,
        |ready| {
            *ready = false;
            "done"
        },
    )
});

monitor.write(|ready| *ready = true);
monitor.notify_one();

assert_eq!(waiter.join().expect("waiter should finish"), "done");

pub fn wait_while_for<R, P, F>( &self, timeout: Duration, waiting: P, f: F, ) -> WaitTimeoutResult<R>

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

Waits while a predicate remains true, with an overall time limit.

This method is the timeout-aware form of Self::wait_while. It keeps rechecking waiting under the monitor lock and waits only for the remaining portion of timeout. If waiting becomes false before the timeout expires, f runs while the lock is still held. If the timeout expires first, the closure is not called.

Timeout status alone is not used as proof that the predicate is still true; the predicate is always rechecked under the lock.

Arguments

• timeout - Maximum total duration to wait.
• waiting - Predicate that returns true while the caller should continue waiting.
• f - Closure that receives mutable access when waiting is no longer required.

Returns

WaitTimeoutResult::Ready with the value returned by f when the predicate stops blocking before the timeout. Returns WaitTimeoutResult::TimedOut when the timeout expires first.

Example

use std::time::Duration;

use qubit_lock::{ParkingLotMonitor, WaitTimeoutResult};

let monitor = ParkingLotMonitor::new(Vec::<i32>::new());
let result = monitor.wait_while_for(
    Duration::from_millis(1),
    |items| items.is_empty(),
    |items| items.pop(),
);

assert_eq!(result, WaitTimeoutResult::TimedOut);

pub fn wait_until_for<R, P, F>( &self, timeout: Duration, ready: P, f: F, ) -> WaitTimeoutResult<R>

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

Waits until a predicate becomes true, with an overall time limit.

This is the positive-predicate counterpart of Self::wait_while_for. If ready becomes true before the timeout expires, f runs while the monitor lock is still held. If the timeout expires first, the closure is not called.

Timeout status alone is not used as proof that the predicate is still false; the predicate is always rechecked under the lock.

Arguments

• timeout - Maximum total duration to wait.
• ready - Predicate that returns true when the caller may continue.
• f - Closure that receives mutable access to the ready state.

Returns

WaitTimeoutResult::Ready with the value returned by f when the predicate becomes true before the timeout. Returns WaitTimeoutResult::TimedOut when the timeout expires first.

Example

use std::{
    sync::Arc,
    thread,
    time::Duration,
};

use qubit_lock::{ParkingLotMonitor, WaitTimeoutResult};

let monitor = Arc::new(ParkingLotMonitor::new(false));
let waiter_monitor = Arc::clone(&monitor);

let waiter = thread::spawn(move || {
    waiter_monitor.wait_until_for(
        Duration::from_secs(1),
        |ready| *ready,
        |ready| {
            *ready = false;
            5
        },
    )
});

monitor.write(|ready| *ready = true);
monitor.notify_one();

assert_eq!(
    waiter.join().expect("waiter should finish"),
    WaitTimeoutResult::Ready(5),
);

pub fn notify_one(&self)

Wakes one thread waiting on this monitor’s condition variable.

Notifications do not carry state by themselves. A waiting thread only proceeds safely after rechecking the protected state. Call this after changing state that may make one waiter able to continue.

Example

use std::thread;

use qubit_lock::ArcParkingLotMonitor;

let monitor = ArcParkingLotMonitor::new(0_u32);
let waiter = {
    let m = monitor.clone();
    thread::spawn(move || {
        m.wait_until(|n| *n > 0, |n| {
            *n -= 1;
        });
    })
};

monitor.write(|n| *n = 1);
monitor.notify_one();
waiter.join().expect("waiter should finish");

pub fn notify_all(&self)

Wakes all threads waiting on this monitor’s condition variable.

Notifications do not carry state by themselves. Every awakened thread must recheck the protected state before continuing. Call this after a state change that may allow multiple waiters to make progress.

Example

use std::thread;

use qubit_lock::ArcParkingLotMonitor;

let monitor = ArcParkingLotMonitor::new(false);
let mut handles = Vec::new();
for _ in 0..2 {
    let m = monitor.clone();
    handles.push(thread::spawn(move || {
        m.wait_until(|ready| *ready, |_| ());
    }));
}

monitor.write(|ready| *ready = true);
monitor.notify_all();
for h in handles {
    h.join().expect("waiter should finish");
}

Trait Implementations

impl<T> AsRef<ParkingLotMonitor<T>> for ArcParkingLotMonitor<T>

fn as_ref(&self) -> &ParkingLotMonitor<T>

Returns a reference to the underlying monitor.

This is useful when callers need an explicit ParkingLotMonitor reference while keeping the cloneable ArcParkingLotMonitor handle.

impl<T> Clone for ArcParkingLotMonitor<T>

fn clone(&self) -> Self

Clones this monitor handle.

The cloned handle shares the same protected state and condition variable with the original.

Returns

A new handle sharing the same monitor state.

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

Performs copy-assignment from source.

impl<T> ConditionWaiter for ArcParkingLotMonitor<T>

fn wait_while<R, P, F>(&self, predicate: P, action: F) -> R

where P: FnMut(&Self::State) -> bool, F: FnOnce(&mut Self::State) -> R,

Blocks while the predicate remains true, then runs the action.

type State = T

State protected by the monitor.

fn wait_until<R, P, F>(&self, predicate: P, action: F) -> R

where P: FnMut(&Self::State) -> bool, F: FnOnce(&mut Self::State) -> R,

Blocks until the predicate becomes true, then runs an action.

impl<T: Default> Default for ArcParkingLotMonitor<T>

fn default() -> Self

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

Returns

A cloneable monitor handle protecting the default value for T.

impl<T> Deref for ArcParkingLotMonitor<T>

fn deref(&self) -> &Self::Target

Dereferences this wrapper to the underlying monitor.

Method-call dereferencing lets callers use native ParkingLotMonitor APIs directly, while this wrapper still provides cloneable ownership.

type Target = ParkingLotMonitor<T>

The resulting type after dereferencing.

impl<T> From<T> for ArcParkingLotMonitor<T>

fn from(value: T) -> Self

Creates an Arc-wrapped monitor from an initial state value.

Arguments

• value - Initial state protected by the monitor.

Returns

A cloneable monitor handle protecting value.

impl<T> NotificationWaiter for ArcParkingLotMonitor<T>

fn wait(&self)

Blocks until a notification wakes this waiter.

impl<T> Notifier for ArcParkingLotMonitor<T>

fn notify_one(&self)

Wakes one thread waiting on this monitor.

fn notify_all(&self)

Wakes all threads waiting on this monitor.

impl<T> TimeoutConditionWaiter for ArcParkingLotMonitor<T>

fn wait_while_for<R, P, F>( &self, timeout: Duration, predicate: P, action: F, ) -> WaitTimeoutResult<R>

where P: FnMut(&Self::State) -> bool, F: FnOnce(&mut Self::State) -> R,

Blocks while the predicate remains true or until the timeout expires.

fn wait_until_for<R, P, F>( &self, timeout: Duration, predicate: P, action: F, ) -> WaitTimeoutResult<R>

where P: FnMut(&Self::State) -> bool, F: FnOnce(&mut Self::State) -> R,

Blocks until the predicate becomes true or the timeout expires.

impl<T> TimeoutNotificationWaiter for ArcParkingLotMonitor<T>

fn wait_for(&self, timeout: Duration) -> WaitTimeoutStatus

Blocks until a notification wakes this waiter or the timeout expires.