Struct MonotonicClock 

pub struct MonotonicClock<const N: u64 = 1> { /* private fields */ }

Available on target_has_atomic=64 and crate feature alloc and crate feature std only.

A monotonic time source that returns elapsed time since process start, offset from a user-defined epoch.

This avoids wall-clock adjustments (e.g., NTP or daylight savings changes) while still aligning timestamps to a fixed origin.

Internally, the clock measures time by capturing Instant::now() at construction and adding to it the duration elapsed since a given epoch (computed from SystemTime::now() at startup).

N controls the number of real milliseconds represented by one returned time unit. MonotonicClock and MonotonicClock<1> return literal milliseconds, while MonotonicClock<8> returns 8-millisecond ticks.

use ferroid::time::{MonotonicClock, UNIX_EPOCH};

let _ = MonotonicClock::<0>::with_epoch(UNIX_EPOCH);

Implementations

impl<const N: u64> MonotonicClock<N>

pub const GRANULARITY_MILLIS: u64 = N

pub fn with_epoch(epoch: Duration) -> Self

Constructs a monotonic clock using a custom epoch as the origin (t = 0), specified in milliseconds since the Unix epoch.

The provided epoch defines the zero-point for all future timestamps returned by this clock. Internally, the clock uses a shared background thread that updates a global atomic counter once per millisecond, using a monotonic timer (Instant) to measure elapsed time since startup.

Different epochs are supported by applying a per-instance offset to the shared ticker value.

On each call to current_millis, the clock returns the current tick value plus a fixed offset - the precomputed difference between the current wall-clock time (SystemTime::now()) and the given epoch. The final value is quantized into N-millisecond units.

This design avoids syscalls on the hot path and ensures that time never goes backward, even if the system clock is adjusted externally.

Parameters

• epoch: The origin timestamp, as a Duration since 1970-01-01 UTC.

Example

use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};

use ferroid::time::{MonotonicClock, TimeSource};
let now = SystemTime::now().duration_since(UNIX_EPOCH).unwrap();
// Or use a default epoch
// use ferroid::TWITTER_EPOCH,
// let now = TWITTER_EPOCH;

let clock = MonotonicClock::<1>::with_epoch(now);

std::thread::sleep(Duration::from_millis(5));

let ts: u64 = clock.current_millis();

// On most systems, this will report a value near 5 ms. However, due to
// small differences in timer alignment and sleep accuracy, the counter
// may be slightly behind or ahead on the first read. It's common to
// observe values like 4–6 ms after sleeping for 5 ms. The value will
// never go backward and is guaranteed to increase monotonically.
// assert!(ts >= ~5);

This allows you to control the timestamp layout by anchoring all generated times to a custom epoch of your choosing.

Trait Implementations

impl<const N: u64> Clone for MonotonicClock<N>

fn clone(&self) -> MonotonicClock<N>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<const N: u64> Debug for MonotonicClock<N>

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

Formats the value using the given formatter.

impl Default for MonotonicClock<1>

fn default() -> Self

Constructs a monotonic clock aligned to the default UNIX_EPOCH.

impl<const N: u64> TimeSource<u64> for MonotonicClock<N>

fn current_millis(&self) -> u64

Returns the number of N-millisecond units since the configured epoch, based on the elapsed monotonic time since construction.

const GRANULARITY_MILLIS: u64 = Self::GRANULARITY_MILLIS

The number of real milliseconds represented by one returned time unit.

impl<const N: u64> TimeSource<u128> for MonotonicClock<N>

fn current_millis(&self) -> u128

Returns the number of N-millisecond units since the configured epoch, based on the elapsed monotonic time since construction.

const GRANULARITY_MILLIS: u64 = Self::GRANULARITY_MILLIS

The number of real milliseconds represented by one returned time unit.