qubit_clock/error/
timer_unavailable_error.rs

1// =============================================================================
2//    Copyright (c) 2025 - 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Defines errors reported when a timer backend is unavailable.
9
10use std::error::Error as StdError;
11use std::io;
12
13use thiserror::Error;
14
15/// Describes a backend failure that prevented timer registration or completion.
16///
17/// Each variant preserves the most specific stable source exposed by its
18/// backend. Custom [`Timer`](crate::Timer) implementations should use
19/// [`BackendUnavailable`](Self::BackendUnavailable) to retain their own error
20/// rather than reducing it to display text. The enum is non-exhaustive; callers
21/// must retain a fallback arm when matching it.
22#[non_exhaustive]
23#[derive(Debug, Error)]
24pub enum TimerUnavailableError {
25    /// The standard timer could not spawn its shared scheduler worker.
26    #[error("the scheduler worker thread could not be spawned: {source}")]
27    WorkerThreadSpawnFailed {
28        /// I/O error returned by the native thread builder.
29        #[source]
30        source: io::Error,
31    },
32    /// The standard timer scheduler worker exited before the deadline.
33    #[error("the scheduler worker thread terminated unexpectedly")]
34    SchedulerWorkerTerminated,
35    /// The target asynchronous runtime has no enabled time driver.
36    ///
37    /// Tokio currently exposes this condition by panicking while creating a
38    /// future sleep. [`TokioTimer`](crate::TokioTimer) catches that unwind and
39    /// returns this variant, but the process panic hook runs before unwinding.
40    /// Consequently the hook may still log or otherwise observe the panic,
41    /// and a `panic = "abort"` build cannot convert it into this error.
42    #[cfg(feature = "tokio")]
43    #[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
44    #[error("the asynchronous runtime time driver is disabled")]
45    TimeDriverDisabled,
46    /// The target asynchronous runtime shut down before a pending timer future
47    /// completed.
48    #[cfg(feature = "tokio")]
49    #[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
50    #[error("the asynchronous runtime shut down before the timer future completed")]
51    RuntimeShuttingDown,
52    /// A custom timer backend is unavailable.
53    #[error("timer backend '{backend}' is unavailable: {source}")]
54    BackendUnavailable {
55        /// Stable name identifying the custom backend.
56        backend: &'static str,
57        /// Backend-specific error that prevented timer registration or
58        /// completion.
59        #[source]
60        source: Box<dyn StdError + Send + Sync + 'static>,
61    },
62}
qubit_clock/error/timer_unavailable_error.rs

qubit_clock/error/
timer_unavailable_error.rs
