1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

//! Abstraction for hardware timers/clocks

use crate::{
    duration::Duration, fixed_point::FixedPoint, fraction::Fraction, instant::Instant,
    time_int::TimeInt, timer::param, timer::Timer,
};

/// Potential `Clock` errors
#[non_exhaustive]
#[derive(Debug, Eq, PartialEq)]
pub enum Error<E> {
    /// implementation-specific error
    Other(E),
}

/// The `Clock` trait provides an abstraction of hardware-specific timer peripherals, external timer
/// devices, RTCs, etc.
///
/// The `Clock` is characterized by an inner unsigned integer storage type (either [`u32`] or
/// [`u64`]), a [`u32`]/[`u32`] [`Fraction`] defining the duration (in seconds) of one
/// count of the `Clock`, and a custom error type representing errors that may be generated by the
/// implementation.
///
/// In addition to the [`Clock::try_now()`] method which returns an [`Instant`], an unlimited number
/// of software [`Timer`]s can be spawned from a single `Clock` instance.
pub trait Clock: Sized {
    /// The type to hold the tick count
    type T: TimeInt;

    /// Implementation-defined error type
    ///
    /// This type can be returned using the
    /// [`clock::Error::Other(E)`](enum.Error.html#variant.Other)
    type ImplError;

    /// The duration of one clock tick in seconds, AKA the clock precision.
    const SCALING_FACTOR: Fraction;

    /// Get the current Instant
    ///
    /// # Errors
    ///
    /// Implementation-specific error returned as
    /// [`Error::Other(Self::ImplError)`](enum.Error.html#variant.Other)
    // TODO: add example
    fn try_now(&self) -> Result<Instant<Self>, Error<Self::ImplError>>;

    /// Spawn a new, `OneShot` [`Timer`] from this clock
    fn new_timer<Dur: Duration>(
        &self,
        duration: Dur,
    ) -> Timer<param::OneShot, param::Armed, Self, Dur>
    where
        Dur: FixedPoint,
    {
        Timer::<param::None, param::None, Self, Dur>::new(&self, duration)
    }
}