qubit_lock/monitor/wait_timeout_status.rs
1/*******************************************************************************
2 *
3 * Copyright (c) 2025 - 2026.
4 * Haixing Hu, Qubit Co. Ltd.
5 *
6 * All rights reserved.
7 *
8 ******************************************************************************/
9//! # Wait Timeout Status
10//!
11//! Provides the status returned by one timed condition-variable wait.
12//!
13//! # Author
14//!
15//! Haixing Hu
16
17/// Result of a timed wait operation.
18///
19/// This status is returned by
20/// [`MonitorGuard::wait_timeout`](super::MonitorGuard::wait_timeout) and
21/// [`Monitor::wait_notify`](super::Monitor::wait_notify). It describes why a
22/// timed wait returned, but callers must still re-check the protected state
23/// because condition variables may wake spuriously.
24///
25/// # Example
26///
27/// ```rust
28/// use std::time::Duration;
29///
30/// use qubit_lock::lock::{Monitor, WaitTimeoutStatus};
31///
32/// let monitor = Monitor::new(false);
33/// let guard = monitor.lock();
34/// let (_guard, status) = guard.wait_timeout(Duration::from_millis(1));
35/// assert_eq!(status, WaitTimeoutStatus::TimedOut);
36/// ```
37#[derive(Debug, Clone, Copy, PartialEq, Eq)]
38pub enum WaitTimeoutStatus {
39 /// The wait returned before the timeout elapsed.
40 ///
41 /// This usually means another thread called
42 /// [`Monitor::notify_one`](super::Monitor::notify_one) or
43 /// [`Monitor::notify_all`](super::Monitor::notify_all), but it may also be
44 /// a spurious wakeup. Always re-check the guarded state before acting on
45 /// this status.
46 Woken,
47 /// The wait reached the timeout boundary.
48 ///
49 /// Even after this status, callers should inspect the protected state
50 /// because another thread may have changed it while the waiting thread was
51 /// reacquiring the mutex.
52 TimedOut,
53}