time: add microseconds-based APIs

[pmarks-net]

The upper bound of a nanoseconds-since-1970 timestamp is not very far away, on the timescale of human civilization:

time.Unix(0, math.MaxInt64)
2262-04-11 23:47:16.854775807 +0000 UTC

Suggestions for improvement:

• Document the limits at https://golang.org/pkg/time/, and deprecate the UnixNano function.
• Create a UnixMicro function, which works until the year 294247.

I notice a lot of code that tries to implement UnixMicro as UnixNano()/1000, so it would be good to have a centralized, correct implementation.

[griesemer]

For Go25.

[adg]

I don't understand the complaint. This limitation is built into the design, and is why time.Unix first takes a seconds argument followed by a nanoseconds argument for precision.

time.Unix(math.MaxInt64, 0) represents the year 219250468, so I think this API is solid for the foreseeable future.

[adg]

Oh, I see. This is about UnixNano.

Note the docs already cover this:

The result is undefined if the Unix time in nanoseconds cannot be represented by an int64.

[pmarks-net]

The documentation should specify what the limits are, because the actual values can be surprising to people who assume that int64 is practically infinite. It seems bad to promote a time format which is more restrictive than YYYY without spelling out the risks.

And what about creating a microseconds interface? I haven't tested the following code yet, but you can observe that the conversion functions are nontrivial in both directions:

return time.Unix(usec / 1000000, (usec % 1000000) * 1000)

return t.Unix() * 1000000 + int64(t.Nanosecond() / 1000)

[adg]

Who uses microseconds (apart from JavaScript)?

[pmarks-net]

"Microseconds since 1970" a very common format within Google at least. Bigtable and Spanner are among the more prominent users.

[adg]

Seems like something worth considering.

[extemporalgenome]

I don't see why we would deprecate the UnixNano method. The argument seems to be that time.Now().UnixNano() will be undefined when run ~246 years from now. By the same argument, time.Now().UnixMicro() will also be undefined in a mere ~292231 years.

There's no point in deprecating UnixNano, so this proposal should only be concerned with weighing the benefit of adding UnixMicro.

[pmarks-net]

Notice that Unix() returns int64, not int32. Had it been the latter, it would make sense to argue for its deprecation. In order-of-magnitude terms, UnixNano() is only marginally better than a 32-bit unix timestamp.

We're obviously going to have a bad time when 9999 rolls around, but designing a format that can't even get that far seems like an obvious mistake.

[uluyol]

Whatever software is around in 200 years can spend 46 years migrating to storing 128-bit timestamps. This sounds like a documentation bug if anything.

The few people who need a UnixMicro can write a trivial function.

[pmarks-net]

The few people who need a UnixMicro can write a trivial function.

But the function is not trivial, and in practice most people get it wrong. UnixNano()/1000 gives you the worst of both worlds, with regards to range and precision.

[ianlancetaylor]

I think we should postpone this issue until Go has a int128 type.

[pmarks-net]

Why should adding microseconds-based APIs be blocked on an int128 type? If time.UnixNano128(...) and t.UnixNano128() existed, then microseconds-based APIs would no longer be necessary.

[minux]

I don't think the year 2262 problem is too big. For example, ext4 also has this (though it's using uint64, and leaves 34 bits for the second part). We can certainly wait a little longer to solve it. And when Go has int128, it can be solved once and for all. That is, the year 2262 limit does not justify the new API. (I'd argue that if you care, you should design it to store int64 sec + int32 nsec instead of int64 usec)

[nathany]

re: int128 is issue #9455

[bradfitz]

@nathany, I think @ianlancetaylor's int128 comment was a joke. He's saying that by the time we have an int128 type (distant future), only then would we care about the year 2262, and if we had an int128 anyway, then we wouldn't need to do anything in this issue, because nanoseconds would again be sufficient.

Jokes are funnier when they're explained, I know. Sorry.

[ianlancetaylor]

I didn't really mean it to be a joke as such. I mean more or less what @bradfitz says, but seriously. Assuming Go continues to exist at all, it will get an int128 type at least a century before 2262. There is no need to introduce a microsecond API, we just need to change the time package to use int128.

[pmarks-net]

The first bullet point (document the limits) was fixed by https://go-review.googlesource.com/#/c/28478/

[rsc]

The time.Time representation itself has no problem with the year 2262, by design. Conversions like t.UnixNano exist for interoperability with other systems that use those encodings. They are not fundamental to the API, just helpful when you need that conversion. Google programs that use UnixNano()/1000 can keep doing so. I agree with the various comments that we can fix this in 200 years (with plenty of time to spare) by changing the result of UnixNano to int128. Until then, now that the documentation makes the limitation clear, I think we can close this issue.

[pmarks-net]

For the record, I don't think "changing the result of UnixNano to int128" is possible, because of all the existing code that assumes the result is an int64. This will almost certainly require a new API, like UnixNano128().