Module tor_rtcompat::coarse_time

Wrapper for coarsetime.

We want to be able to mock coarsetime in tor-rtmock, so we need coarse time provision to to be part of a Runtime.

(We can’t just use coarsetime’s mocking facilities, because they still use a process-wide global for the current time.)

We use [coarsetime::Instant::now], which in turn calls the OS’s CLOCK_MONOTONIC_COARSE, CLOCK_MONOTONIC_FAST, or similar.

We don’t use the non-updating coarsetime methods such as coarsetime::Instant:: now_without_cache_update. So, nor do we start a [coarsetime::Updater] update thread (that would wake up frequently).

We don’t use (or expose any way to use) coarsetime::Clock; we don’t think that’s a useful thing.

Future possibilities

If we ever need to mix-and-match coarse time values from low-level crates like tor-proto, with the wrapped-up coarsetime we have here, we have the following options:

a. move much of this (perhaps the whole module) to a lower-layer crate (let’s call it tor-coarsetime) and have everyone use that. Even the CoarseTimeProvider trait could be moved down, since it doesn’t depend on anything else from tor-rtcompat.

b1. semver-expose coarsetime here in tor-rtcompat, perhaps optionally, by exposing a conversions with coarsetime::Instant.

b2. abolish the newtypes and instead make the types here aliases for coarsetime

Macros

• impl_add_sub 🔒
  implement $AddSub<CoarseDuration> for CoarseInstant, and *Assign

Structs

• CoarseDuration
  A duration with reduced precision, and, in the future, saturating arithmetic
• CoarseInstant
  A monotonic timestamp with reduced precision, and, in the future, saturating arithmetic
• RealCoarseTimeProvider
  Provider of reduced-precision timestamps using the real OS clock