Crate fast_clock 

Low-overhead timing without hiding the details from you.

Core abstractions

• Time: Defines the Instant and Duration types for a clock domain and the arithmetic between them.
• Clock: Provides Clock::now and names the associated Time and DurationCalibration types.
• DurationCalibration: Converts durations to/from nanoseconds as u64.
• CalibratedClock: Bundles a Clock with its calibration for convenient passing.
• ClockSynchronization: Correlates instants between two clock domains.

Standard library clocks

std_clocks::InstantClock and std_clocks::SystemClock wrap std::time::Instant and std::time::SystemTime. They use InherentlyCalibrated, as their duration type is directly convertible to/from nanoseconds.

Hardware clocks

These are gated on their target architecture, so only the matching one is present.

tsc::Tsc reads the x86_64 timestamp counter. Its ticks are not nanoseconds, so calibration via wrapping_u64::U64Calibration is required. Calibration also produces a ClockSynchronization that can convert TSC instants to std::time::Instant and vice versa.

generic_timer::GenericTimer is the aarch64 counterpart. It can be calibrated the same way, or without a measurement from the frequency the hardware reports.

let tsc = Tsc::try_new_assume_stable().unwrap();
let (calibration, sync) = U64Calibration::new_with_std_instant(
    &tsc,
    std::time::Duration::from_millis(100),
);
let clock = CalibratedClock { clock: tsc, calibration };

let t0 = clock.clock.now();
// ... timed section ...
let t1 = clock.clock.now();

let duration = WrappingU64Time::instant_sub(t1, t0);
let duration_ns: u64 = clock.calibration.convert_to_ns(duration);

// Convert a TSC instant to std::time::Instant using the synchronization point.
let std_instant = sync.to_a(t0, &InherentlyCalibrated, &clock.calibration);

Fast clock

FastClock is a type alias for a fast default clock for the target architecture. This allows code using the clock to be portable. Note that the associated types of the clock may vary between architectures.

It is currently implemented only for x86_64 and aarch64. Both have very similar initialization options and are zero sized. On aarch64 the fast-clock-aarch64-56bit feature selects GenericTimer<56> instead of GenericTimer<64>. See generic_timer::GenericTimer for the tradeoffs involved.

Features

Feature	Default	Description
std	yes	Enables std_clocks and std-dependent methods.
x86_64-tsc	yes	Enables tsc (x86_64 only).
aarch64-generic-timer	yes	Enables generic_timer (aarch64 only).
fast-clock	yes	Enables FastClock. Implies the hardware clock features above.
fast-clock-aarch64-56bit	no	Makes FastClock use a 56 bit counter on aarch64. Implies fast-clock.

Contributions adding more clocks are welcome.

Modules

generic_timer

std_clocks

tsc

wrapping_u64

Structs

CalibratedClock

A Clock bundled with its DurationCalibration.

ClockSynchronization

A pair of instants from two clocks that correspond to roughly the same point in time.

InherentlyCalibrated

Calibration type for clocks whose native duration is already in nanoseconds.

Traits

Clock

A source of time readings.

DurationCalibration

Converts a clock’s native duration type to and from nanoseconds.

Time

Arithmetic types and operations for a clock domain.

Type Aliases

FastClock

A type alias for a fast default clock for the target architecture.

FastClockCalibration

The DurationCalibration of FastClock.

FastClockTime

The Time of FastClock.