Skip to content

Commit e7e2fa0

Browse files
committed
time: add notes about monotonic time paused during system sleep
1 parent a639078 commit e7e2fa0

File tree

1 file changed

+46
-1
lines changed

1 file changed

+46
-1
lines changed

src/time/time.go

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,10 @@
5353
//
5454
// On some systems the monotonic clock will stop if the computer goes to sleep.
5555
// On such a system, t.Sub(u) may not accurately reflect the actual
56-
// time that passed between t and u.
56+
// time that passed between t and u. This may impact a bunch of functions/methods:
57+
// [time.Since], [time.Until], [Time.Add], [Time.Sub], [Time.After], [Time.Before]
58+
// [Time.Equal], [Time.Compare].
59+
// Use [Time.Round](0) or [Time.Truncate](0) to walkaround.
5760
//
5861
// Because the monotonic clock reading has no meaning outside
5962
// the current process, the serialized forms generated by t.GobEncode,
@@ -254,6 +257,11 @@ func (t *Time) mono() int64 {
254257
}
255258

256259
// After reports whether the time instant t is after u.
260+
//
261+
// On some systems the monotonic clock will stop if the computer goes to sleep.
262+
// On such a system, this may not accurately reflect the actual time that
263+
// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround.
264+
// See issue: https://github.com/golang/go/issues/66870
257265
func (t Time) After(u Time) bool {
258266
if t.wall&u.wall&hasMonotonic != 0 {
259267
return t.ext > u.ext
@@ -264,6 +272,11 @@ func (t Time) After(u Time) bool {
264272
}
265273

266274
// Before reports whether the time instant t is before u.
275+
//
276+
// On some systems the monotonic clock will stop if the computer goes to sleep.
277+
// On such a system, this may not accurately reflect the actual time that
278+
// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround.
279+
// See issue: https://github.com/golang/go/issues/66870
267280
func (t Time) Before(u Time) bool {
268281
if t.wall&u.wall&hasMonotonic != 0 {
269282
return t.ext < u.ext
@@ -275,6 +288,11 @@ func (t Time) Before(u Time) bool {
275288

276289
// Compare compares the time instant t with u. If t is before u, it returns -1;
277290
// if t is after u, it returns +1; if they're the same, it returns 0.
291+
//
292+
// On some systems the monotonic clock will stop if the computer goes to sleep.
293+
// On such a system, this may not accurately reflect the actual time that
294+
// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround.
295+
// See issue: https://github.com/golang/go/issues/66870
278296
func (t Time) Compare(u Time) int {
279297
var tc, uc int64
280298
if t.wall&u.wall&hasMonotonic != 0 {
@@ -299,6 +317,11 @@ func (t Time) Compare(u Time) int {
299317
// For example, 6:00 +0200 and 4:00 UTC are Equal.
300318
// See the documentation on the Time type for the pitfalls of using == with
301319
// Time values; most code should use Equal instead.
320+
//
321+
// On some systems the monotonic clock will stop if the computer goes to sleep.
322+
// On such a system, this may not accurately reflect the actual time that
323+
// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround.
324+
// See issue: https://github.com/golang/go/issues/66870
302325
func (t Time) Equal(u Time) bool {
303326
if t.wall&u.wall&hasMonotonic != 0 {
304327
return t.ext == u.ext
@@ -870,6 +893,11 @@ func (d Duration) Abs() Duration {
870893
}
871894

872895
// Add returns the time t+d.
896+
// On some systems the monotonic clock will stop if the computer goes to sleep.
897+
//
898+
// On such a system, this may not accurately reflect the actual time that
899+
// t+d. Use [Time.Round](0) or [Time.Truncate](0) to walkaround.
900+
// See issue: https://github.com/golang/go/issues/66870
873901
func (t Time) Add(d Duration) Time {
874902
dsec := int64(d / 1e9)
875903
nsec := t.nsec() + int32(d%1e9)
@@ -898,6 +926,11 @@ func (t Time) Add(d Duration) Time {
898926
// value that can be stored in a [Duration], the maximum (or minimum) duration
899927
// will be returned.
900928
// To compute t-d for a duration d, use t.Add(-d).
929+
//
930+
// On some systems the monotonic clock will stop if the computer goes to sleep.
931+
// On such a system, this may not accurately reflect the actual time that
932+
// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround.
933+
// See issue: https://github.com/golang/go/issues/66870
901934
func (t Time) Sub(u Time) Duration {
902935
if t.wall&u.wall&hasMonotonic != 0 {
903936
return subMono(t.ext, u.ext)
@@ -927,6 +960,12 @@ func subMono(t, u int64) Duration {
927960

928961
// Since returns the time elapsed since t.
929962
// It is shorthand for time.Now().Sub(t).
963+
//
964+
// On some systems the monotonic clock will stop if the computer goes to sleep.
965+
// On such a system, this may not accurately reflect the actual time that
966+
// passed between t and process start time.
967+
// Use [Time.Round](0) or [Time.Truncate](0) to walkaround.
968+
// See issue: https://github.com/golang/go/issues/66870
930969
func Since(t Time) Duration {
931970
if t.wall&hasMonotonic != 0 {
932971
// Common case optimization: if t has monotonic time, then Sub will use only it.
@@ -937,6 +976,12 @@ func Since(t Time) Duration {
937976

938977
// Until returns the duration until t.
939978
// It is shorthand for t.Sub(time.Now()).
979+
//
980+
// On some systems the monotonic clock will stop if the computer goes to sleep.
981+
// On such a system, this may not accurately reflect the actual time that
982+
// passed between t and now.
983+
// Use [Time.Round](0) or [Time.Truncate](0) to walkaround.
984+
// See issue: https://github.com/golang/go/issues/66870
940985
func Until(t Time) Duration {
941986
if t.wall&hasMonotonic != 0 {
942987
// Common case optimization: if t has monotonic time, then Sub will use only it.

0 commit comments

Comments
 (0)