Struct MonotonicClock

pub struct MonotonicClock { /* private fields */ }

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).

Implementations

impl MonotonicClock

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 spawns a background thread that updates a shared atomic counter once per millisecond, using a monotonic timer (Instant) to measure elapsed time since startup.

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.

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.

Panics

Panics if:

• The current system time is earlier than the given epoch
• The internal ticker thread has already been initialized

Example

use std::time::{Duration, Instant};
use ferroid::{MonotonicClock, TimeSource};
let now = std::time::SystemTime::now()
    .duration_since(std::time::UNIX_EPOCH)
    .unwrap();

// Or use a default epoch
// use ferroid::TWITTER_EPOCH,
// let now = TWITTER_EPOCH;
let clock = MonotonicClock::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. 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 (e.g., Snowflake-style ID encoding) by anchoring all generated times to a custom epoch of your choosing.

Trait Implementations

impl Clone for MonotonicClock

fn clone(&self) -> MonotonicClock

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for MonotonicClock

fn default() -> Self

Constructs a monotonic clock aligned to the default CUSTOM_EPOCH.

Panics if system time is earlier than the custom epoch.

impl TimeSource<u128> for MonotonicClock

fn current_millis(&self) -> u128

Returns the number of milliseconds since the configured epoch, based on the elapsed monotonic time since construction.

impl TimeSource<u64> for MonotonicClock

fn current_millis(&self) -> u64

Returns the number of milliseconds since the configured epoch, based on the elapsed monotonic time since construction.