Trait Timer

pub trait Timer<'a>: Time {
    // Required methods
    fn set_timer_client(&self, client: &'a dyn TimerClient);
    fn oneshot(&self, interval: Self::Ticks) -> Self::Ticks;
    fn repeating(&self, interval: Self::Ticks) -> Self::Ticks;
    fn interval(&self) -> Option<Self::Ticks>;
    fn is_oneshot(&self) -> bool;
    fn is_repeating(&self) -> bool;
    fn time_remaining(&self) -> Option<Self::Ticks>;
    fn is_enabled(&self) -> bool;
    fn cancel(&self) -> Result<(), ErrorCode>;
}

Interface for controlling callbacks when an interval has passed.

This interface is intended for software that requires repeated and/or one-shot timers and is willing to experience some jitter or imprecision in return for a simpler API that doesn’t require actual calculation of counter values. Software that requires more precisely timed callbacks should use the Alarm trait instead.

Required Methods

fn set_timer_client(&self, client: &'a dyn TimerClient)

Specify the callback to invoke when the timer interval expires. If there was a previously installed callback this call replaces it.

fn oneshot(&self, interval: Self::Ticks) -> Self::Ticks

Start a one-shot timer that will invoke the callback at least interval ticks in the future. If there is a timer currently pending, calling this cancels that previous timer. After a callback is invoked for a one shot timer, the timer MUST NOT invoke the callback again unless a new timer is started (either with repeating or one shot). Returns the actual interval for the timer that was registered. This MUST NOT be smaller than interval but MAY be larger.

fn repeating(&self, interval: Self::Ticks) -> Self::Ticks

Start a repeating timer that will invoke the callback every interval ticks in the future. If there is a timer currently pending, calling this cancels that previous timer. Returns the actual interval for the timer that was registered. This MUST NOT be smaller than interval but MAY be larger.

fn interval(&self) -> Option<Self::Ticks>

Return the interval of the last requested timer.

fn is_oneshot(&self) -> bool

Return if the last requested timer is a one-shot timer.

fn is_repeating(&self) -> bool

Return if the last requested timer is a repeating timer.

fn time_remaining(&self) -> Option<Self::Ticks>

Return how many ticks are remaining until the next callback, or None if the timer is disabled. This call is useful because there may be non-negligible delays between when a timer was requested and it was actually scheduled. Therefore, since a timer’s start might be delayed slightly, the time remaining might be slightly higher than one would expect if one calculated it right before the call to start the timer.

fn is_enabled(&self) -> bool

Returns whether there is currently a timer enabled and so a callback will be expected in the future. If is_enabled returns false then the implementation MUST NOT invoke a callback until a call to oneshot or repeating restarts the timer.

fn cancel(&self) -> Result<(), ErrorCode>

Cancel the current timer, if any. Value Result<(), ErrorCode> values are:

• Ok(()): no callback will be invoked in the future.
• Err(ErrorCode::FAIL): the timer could not be cancelled and a callback will be invoked in the future.

Implementors

impl<'a, A: Alarm<'a>> Timer<'a> for VirtualTimer<'a, A>

impl<'a, R: LiteXSoCRegisterConfiguration, F: Frequency> Timer<'a> for LiteXTimer<'a, R, F>