Hybrid Clocks Crate Inward Rust

I receive got been learning Rust inwards my spare time. It has a really steep learning curve, but inwards render yous acquire to utilisation an elegant, fast, in addition to security programming linguistic communication yous tin dismiss utilisation anywhere from embedded systems to datacenter computing. Rust stole similar an artist the best concepts from several languages in addition to combined them nether i roof amongst style. Rust has seen a lot of traction recently, in addition to I intend Rust is hither to rest for a long time. 

In the final dyad months, I receive got been writing pocket-sized programs to exercise Rust, in addition to of late I decided I should become bigger in addition to consider reading a existent code base, but something amongst manageable size. I chose to focus on the hybrid logical clocks in addition to provides a strictly-monotonic clock that tin dismiss live used to determine if i lawsuit happens-before another.

The agency yous utilisation the crate is to outset do a clock past times calling a Clock implementation/subtype, in addition to and thence past times getting a timestamp past times calling the similar a shot method on the clock. 

The now() method is provided after a score of indirection, dispensed past times i of the underlying 3 clocksources.  I explicate this inwards the trait objects heading below.

Timestamp

Let's start amongst the Timestamp struct that the now() method returns. This is defined inwards lib.rs, every bit that is where most of the activity is. 

The epoch hither is a counter similar the Raft epoch. If a node likes to reset the clock, in addition to continue, it tin dismiss growth the epoch, in addition to start a novel era. The crate does non prescribe a agency to utilisation this. 

Clock 

Clock uses the timestamp struct via saving the final observed fourth dimension every bit the last_observed field. The Clock too has an epoch, for incrementing the epoch, in addition to timestamping amongst that. 

Finally the src plain is the clocksource. Clock takes whatever element south that implements the ClockSource trait, in addition to assigns it to src. There are 3 unlike implementations of ClockSource inwards the crate:

• Manual Clock is what yous laid in addition to update, it doesn't utilisation a physical organisation clock.
• WallNS is the organisation clock UNIX fourth dimension inwards nanoseconds. 
• WallMS is the same matter but for microseconds I think.

ClockSource Trait

The ClockSource Trait, inwards mod.rs, is the high score trait.

(The type Delta is used subsequently inwards the crate for OffSetLimiter interface for setting the max_offset for limiting the window of observed timestamps to update the clock with. My outset idea near it was for comparison, but in addition to thence I realized that, but past times deriving from Ord, the Timestamp already allows comparisons amongst <, =, >.)

The similar a shot method inwards this trait is routed to the underlying 3 clocksource implementations inwards lib.rs. 

The similar a shot method inwards lib.rs outset calls the read_pt to read the fourth dimension in addition to and thence calls do_observe to update the clock. There is some other method called notice that takes a message in addition to calls do_observe the same agency to acquire the clock updated. I intend that is actually clever in addition to efficient code, combining ii cases inwards to one.  

This gives monotonicity for a unmarried clock source every bit well, because do_observe is used amongst honour to the read_pt of physical time. Even when physical fourth dimension from read_pt would become dorsum the lawsuit would non become back. This is made possible because nosotros are keeping the final lawsuit inwards last_observed every bit component of the clock struct.

Do notice provides a really overnice utilisation of match. It combines cases cleverly, in addition to updates the clock amongst minimal checks. Here is what nosotros had inwards the newspaper to do that. And the side past times side i is inwards TLA+.

I do receive got a nit alternative near do_observe when adapting observation.clone() at describe of piece of job 142 though. In gild to brand the novel hybrid clock greater than the observed, the code should growth the count past times one. But, this is non a bug, because clock.observe doesn't render a value. Instead after do_observe, clock.now() needs to live called to acquire the value, in addition to that ensures the novel clock is strictly larger than the observed.

Trait objects

Let's dig downward to the trait object utilisation case. Let's await at the Clock<WallNS> in addition to Clock<S: ClockSource> relation. The other ii clocks Clock<WallMS> in addition to Clock<ManualClock> receive got similar relation. 

Clock<WallNS> has a Clock::new(WallNS) to render a clock. The tilt "let mut clock_a = Clock::wall_ns()?;" is piped to this inwards lib.rs:

The Clock<WallNS> implementation, calls the Clock struct implementation amongst WallNS every bit the src. So it is piped to the "impl<S: ClockSource> Clock<S>, ::new()" function,  which sets the last_observed inwards the Clock struct the outset invocation of src.now(), calling dorsum wall_ns.now to acquire the physical time. Similarly read_pt method too calls the similar a shot method which is dispensed past times the underlying right clock source.

By the way, WallNS an empty struct type "pub struct WallNS;", which but has a ClockSource implementation inwards wall_ns.rs: 

OffsetLimiter

The crate has some other struct OffsetLimiter that builds on ClockSource. OffsetLimiter is used for implementing  wrapper some Clock that volition spend upwards updates exterior of the epsilon tolerance window of the clock update.

Testing

I volition beak near the tests inwards the crate, in addition to how I wrote some other utilisation example programs for testing hybrid clocks at a subsequently post. 

Share this post