Namespace: go.std.time

v1.0

Contents

Summary

Provides a low-level interface to the time package.

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:

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), 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().

Index

Legend

Constants

Constants are variables with :const true in their metadata. Joker currently does not recognize them as special; as such, it allows redefining them or their values.

Variables

Functions, Macros, and Special Forms

Types