Operating systems provide both a “wall clock,” which is subject to
changes for clock synchronization, and a “monotonic clock,” which is
not. The general rule is that the wall clock is for telling time and
the monotonic clock is for measuring time. Rather than split the API,
in this package the Time returned by time.Now contains both a wall
clock reading and a monotonic clock reading; later time-telling
operations use the wall clock reading, but later time-measuring
operations, specifically comparisons and subtractions, use the
monotonic clock reading.
For example, this code always computes a positive elapsed time of
approximately 20 milliseconds, even if the wall clock is changed during
the operation being timed:
start := time.Now() ... operation that takes 20 milliseconds ... t := time.Now() elapsed := t.Sub(start)
Other idioms, such as time.Since(start), time.Until(deadline), and
time.Now().Before(deadline), are similarly robust against wall clock
resets.
The rest of this section gives the precise details of how operations
use monotonic clocks, but understanding those details is not required
to use this package.
The Time returned by time.Now contains a monotonic clock reading.
If Time t has a monotonic clock reading, t.Add adds the same duration to
both the wall clock and monotonic clock readings to compute the result.
Because t.AddDate(y, m, d), t.Round(d), and t.Truncate(d) are wall time
computations, they always strip any monotonic clock reading from their results.
Because t.In, t.Local, and t.UTC are used for their effect on the interpretation
of the wall time, they also strip any monotonic clock reading from their results.
The canonical way to strip a monotonic clock reading is to use t = t.Round(0).
If Times t and u both contain monotonic clock readings, the operations
t.After(u), t.Before(u), t.Equal(u), t.Compare(u), and t.Sub(u) are carried out
using the monotonic clock readings alone, ignoring the wall clock
readings. If either t or u contains no monotonic clock reading, these
operations fall back to using the wall clock readings.
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.
Because the monotonic clock reading has no meaning outside
the current process, the serialized forms generated by t.GobEncode,
t.MarshalBinary, t.MarshalJSON, and t.MarshalText omit the monotonic
clock reading, and t.Format provides no format for it. Similarly, the
constructors time.Date, time.Parse, time.ParseInLocation, and time.Unix,
as well as the unmarshalers t.GobDecode, t.UnmarshalBinary.
t.UnmarshalJSON, and t.UnmarshalText always create times with
no monotonic clock reading.
The monotonic clock reading exists only in Time values. It is not
a part of Duration values or the Unix times returned by t.Unix and
friends.
Note that the Go == operator compares not just the time instant but
also the Location and the monotonic clock reading. See the
documentation for the Time type for a discussion of equality
testing for Time values.
For debugging, the result of t.String does include the monotonic
clock reading if present. If t != u because of different monotonic clock readings,
that difference will be visible when printing t.String() and u.String().
Timer resolution varies depending on the Go runtime, the operating system
and the underlying hardware.
On Unix, the resolution is approximately 1ms.
On Windows, the default resolution is approximately 16ms, but
a higher resolution may be requested using [golang.org/x/sys/windows.TimeBeginPeriod].
Package time provides functionality for measuring and displaying time.
The calendrical calculations always assume a Gregorian calendar, with no leap seconds.
Monotonic Clocks
Operating systems provide both a “wall clock,” which is subject to changes for clock synchronization, and a “monotonic clock,” which is not. The general rule is that the wall clock is for telling time and the monotonic clock is for measuring time. Rather than split the API, in this package the Time returned by time.Now contains both a wall clock reading and a monotonic clock reading; later time-telling operations use the wall clock reading, but later time-measuring operations, specifically comparisons and subtractions, use the monotonic clock reading.
For example, this code always computes a positive elapsed time of approximately 20 milliseconds, even if the wall clock is changed during the operation being timed:
Other idioms, such as time.Since(start), time.Until(deadline), and time.Now().Before(deadline), are similarly robust against wall clock resets.
The rest of this section gives the precise details of how operations use monotonic clocks, but understanding those details is not required to use this package.
The Time returned by time.Now contains a monotonic clock reading. If Time t has a monotonic clock reading, t.Add adds the same duration to both the wall clock and monotonic clock readings to compute the result. Because t.AddDate(y, m, d), t.Round(d), and t.Truncate(d) are wall time computations, they always strip any monotonic clock reading from their results. Because t.In, t.Local, and t.UTC are used for their effect on the interpretation of the wall time, they also strip any monotonic clock reading from their results. The canonical way to strip a monotonic clock reading is to use t = t.Round(0).
If Times t and u both contain monotonic clock readings, the operations t.After(u), t.Before(u), t.Equal(u), t.Compare(u), and t.Sub(u) are carried out using the monotonic clock readings alone, ignoring the wall clock readings. If either t or u contains no monotonic clock reading, these operations fall back to using the wall clock readings.
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.
Because the monotonic clock reading has no meaning outside the current process, the serialized forms generated by t.GobEncode, t.MarshalBinary, t.MarshalJSON, and t.MarshalText omit the monotonic clock reading, and t.Format provides no format for it. Similarly, the constructors time.Date, time.Parse, time.ParseInLocation, and time.Unix, as well as the unmarshalers t.GobDecode, t.UnmarshalBinary. t.UnmarshalJSON, and t.UnmarshalText always create times with no monotonic clock reading.
The monotonic clock reading exists only in Time values. It is not a part of Duration values or the Unix times returned by t.Unix and friends.
Note that the Go == operator compares not just the time instant but also the Location and the monotonic clock reading. See the documentation for the Time type for a discussion of equality testing for Time values.
For debugging, the result of t.String does include the monotonic clock reading if present. If t != u because of different monotonic clock readings, that difference will be visible when printing t.String() and u.String().
Timer Resolution
Timer resolution varies depending on the Go runtime, the operating system and the underlying hardware. On Unix, the resolution is approximately 1ms. On Windows, the default resolution is approximately 16ms, but a higher resolution may be requested using [golang.org/x/sys/windows.TimeBeginPeriod].