monotime

monotime

Strictly monotonic, lock-free generators for time-based identifiers.

Generators guarantee strict monotonicity even when:

• System clock is misconfigured
• Time is adjusted manually
• NTP steps the clock backward
• Process restarts (with a previously stored value)

This is accomplished by switching between real timestamps and logical clock whenever the system clock falls behind.

1. Gen

Produces raw int64 nanosecond timestamps. Fast and simple way to get unique and ordered timestamps.

// Initialize with the last known timestamp from your DB (or 0 for a fresh start)
mono := monotime.NewGen(lastKnownTimestamp)

// Get the next timestamp
ts1 := mono.Next() // e.g., 1731627315000000001
ts2 := mono.Next() // e.g., 1731627315000000002

Behavior

• If the system time is greater than the last emitted ID, generator uses the real timestamp.
• If the system clock ever moves backwards or stops, generator switches into logical mode, incrementing the nanosecond counter until real time catches up.
• When real time becomes greater again, generator resumes using real timestamps.

2. GenUUID

Produces K-sortable, time-ordered UUID v7 identifiers.
It embeds the monotonic nanosecond timestamp directly into the UUID structure and requires a node ID (24-bit) to ensure uniqueness across different services or cluster nodes.

This implementation also includes a custom magic prefix (0xE355) and zeroes out the rand_a portion, allowing to parse and verify that a UUID was generated by this package.

// Initialize with a unique node ID and the last known UUID from your DB
// (or monotime.ZeroUUID for a fresh start)
mono, err := monotime.NewGenUUID(nodeID, lastKnownUUID)

// Get the next UUID
id1 := mono.Next() // e.g., 0124e053-3580-7000-8e35-500000100001
id2 := mono.Next() // e.g., 0124e053-3580-7000-8e35-500000100002

Behavior

UUID v7 is time-ordered by design, but it normally does not guarantee strict monotonicity.
This implementation enforces it:

• For each generated UUID, the timestamp component is checked against the last emitted UUID.
• If the clock goes backward or stops, generator switches to logical timestamp increments.
• The nanosecond counter is incremented for each ID, ensuring uniqueness within the same millisecond.
• The generator never emits a UUID with a timestamp earlier than the previous one.

Running ahead of the clock

The generators must produce strictly increasing IDs.
This priority is more important than matching the system clock.

The core logic is: next = max(now, old + 1)

This means the generator's internal timestamp (last) can "run ahead" of the real system clock (now) in two specific scenarios:

1. Clock rollback: If the system clock moves backward (e.g., NTP update), now will be less than old.
   The generator must choose old + 1 to maintain monotonicity.

2. High throughput: If Next() is called in a very tight loop (e.g., millions of times per second), now might be equal to old (or time.Now() hasn't ticked forward).
   The generator must choose old + 1 to guarantee uniqueness.

In both cases, the generator starts issuing "logical" timestamps that are ahead of real time.
This is the correct and intended behavior.

Once the system clock eventually catches up (i.e., now becomes greater than the generator's last value), the generator will automatically switch back to using now as the base.

Impact on Generators

• Gen: the returned timestamp might be "in the future" compared to time.Now().UnixNano().

• GenUUID: the 48-bit millisecond part of the UUID will simply roll forward as the internal nanosecond counter increments. For example, if the counter is at ...999_999 (last nanosecond of a millisecond) and Next() is called, the new value will be ...000_000 and the millisecond portion of the UUID will be incremented by one.

Benchmarks

goos: linux
goarch: amd64
pkg: github.com/vapstack/monotime
cpu: AMD Ryzen 9 5900HX with Radeon Graphics
BenchmarkGenNext-16                     26904223       44.18 ns/op       0 B/op     0 allocs/op
BenchmarkGenNextParallel-16              5724068      208.6 ns/op        0 B/op     0 allocs/op
BenchmarkGenUUIDNext-16                 21900927       53.21 ns/op       0 B/op     0 allocs/op
BenchmarkGenUUIDNextParallel-16          5640699      214.6 ns/op        0 B/op     0 allocs/op
BenchmarkUUIDString-16                  33152881       31.97 ns/op      48 B/op     1 allocs/op
BenchmarkUUIDMarshalText-16             34586162       31.90 ns/op      48 B/op     1 allocs/op
BenchmarkUUIDParse-16                   130833162       9.132 ns/op      0 B/op     0 allocs/op
BenchmarkUUIDUnmarshalText-16           43163187       26.48 ns/op       0 B/op     0 allocs/op
BenchmarkUUIDUnmarshalBinary-16         147303606       8.138 ns/op      0 B/op     0 allocs/op
BenchmarkUUIDMarshalBinary-16           60735979       17.62 ns/op      16 B/op     1 allocs/op
BenchmarkTimeNow-16                     29152137       40.37 ns/op