qubit_clock/timer/timer_future.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 the future returned by timer registrations.
9
10use std::future::Future;
11use std::pin::Pin;
12
13use crate::TimeError;
14
15/// An owned future that becomes ready when a timer reaches its deadline.
16///
17/// The logical deadline and cancellation ownership are fixed before this
18/// future is returned. A backend may defer enrollment with its native
19/// scheduler until the future is first polled. Dropping an incomplete future
20/// cancels its outstanding notification in either case. Completion reports a
21/// recoverable backend failure that occurs after successful registration.
22/// Built-in timers report backend shutdown through [`TimeError`].
23///
24/// # Panics
25///
26/// A custom Timer implementation may document additional panic conditions.
27/// Built-in manual timers may also resume panics from registered task Wakers
28/// after notifying every affected Waker.
29pub type TimerFuture = Pin<Box<dyn Future<Output = Result<(), TimeError>> + Send + 'static>>;