From e7e2fa00734ca165a8613eaa1eebd2ada4d651c4 Mon Sep 17 00:00:00 2001 From: plasmatium Date: Fri, 19 Apr 2024 22:30:28 +0800 Subject: [PATCH 1/7] time: add notes about monotonic time paused during system sleep --- src/time/time.go | 47 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/src/time/time.go b/src/time/time.go index 8c24e1c48106ef..7f320da5113a4c 100644 --- a/src/time/time.go +++ b/src/time/time.go @@ -53,7 +53,10 @@ // // On some systems the monotonic clock will stop if the computer goes to sleep. // On such a system, t.Sub(u) may not accurately reflect the actual -// time that passed between t and u. +// time that passed between t and u. This may impact a bunch of functions/methods: +// [time.Since], [time.Until], [Time.Add], [Time.Sub], [Time.After], [Time.Before] +// [Time.Equal], [Time.Compare]. +// Use [Time.Round](0) or [Time.Truncate](0) to walkaround. // // Because the monotonic clock reading has no meaning outside // the current process, the serialized forms generated by t.GobEncode, @@ -254,6 +257,11 @@ func (t *Time) mono() int64 { } // After reports whether the time instant t is after u. +// +// On some systems the monotonic clock will stop if the computer goes to sleep. +// On such a system, this may not accurately reflect the actual time that +// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround. +// See issue: https://github.com/golang/go/issues/66870 func (t Time) After(u Time) bool { if t.wall&u.wall&hasMonotonic != 0 { return t.ext > u.ext @@ -264,6 +272,11 @@ func (t Time) After(u Time) bool { } // Before reports whether the time instant t is before u. +// +// On some systems the monotonic clock will stop if the computer goes to sleep. +// On such a system, this may not accurately reflect the actual time that +// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround. +// See issue: https://github.com/golang/go/issues/66870 func (t Time) Before(u Time) bool { if t.wall&u.wall&hasMonotonic != 0 { return t.ext < u.ext @@ -275,6 +288,11 @@ func (t Time) Before(u Time) bool { // Compare compares the time instant t with u. If t is before u, it returns -1; // if t is after u, it returns +1; if they're the same, it returns 0. +// +// On some systems the monotonic clock will stop if the computer goes to sleep. +// On such a system, this may not accurately reflect the actual time that +// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround. +// See issue: https://github.com/golang/go/issues/66870 func (t Time) Compare(u Time) int { var tc, uc int64 if t.wall&u.wall&hasMonotonic != 0 { @@ -299,6 +317,11 @@ func (t Time) Compare(u Time) int { // For example, 6:00 +0200 and 4:00 UTC are Equal. // See the documentation on the Time type for the pitfalls of using == with // Time values; most code should use Equal instead. +// +// On some systems the monotonic clock will stop if the computer goes to sleep. +// On such a system, this may not accurately reflect the actual time that +// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround. +// See issue: https://github.com/golang/go/issues/66870 func (t Time) Equal(u Time) bool { if t.wall&u.wall&hasMonotonic != 0 { return t.ext == u.ext @@ -870,6 +893,11 @@ func (d Duration) Abs() Duration { } // Add returns the time t+d. +// On some systems the monotonic clock will stop if the computer goes to sleep. +// +// On such a system, this may not accurately reflect the actual time that +// t+d. Use [Time.Round](0) or [Time.Truncate](0) to walkaround. +// See issue: https://github.com/golang/go/issues/66870 func (t Time) Add(d Duration) Time { dsec := int64(d / 1e9) nsec := t.nsec() + int32(d%1e9) @@ -898,6 +926,11 @@ func (t Time) Add(d Duration) Time { // value that can be stored in a [Duration], the maximum (or minimum) duration // will be returned. // To compute t-d for a duration d, use t.Add(-d). +// +// On some systems the monotonic clock will stop if the computer goes to sleep. +// On such a system, this may not accurately reflect the actual time that +// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround. +// See issue: https://github.com/golang/go/issues/66870 func (t Time) Sub(u Time) Duration { if t.wall&u.wall&hasMonotonic != 0 { return subMono(t.ext, u.ext) @@ -927,6 +960,12 @@ func subMono(t, u int64) Duration { // Since returns the time elapsed since t. // It is shorthand for time.Now().Sub(t). +// +// On some systems the monotonic clock will stop if the computer goes to sleep. +// On such a system, this may not accurately reflect the actual time that +// passed between t and process start time. +// Use [Time.Round](0) or [Time.Truncate](0) to walkaround. +// See issue: https://github.com/golang/go/issues/66870 func Since(t Time) Duration { if t.wall&hasMonotonic != 0 { // Common case optimization: if t has monotonic time, then Sub will use only it. @@ -937,6 +976,12 @@ func Since(t Time) Duration { // Until returns the duration until t. // It is shorthand for t.Sub(time.Now()). +// +// On some systems the monotonic clock will stop if the computer goes to sleep. +// On such a system, this may not accurately reflect the actual time that +// passed between t and now. +// Use [Time.Round](0) or [Time.Truncate](0) to walkaround. +// See issue: https://github.com/golang/go/issues/66870 func Until(t Time) Duration { if t.wall&hasMonotonic != 0 { // Common case optimization: if t has monotonic time, then Sub will use only it. From 47448ac87095ad2f647dcc8cf9c532e45b49b369 Mon Sep 17 00:00:00 2001 From: plasmatium Date: Mon, 22 Apr 2024 14:47:58 +0800 Subject: [PATCH 2/7] time: add notes about monotonic time paused during system sleep --- src/time/time.go | 48 +++--------------------------------------------- 1 file changed, 3 insertions(+), 45 deletions(-) diff --git a/src/time/time.go b/src/time/time.go index 7f320da5113a4c..b07bc5cf632e06 100644 --- a/src/time/time.go +++ b/src/time/time.go @@ -53,9 +53,9 @@ // // On some systems the monotonic clock will stop if the computer goes to sleep. // On such a system, t.Sub(u) may not accurately reflect the actual -// time that passed between t and u. This may impact a bunch of functions/methods: -// [time.Since], [time.Until], [Time.Add], [Time.Sub], [Time.After], [Time.Before] -// [Time.Equal], [Time.Compare]. +// time that passed between t and u. The same applies to other functions and +// methods that subtract times, such as [Since], [Until], [Before], [After] ... +// See issue: https://github.com/golang/go/issues/66870 // Use [Time.Round](0) or [Time.Truncate](0) to walkaround. // // Because the monotonic clock reading has no meaning outside @@ -257,11 +257,6 @@ func (t *Time) mono() int64 { } // After reports whether the time instant t is after u. -// -// On some systems the monotonic clock will stop if the computer goes to sleep. -// On such a system, this may not accurately reflect the actual time that -// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround. -// See issue: https://github.com/golang/go/issues/66870 func (t Time) After(u Time) bool { if t.wall&u.wall&hasMonotonic != 0 { return t.ext > u.ext @@ -272,11 +267,6 @@ func (t Time) After(u Time) bool { } // Before reports whether the time instant t is before u. -// -// On some systems the monotonic clock will stop if the computer goes to sleep. -// On such a system, this may not accurately reflect the actual time that -// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround. -// See issue: https://github.com/golang/go/issues/66870 func (t Time) Before(u Time) bool { if t.wall&u.wall&hasMonotonic != 0 { return t.ext < u.ext @@ -288,11 +278,6 @@ func (t Time) Before(u Time) bool { // Compare compares the time instant t with u. If t is before u, it returns -1; // if t is after u, it returns +1; if they're the same, it returns 0. -// -// On some systems the monotonic clock will stop if the computer goes to sleep. -// On such a system, this may not accurately reflect the actual time that -// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround. -// See issue: https://github.com/golang/go/issues/66870 func (t Time) Compare(u Time) int { var tc, uc int64 if t.wall&u.wall&hasMonotonic != 0 { @@ -317,11 +302,6 @@ func (t Time) Compare(u Time) int { // For example, 6:00 +0200 and 4:00 UTC are Equal. // See the documentation on the Time type for the pitfalls of using == with // Time values; most code should use Equal instead. -// -// On some systems the monotonic clock will stop if the computer goes to sleep. -// On such a system, this may not accurately reflect the actual time that -// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround. -// See issue: https://github.com/golang/go/issues/66870 func (t Time) Equal(u Time) bool { if t.wall&u.wall&hasMonotonic != 0 { return t.ext == u.ext @@ -893,11 +873,6 @@ func (d Duration) Abs() Duration { } // Add returns the time t+d. -// On some systems the monotonic clock will stop if the computer goes to sleep. -// -// On such a system, this may not accurately reflect the actual time that -// t+d. Use [Time.Round](0) or [Time.Truncate](0) to walkaround. -// See issue: https://github.com/golang/go/issues/66870 func (t Time) Add(d Duration) Time { dsec := int64(d / 1e9) nsec := t.nsec() + int32(d%1e9) @@ -926,11 +901,6 @@ func (t Time) Add(d Duration) Time { // value that can be stored in a [Duration], the maximum (or minimum) duration // will be returned. // To compute t-d for a duration d, use t.Add(-d). -// -// On some systems the monotonic clock will stop if the computer goes to sleep. -// On such a system, this may not accurately reflect the actual time that -// passed between t and u. Use [Time.Round](0) or [Time.Truncate](0) to walkaround. -// See issue: https://github.com/golang/go/issues/66870 func (t Time) Sub(u Time) Duration { if t.wall&u.wall&hasMonotonic != 0 { return subMono(t.ext, u.ext) @@ -960,12 +930,6 @@ func subMono(t, u int64) Duration { // Since returns the time elapsed since t. // It is shorthand for time.Now().Sub(t). -// -// On some systems the monotonic clock will stop if the computer goes to sleep. -// On such a system, this may not accurately reflect the actual time that -// passed between t and process start time. -// Use [Time.Round](0) or [Time.Truncate](0) to walkaround. -// See issue: https://github.com/golang/go/issues/66870 func Since(t Time) Duration { if t.wall&hasMonotonic != 0 { // Common case optimization: if t has monotonic time, then Sub will use only it. @@ -976,12 +940,6 @@ func Since(t Time) Duration { // Until returns the duration until t. // It is shorthand for t.Sub(time.Now()). -// -// On some systems the monotonic clock will stop if the computer goes to sleep. -// On such a system, this may not accurately reflect the actual time that -// passed between t and now. -// Use [Time.Round](0) or [Time.Truncate](0) to walkaround. -// See issue: https://github.com/golang/go/issues/66870 func Until(t Time) Duration { if t.wall&hasMonotonic != 0 { // Common case optimization: if t has monotonic time, then Sub will use only it. From 7cc6a86ea86805b7d79649e66249d4e814195c7d Mon Sep 17 00:00:00 2001 From: plasmatium Date: Tue, 23 Apr 2024 09:37:21 +0800 Subject: [PATCH 3/7] remove issue ref and list all --- src/time/time.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/time/time.go b/src/time/time.go index b07bc5cf632e06..f89f1e73f7670d 100644 --- a/src/time/time.go +++ b/src/time/time.go @@ -54,8 +54,8 @@ // On some systems the monotonic clock will stop if the computer goes to sleep. // On such a system, t.Sub(u) may not accurately reflect the actual // time that passed between t and u. The same applies to other functions and -// methods that subtract times, such as [Since], [Until], [Before], [After] ... -// See issue: https://github.com/golang/go/issues/66870 +// methods that subtract times, such as [Since], [Until], [Before], [After], +// [Add], [Sub], [Equal] and [Compare] // Use [Time.Round](0) or [Time.Truncate](0) to walkaround. // // Because the monotonic clock reading has no meaning outside From fedd71ea9ab54c3bd5996d0a504c1b1be2e04616 Mon Sep 17 00:00:00 2001 From: plasmatium Date: Tue, 23 Apr 2024 09:39:20 +0800 Subject: [PATCH 4/7] add period --- src/time/time.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/time/time.go b/src/time/time.go index f89f1e73f7670d..90eb4a0cec32b4 100644 --- a/src/time/time.go +++ b/src/time/time.go @@ -55,7 +55,7 @@ // On such a system, t.Sub(u) may not accurately reflect the actual // time that passed between t and u. The same applies to other functions and // methods that subtract times, such as [Since], [Until], [Before], [After], -// [Add], [Sub], [Equal] and [Compare] +// [Add], [Sub], [Equal] and [Compare]. // Use [Time.Round](0) or [Time.Truncate](0) to walkaround. // // Because the monotonic clock reading has no meaning outside From f9bb1b310c49735735a0540d194866e5029119cc Mon Sep 17 00:00:00 2001 From: plasmatium Date: Wed, 24 Apr 2024 10:03:54 +0800 Subject: [PATCH 5/7] refine duplicated hint --- src/time/time.go | 1 - 1 file changed, 1 deletion(-) diff --git a/src/time/time.go b/src/time/time.go index 90eb4a0cec32b4..4bc6c0703f4314 100644 --- a/src/time/time.go +++ b/src/time/time.go @@ -56,7 +56,6 @@ // time that passed between t and u. The same applies to other functions and // methods that subtract times, such as [Since], [Until], [Before], [After], // [Add], [Sub], [Equal] and [Compare]. -// Use [Time.Round](0) or [Time.Truncate](0) to walkaround. // // Because the monotonic clock reading has no meaning outside // the current process, the serialized forms generated by t.GobEncode, From c4b589dc1bf2f23e6a05f102c0c4da087f47309c Mon Sep 17 00:00:00 2001 From: plasmatium Date: Thu, 25 Apr 2024 09:41:05 +0800 Subject: [PATCH 6/7] add notes --- src/time/time.go | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/time/time.go b/src/time/time.go index 4bc6c0703f4314..7f454a01efca0b 100644 --- a/src/time/time.go +++ b/src/time/time.go @@ -55,7 +55,9 @@ // On such a system, t.Sub(u) may not accurately reflect the actual // time that passed between t and u. The same applies to other functions and // methods that subtract times, such as [Since], [Until], [Before], [After], -// [Add], [Sub], [Equal] and [Compare]. +// [Add], [Sub], [Equal] and [Compare]. In some cases, you may need to strip +// the monotonic clock or use an external source of time outside the current +// process to get more accurate results. // // Because the monotonic clock reading has no meaning outside // the current process, the serialized forms generated by t.GobEncode, From 9d92f116b05db5568dd4d5834bace659eaf8cc49 Mon Sep 17 00:00:00 2001 From: plasmatium Date: Fri, 26 Apr 2024 09:09:56 +0800 Subject: [PATCH 7/7] refine comment --- src/time/time.go | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/time/time.go b/src/time/time.go index 7f454a01efca0b..0bbdeaecf5d565 100644 --- a/src/time/time.go +++ b/src/time/time.go @@ -56,8 +56,7 @@ // time that passed between t and u. The same applies to other functions and // methods that subtract times, such as [Since], [Until], [Before], [After], // [Add], [Sub], [Equal] and [Compare]. In some cases, you may need to strip -// the monotonic clock or use an external source of time outside the current -// process to get more accurate results. +// the monotonic clock to get accurate results. // // Because the monotonic clock reading has no meaning outside // the current process, the serialized forms generated by t.GobEncode,