qubit_lock/monitor/
wait_timeout_status.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026 Haixing Hu.
4 *
5 *    SPDX-License-Identifier: Apache-2.0
6 *
7 *    Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10//! # Wait Timeout Status
11//!
12//! Provides the status returned by one timed condition-variable wait.
13//!
14
15/// Result of a timed wait operation.
16///
17/// This status is returned by
18/// [`MonitorGuard::wait_timeout`](super::MonitorGuard::wait_timeout) and
19/// [`Monitor::wait_notify`](super::Monitor::wait_notify). It describes why a
20/// timed wait returned, but callers must still re-check the protected state
21/// because condition variables may wake spuriously.
22///
23/// # Example
24///
25/// ```rust
26/// use std::time::Duration;
27///
28/// use qubit_lock::{Monitor, WaitTimeoutStatus};
29///
30/// let monitor = Monitor::new(false);
31/// let guard = monitor.lock();
32/// let (_guard, status) = guard.wait_timeout(Duration::from_millis(1));
33/// assert_eq!(status, WaitTimeoutStatus::TimedOut);
34/// ```
35#[derive(Debug, Clone, Copy, PartialEq, Eq)]
36pub enum WaitTimeoutStatus {
37    /// The wait returned before the timeout elapsed.
38    ///
39    /// This usually means another thread called
40    /// [`Monitor::notify_one`](super::Monitor::notify_one) or
41    /// [`Monitor::notify_all`](super::Monitor::notify_all), but it may also be
42    /// a spurious wakeup. Always re-check the guarded state before acting on
43    /// this status.
44    Woken,
45    /// The wait reached the timeout boundary.
46    ///
47    /// Even after this status, callers should inspect the protected state
48    /// because another thread may have changed it while the waiting thread was
49    /// reacquiring the mutex.
50    TimedOut,
51}
52
53impl WaitTimeoutStatus {
54    /// Returns `true` when the wait returned before the timeout elapsed.
55    ///
56    /// # Returns
57    ///
58    /// `true` for [`Self::Woken`], otherwise `false`.
59    #[inline]
60    pub const fn is_woken(&self) -> bool {
61        match self {
62            Self::Woken => true,
63            Self::TimedOut => false,
64        }
65    }
66
67    /// Returns `true` when the wait reached the timeout boundary.
68    ///
69    /// # Returns
70    ///
71    /// `true` for [`Self::TimedOut`], otherwise `false`.
72    #[inline]
73    pub const fn is_timed_out(&self) -> bool {
74        match self {
75            Self::Woken => false,
76            Self::TimedOut => true,
77        }
78    }
79}
qubit_lock/monitor/wait_timeout_status.rs

qubit_lock/monitor/
wait_timeout_status.rs
