proposal: time: add Instant type exposing Monotonic Time

[deankarn]

This will be short a suite as it's pretty basic.

There is appetite to have access to Monotonic Time in Go from previous issues, proposals and requests.

Proposed Additions

I propose adding a new type to the time package called Instant which will represent an opaque type that can only be compared with one another and allows measuring of duration. An existing implementation can be found here exert posted below for convenience.

package timeext

import "time"

// Instant represents a monotonic instant in time.
//
// Instants are opaque types that can only be compared with one another and allows measuring of duration.
type Instant int64

// NewInstant returns a new Instant.
func NewInstant() Instant {
	return Instant(NanoTime())
}

// Elapsed returns the duration since the instant was created.
func (i Instant) Elapsed() time.Duration {
	return time.Duration(NewInstant() - i)
}

// Since returns the duration elapsed from another Instant, or zero is that Instant is later than this one.
func (i Instant) Since(instant Instant) time.Duration {
	if instant > i {
		return 0
	}
	return time.Duration(i - instant)
}

This will allow access to Monotonic Time from Go, that already exists, but yet unexposed except through time.Time. The reason this is necessary is that time.Time is a very heavy structure and has a bunch of overhead that is not necessary if only measuring monotonically increasing time such as when used in Benchmarking and very hot code paths.

[gophun]

The whole point of https://go.googlesource.com/proposal/+/master/design/12914-monotonic.md was to avoid exposing monotonic clocks.

[deankarn]

OK...AND... this is a new proposal to expose them, for good reasons.

I do not agree that it should not be exposed.

[apparentlymart]

The linked earlier proposal that added monotonic time as an implementation detail describes the rationale for not exposing a separate monotonic API: that having two different APIs which behave exactly the same except during very occasional events like a leap second invites bugs where people use the wrong one.

However, I can see some subtlety in that argument: having two separate APIs where one is a strict subset of the other would seem to avoid the bug hazard and instead offer two APIs that both correctly handle monotonic time but where one of them is free of the overhead of also tracking wallclock time.

That seems like a plausible argument in theory, but I expect the best way to argue the value of such an addition would be to demonstrate:

• That the overhead of tracking wallclock time in systems that only need monotonic time is material for several specific applications, and
• That the overhead of tracking wallclock time cannot be reduced or eliminated as an implementation detail, without changing the API design.

I don't have a strong opinion about this myself. I offer the above just as an idea for how to add new information that might motivate revisiting the conclusions from that earlier proposal. It isn't typically sufficient only to disagree with the previous outcome without adding new information.

[deankarn]

I have read the paper before and what it's describing sounds very much like the different of SystemTime and Instant.

I'll refer to Rust's types because I think their documentation explains it better than I could ever.

• SystemTime
• Instant

I understand the rational of trying to limit the API surface area and hiding some lower level concepts and complexity under time.Time, however, in doing so and not exposing the other ways of dealing with time limits the Go language and specific, even if niche, valid use cases.

Maybe My proposal should be to add both SystemTime and Instant rather than just Instant.

In either case I am only interested in Monotonic time at this moment, here are some performance reasons, using the existing linked code in the proposal, I think this new type would benefit some real world libraries involving as caches, benchmarking and metrics off the top of my head.

func BenchmarkTime(b *testing.B) {
	for i := 0; i < b.N; i++ {
		instant := time.Now()
		_ = time.Since(instant)
	}
}

func BenchmarkInstant(b *testing.B) {
	for i := 0; i < b.N; i++ {
		instant := timeext.NewInstant()
		_ = instant.Elapsed()
	}
}

--- Result

goos: darwin
goarch: arm64
pkg: test
BenchmarkTime-8         16162813                66.93 ns/op            0 B/op          0 allocs/op
BenchmarkInstant-8      34626579                34.55 ns/op            0 B/op          0 allocs/op

Just dealing with Instant and not the additional time same approximately 50% of the time, on my machine at least. But that's not the whole story either, there's also the size different of representing each in memory:

	fmt.Println(unsafe.Sizeof(time.Now()))
	fmt.Println(unsafe.Sizeof(timeext.NewInstant()))

-----

// 24
// 8

time.Time is 3x more expensive memory wise than a primitive type to monitor monotonic time alone.

[dsnet]

For prior art, @tailscale has tstime.Now, which is basically what this proposal is asking for. A fast monotonic clock reading is useful in high-throughput packet processing.

[rsc]

From an API standpoint, start := time.Now(); ...; d := time.Since(start) is just about perfect. I do not want to introduce a second API to do that calculation. Among other things, the next thing that will happen is tons of CLs updating that idiom all over the place to use the new API. And what happens on systems without monotonic time? And so on and so on. Perhaps we can find a way to optimize this sequence instead. Let's look at the space and cpu costs separately.

For space, I find it very hard to believe the 24 vs 8 bytes matters at all. No one is making giant arrays of Instants. They're only subtracting them. People who really really care about the space can declare

var globalStart = time.Now()

and then store arrays of durations since globalStart.

For cpu, there is a factor of two in querying the time, since time.Now fetches wall time and monotonic time, and both have roughly the same cost (the RDTSC or equivalent, which takes O(10-30ns)). Later, when Since is used, the code already knows to fetch only monotonic time when that's all it needs. So for a Now+Since pair, we are fundamentally talking about optimizing 3 time fetches down to 2, or making the sequence 33% faster. (Benchmark at end confirming my claims.) So how can we get rid of that extra fetch?

People who really need to optimize away 50% of time.Now today already can do that:

// global
var base = time.Now()

// timing specific code
start := time.Since(base)
...
d := time.Since(base) - start

(tstime/mono.now could do the same thing – return int64(time.Since(baseWall)) – instead of linkname subterfuge.)

Given that there is a portable way to optimize away the one extra RDTSC already, I don't think it's terribly urgent to make an API change here, especially one that doubles the number of time types.

---

In the long term, I wonder if we can pressure the operating systems to add a function that gets a matched pair of both times. I'm not sure how much Windows or macOS matter anyway. For Linux the kernel vdso provides the accessors, and the two accessors do exactly the same thing except for which offset they add. Perhaps we could convince the Linux kernel team to accept a patch adding a "get both" call.

---

Benchmark

package timebench

import (
	"testing"
	"time"
	_ "unsafe"
)

var now time.Time
var d time.Duration

func BenchmarkTimeNow(b *testing.B) {
	for i := 0; i < b.N; i++ {
		now = time.Now()
	}
}

func BenchmarkTimeSince(b *testing.B) {
	for i := 0; i < b.N; i++ {
		d += time.Since(now)
	}
}

//go:linkname nanotime runtime.nanotime
func nanotime() int64

var inow int64
var id int64

func BenchmarkNanotime(b *testing.B) {
	for i := 0; i < b.N; i++ {
		inow = nanotime()
	}
}

func BenchmarkNanosince(b *testing.B) {
	for i := 0; i < b.N; i++ {
		id += nanotime() - inow
	}
}

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

[rsc]

CL 518135 has an optimization of time.now on Linux that avoids the second RDTSC in exchange for a few extra seqlock checks: instead of doing two regular clock_gettime, it does one regular clock_gettime and three coarse clock_gettime.
Specifically, it does

1. coarse realtime
2. coarse monotime
3. accurate realtime
4. coarse realtime

If (1) and (4) match, then 1, 2, 3, and 4 are all based on the same vdso time parameter update, meaning we can derive accurate monotime = (3) - (1) + (2).

On a relatively old (2014) Intel chip:

goos: linux
goarch: amd64
cpu: Intel(R) Xeon(R) CPU E5-2690 v3 @ 2.60GHz
BenchmarkTimeNow-48      	34610529	        32.72 ns/op
BenchmarkTimeNow-48      	36555846	        31.50 ns/op
BenchmarkTimeNow-48      	38082440	        31.24 ns/op
BenchmarkTimeSince-48    	53753678	        23.07 ns/op
BenchmarkTimeSince-48    	54047199	        23.06 ns/op
BenchmarkTimeSince-48    	50990598	        22.60 ns/op
BenchmarkNanotime-48     	56250726	        21.05 ns/op
BenchmarkNanotime-48     	57996276	        20.93 ns/op
BenchmarkNanotime-48     	53579763	        21.33 ns/op
BenchmarkNanosince-48    	51618572	        20.85 ns/op
BenchmarkNanosince-48    	54901424	        21.35 ns/op
BenchmarkNanosince-48    	58051893	        21.03 ns/op
PASS

On a relatively new (2022) AMD chip:

goos: linux
goarch: amd64
cpu: AMD Ryzen 9 7950X 16-Core Processor            
BenchmarkTimeNow-32      	60488217	        19.15 ns/op
BenchmarkTimeNow-32      	62665620	        18.61 ns/op
BenchmarkTimeNow-32      	64010760	        19.12 ns/op
BenchmarkTimeSince-32    	69519552	        17.10 ns/op
BenchmarkTimeSince-32    	69622921	        16.71 ns/op
BenchmarkTimeSince-32    	69680964	        16.37 ns/op
BenchmarkNanotime-32     	76564293	        16.15 ns/op
BenchmarkNanotime-32     	78482005	        15.08 ns/op
BenchmarkNanotime-32     	76783846	        15.09 ns/op
BenchmarkNanosince-32    	75900324	        15.91 ns/op
BenchmarkNanosince-32    	72681342	        15.81 ns/op
BenchmarkNanosince-32    	77141396	        15.82 ns/op

That is, on the old Intel chip, with the optimization, Now+Since takes (31+22)/(21+21) = 1.25X longer than optimal,
while on the new AMD chip, with the optimization, Now+Since takes (19+17)/(15+16) = 1.16X longer than optimal.
Without the optimization, it's more like (2+1)/(1+1) = 1.5X longer than optimal.

It is still difficult for me to understand the situation where 15ns overhead (for just time.Now) is no big deal but 30ns is a problem. Or where 30ns (for Now+Since) is no big deal but 45ns is a problem.

If we can drop the comparisons to 15 vs 19 and 31 vs 36 then I assume that situation gets even less compelling as a rationale
for whole new APIs.

Anyone is welcome to check out CL 518135 and see how it speeds up their systems. It is linux/amd64-only.