[−][src]Crate embedded_time
Embedded Time
embedded-time
provides a comprehensive library for implementing Clock
abstractions over
hardware to generate Instant
s and using Duration
s (Seconds
, Milliseconds
, etc) in
embedded systems. The approach is similar to the C++ chrono
library. A Duration
consists of
an integer value (chosen by the user from either i32 or i64) as well as a const ratio where the
integer value multiplied by the ratio is the seconds represented by the Duration
. Put another
way, the ratio is the precision of the LSbit of the integer. This structure avoids unnecessary
arithmetic. For example, if the Duration
type is Milliseconds
, a call to the Duration::count()
method simply returns the stored integer value directly which is the number of milliseconds
being represented. Conversion arithmetic is only performed when explicitly converting between
time units.
Motivation
The handling of time on embedded systems is generally much different than that of OSs. For instance, on an OS, the time is measured against an arbitrary epoch. Embedded systems generally don't know (nor do they care) what the real time is, but rather how much time has passed since the system has started.
Background
Drawbacks of the core::Duration type
- The storage is
u64
seconds andu32
nanoseconds.- This is huge overkill and adds needless complexity beyond what is required (or desired) for embedded systems.
- Any read requires arithmetic to convert to the requested units
- This is much slower than this project's implementation of what is analogous to a tagged union of time units.
What is an Instant?
In the Rust ecosystem, it appears to be idiomatic to call a now()
associated function from an Instant type. There is generally no concept of a "Clock". I believe that using the Instant
in this way is a violation of the separation of concerns principle. What is an Instant
? Is it a time-keeping entity from which you read the current instant in time, or is it that instant in time itself. In this case, it's both.
As an alternative, the current instant in time could be read from a Clock. The Instant
read from the Clock
has the same precision and width (integer type) as the Clock
. Requesting the difference between two Instant
s gives a Duration
which can have different precision and/or width.
Definitions
Clock - Any entity that periodically counts (ie a hardware timer peripheral). Generally, this needs to be monotonic. Here a wrapping timer is considered monotonic as long as it fulfills the other requirements.
Wrapping Timer - A timer that when at its maximum value, the next count is the minimum value.
Instant - A specific instant in time ("time-point") returned by calling Clock::now()
.
Duration - The difference of two instances (the duration of time elapsed from one instant until another).
Notes
Some parts of this crate were derived from various sources:
RTFM
time
(Specifically thetime::NumbericalDuration
implementations for primitive integers)
Example Usage
struct SomeClock; impl embedded_time::Clock for SomeClock { type Rep = i64; fn now() -> Instant<Self> { // ... } } impl embedded_time::Period for SomeClock { const PERIOD: Ratio<i32> = Ratio::<i32>::new_raw(1, 16_000_000); } let instant1 = SomeClock::now(); // ... let instant2 = SomeClock::now(); assert!(instant1 < instant2); // instant1 is *before* instant2 let duration: Option<Microseconds<i64>> = instant2.elapsed_since(&instant1); // duration is the difference between the instances assert!(duration.is_some()); assert_eq!(instant1 + duration.unwrap(), instant2);
Re-exports
pub use duration::time_units; |
pub use duration::Duration; |
Modules
duration | Duration types/units creation and conversion. |
instant | |
prelude | A collection of imports that are widely useful. |
Structs
Ratio | Represents the ratio between two numbers. |
Traits
Clock | |
Period | |
TimeRep | Create |