Struct quanta::Clock

pub struct Clock { /* fields omitted */ }

Unified clock for taking measurements.

Methods

impl Clock

pub fn new() -> Clock

Creates a new clock with the optimal reference and source.

Both the reference clock and source clock are chosen at compile-time to be the fastest underlying clocks available. The source clock is calibrated against the reference clock if need be.

pub fn mock() -> (Clock, Arc<Mock>)

Creates a new clock that is mocked for controlling the underlying time.

Returns a Clock instance and a handle to the underlying Mock source so that the caller can control the passage of time.

pub fn now(&self) -> Instant

Gets the current time, scaled to reference time.

Returns an Instant

pub fn raw(&self) -> u64

Gets the underlying time from the source clock.

Value is not guaranteed to be in nanoseconds.

It requires conversion to reference time, however, via scaled or delta.

If you need maximum accuracy in your measurements, consider using start and end.

pub fn start(&self) -> u64

Gets the underlying time from the source clock, specific to starting an operation.

Value is not guaranteed to be in nanoseconds.

Provides the same functionality as raw, but tries to ensure that no extra CPU instructions end up executing after the measurement is taken. Since normal processors are typically out-of-order, other operations that logically come before a call to this method could be reordered to come after the measurement, thereby skewing the overall time measured.

pub fn end(&self) -> u64

Gets the underlying time from the source clock, specific to ending an operation.

Value is not guaranteed to be in nanoseconds.

Provides the same functionality as raw, but tries to ensure that no extra CPU instructions end up executing before the measurement is taken. Since normal processors are typically out-of-order, other operations that logically come after a call to this method could be reordered to come before the measurement, thereby skewing the overall time measured.

pub fn scaled(&self, value: u64) -> Instant

Scales a raw measurement to reference time.

You must scale raw measurements to ensure your result is in nanoseconds. The raw measurement is not guaranteed to be in nanoseconds and may vary. It is only OK to avoid scaling raw measurements if you don't need actual nanoseconds.

Returns an Instant.

pub fn delta(&self, start: u64, end: u64) -> Duration

Calculates the delta between two measurements, and scales to reference time.

Value is in nanoseconds.

This method is slightly faster when you know you need the delta between two raw measurements, or a start/end measurement, than using scaled for both conversions.

pub fn recent(&self) -> Instant

Gets the most recent current time, scaled to reference time.

This method provides ultra-low-overhead access to a slightly-delayed version of the current time. Instead of querying the underlying source clock directly, an external task -- the upkeep thread -- is responsible for polling the time and updating a global reference to the "recent" time, which this method then loads.

This method is usually at least 2x faster than querying the clock directly, and could be even faster in cases where getting the time goes through a heavy virtualized interface, or requires syscalls.

The resolution of the time is still in nanoseconds, although the accuracy can only be as high as the interval at which the upkeep thread updates the global recent time.

For example, the upkeep thread could be configured to update the time every millisecond, which would provide a measurement that should be, at most, 1ms behind the actual time.

If the upkeep thread has not been started, the return value will be 0.

Returns an Instant.

Trait Implementations

impl Clone for Clock

fn clone(&self) -> Clock

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Clock

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Default for Clock

fn default() -> Clock

Returns the "default value" for a type.