timer_kit/
lib.rs

1#![deny(missing_docs, missing_debug_implementations)]
2
3//! A timer toolkit that is generic over the underlying timer implementation. 
4//! 
5//! [![crate_version](https://img.shields.io/crates/v/timer-kit.svg?style=flat)](https://crates.io/crates/timer-kit)
6//! [![docs_version](https://img.shields.io/badge/docs-latest-blue.svg?style=flat)](https://docs.rs/timer-kit/latest/timer_kit/)
7//! 
8//! This crate does not implement any platform-specific timer but uses a generic abstraction over
9//! the timer implementation to provide a set of timer related tools:
10//! 
11//! 1. [`sleep()`]/[`Sleep`]
12//! 2. [`timeout()`]/[`Timeout`]
13//! 3. [`interval()`]/[`Interval`]
14//! 4. [`DelayQueue`]
15//! 
16//! This crate currently does not provide any feature beyond the ones that is already provided by
17//! `tokio`, so this crate is completely not needed if you are already using `tokio` in your
18//! project.
19//! 
20//! The core of this crate is the [`Delay`] trait, and it is implemented for the following types by
21//! enabling the corresponding features:
22//! 
23//! | Type | Feature | Target Arch |
24//! | ---- | ------- | ----------- |
25//! | [`tokio::time::Sleep`] | `"tokio"` | non-wasm32 |
26//! | [`smol::Timer`] | `"smol"` | non-wasm32 |
27//! | [`futures_timer::Delay`] | `"futures-timer"` | non-wasm32 |
28//! | [`wasm_timer::Delay`] | `"wasm-timer"` | wasm32 |
29//! | [`fluvio_wasm_timer::Delay`] | `"fluvio-wasm-timer"` | wasm32 |
30//!
31//! # WebAssembly support
32//! 
33//! Support for `wasm32-unknown-unknown` target depends on the chosen timer implementation.
34//! `wasm-timer` and `fluvio-wasm-timer` are the only two wasm timer implementations that are
35//! currently supported.
36//! 
37//! # Examples
38//! 
39//! The usage remains mostly similar to those provided in `tokio::time` with one additional generic
40//! type parameter `D` which is the type of the underlying timer implementation. Please refer to the
41//! documentation of the corresponding types for more details.
42
43use std::{
44    ops::{Add, Sub},
45    pin::Pin,
46    task::{Context, Poll},
47    time::Duration,
48};
49
50#[macro_use]
51mod macros;
52
53pub(crate) mod util;
54
55mod delay_queue;
56mod interval;
57mod sleep;
58mod timeout;
59
60/// Copied from `tokio-util::time::delay_queue::wheel`
61mod wheel;
62
63mod delay_impl;
64mod instant_impl;
65
66pub mod error;
67
68// Re-exports
69pub use delay_queue::*;
70pub use interval::*;
71pub use sleep::*;
72pub use timeout::*;
73
74/// A trait that defines a delay, which is the fundamental building block of this crate.
75/// 
76/// # Implementations
77/// 
78/// Implementations for the following types are provided with the corresponding features enabled:
79/// 
80/// | Type | Feature | Target Arch |
81/// | ---- | ------- | ----------- |
82/// | [`tokio::time::Sleep`] | `"tokio"` | non-wasm32 |
83/// | [`smol::Timer`] | `"smol"` | non-wasm32 |
84/// | [`futures_timer::Delay`] | `"futures-timer"` | non-wasm32 |
85/// | [`wasm_timer::Delay`] | `"wasm-timer"` | wasm32 |
86/// | [`fluvio_wasm_timer::Delay`] | `"fluvio-wasm-timer"` | wasm32 |
87/// 
88/// User could also provide their own implementations for other types to use the timer
89/// functionalities provided by this crate.
90pub trait Delay {
91    /// The type of value returned by the delay upon completion of `poll_elapsed`.
92    type Value;
93
94    /// The type of instant used by the delay.
95    type Instant: Instant;
96
97    /// Creates a new delay with a specified duration.
98    fn delay(duration: Duration) -> Self;
99
100    /// Creates a new delay with a specified deadline.
101    fn delay_until(deadline: Self::Instant) -> Self;
102
103    /// Some implementation do not expose the deadline, so this is an optional.
104    fn deadline(&self) -> Option<Self::Instant>;
105
106    /// Polls the delay for completion.
107    fn poll_elapsed(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Value>;
108
109    /// Resets the delay to a new deadline.
110    fn reset(self: Pin<&mut Self>, deadline: Self::Instant);
111}
112
113/// A trait that defines an instant.
114/// 
115/// # Implementations
116/// 
117/// Implementations for the following types are provided with the corresponding features enabled:
118/// 
119/// | Type | Feature | Target Arch |
120/// | ---- | ------- | ----------- |
121/// | [`std::time::Instant`] | `"std"` | non-wasm32 |
122/// | [`tokio::time::Instant`] | `"tokio"` | non-wasm32 |
123/// | [`wasm_timer::Instant`] | `"wasm-timer"` | wasm32 |
124/// | [`fluvio_wasm_timer::Instant`] | `"fluvio-wasm-timer"` | wasm32 |
125/// 
126/// User could also provide their own implementations for other types to use the timer
127/// functionalities provided by this crate.
128pub trait Instant
129where
130    Self: Add<Duration, Output = Self>
131        + Sub<Duration, Output = Self>
132        + Sub<Self, Output = Duration>
133        + Sized
134        + Clone
135        + Copy
136        + PartialEq
137        + Eq
138        + PartialOrd
139        + Ord,
140{
141    /// Returns the instant that is "now"
142    fn now() -> Self;
143}
timer_kit/lib.rs

timer_kit/
lib.rs
