Struct Upkeep

pub struct Upkeep { /* private fields */ }

Ultra-low-overhead access to slightly-delayed time.

In some applications, there can be a need to check the current time very often, so much so that the overhead of checking the time can begin to eat up measurable overhead. For some of these cases, the time may need to be accessed often but does not necessarily need to be incredibly accurate: one millisecond granularity could be entirely acceptable.

For these cases, we provide a slightly-delayed version of the time to callers via Clock::recent, which is updated by a background upkeep thread. That thread is configured and spanwed via Upkeep.

Upkeep can construct a new clock (or be passed an existing clock to use), and given an update interval, and it will faithfully attempt to update the global recent time on the specified interval. There is a trade-off to be struck in terms of how often the time is updated versus the required accuracy. Checking the time and updating the global reference is itself not zero-cost, and so care must be taken to analyze the number of readers in order to ensure that, given a particular update interval, the upkeep thread is saving more CPU time than would be spent otherwise by directly querying the current time.

The recent time is read and written atomically. It is global to an application, so if another codepath creates the upkeep thread, the interval chosen by that instantiation will be the one that all callers of Clock::recent end up using.

Multiple upkeep threads cannot exist at the same time. A new upkeep thread can be started if the old one is dropped and returns.

In terms of performance, reading the recent time can be up to two to three times as fast as reading the current time in the optimized case of using the Time Stamp Counter source. In practice, while a caller might expect to take 12-14ns to read the TSC and scale it to reference time, the recent time can be read in 4-5ns, with no reference scale conversion required.

Implementations

impl Upkeep

pub fn new(interval: Duration) -> Upkeep

Creates a new Upkeep.

This creates a new internal clock for acquiring the current time. If you have an existing Clock that is already calibrated, it is slightly faster to clone it and construct the builder with new_with_clock to avoid recalibrating.

pub fn new_with_clock(interval: Duration, clock: Clock) -> Upkeep

Creates a new Upkeep with the specified Clock instance.

pub fn start(self) -> Result<Handle, Error>

Start the upkeep thread, periodically updating the global coarse time.

Handle represents a drop guard for the upkeep thread if it is successfully spawned. Dropping the handle will also instruct the upkeep thread to stop and exist, so the handle must be held while the upkeep thread should continue to run.

Errors

If either an existing upkeep thread is running, or there was an issue when attempting to spawn the upkeep thread, an error variant will be returned describing the error.

Trait Implementations

impl Debug for Upkeep

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

Formats the value using the given formatter.