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

qubit_clock/error/
timer_unavailable_error.rs
