cockroach: Index | Files | Directories

package timeutil

import ""


Package Files

now_unix.go stopwatch.go time.go time_zone_util.go timer.go zoneinfo.go


const LibPQTimePrefix = "0000-01-01"

LibPQTimePrefix is the prefix lib/pq prints time-type datatypes with.


var UnixEpoch = time.Unix(0, 0).UTC()

UnixEpoch represents the Unix epoch, January 1, 1970 UTC.

func FixedOffsetTimeZoneToLocation Uses

func FixedOffsetTimeZoneToLocation(offset int, origRepr string) *time.Location

FixedOffsetTimeZoneToLocation creates a time.Location with a set offset and with a name that can be marshaled by crdb between nodes.

func FromUnixMicros Uses

func FromUnixMicros(us int64) time.Time

FromUnixMicros returns the UTC time.Time corresponding to the given Unix time, usec microseconds since UnixEpoch. In Go's current time.Time implementation, all possible values for us can be represented as a time.Time.

func LoadLocation Uses

func LoadLocation(name string) (*time.Location, error)

LoadLocation returns the time.Location with the given name. The name is taken to be a location name corresponding to a file in the IANA Time Zone database, such as "America/New_York".

We do not use Go's time.LoadLocation() directly because: 1) it maps "Local" to the local time zone, whereas we want UTC. 2) when a tz is not found, it reports some garbage message related to, which we don't ship, instead of a more useful message like "the tz file with such name is not present in one of the standard tz locations".

func Now Uses

func Now() time.Time

Now returns the current UTC time.

func ParseFixedOffsetTimeZone Uses

func ParseFixedOffsetTimeZone(location string) (offset int, origRepr string, success bool)

ParseFixedOffsetTimeZone takes the string representation of a time.Location created by FixedOffsetTimeZoneToLocation and parses it to the offset and the original representation specified by the user. The bool returned is true if parsing was successful.

The strings produced by FixedOffsetTimeZoneToLocation look like "<fixedOffsetPrefix><offset> (<origRepr>)". TODO(#42404): this is not the format given by the results in pgwire/testdata/connection_params.

func ReplaceLibPQTimePrefix Uses

func ReplaceLibPQTimePrefix(s string) string

ReplaceLibPQTimePrefix replaces unparsable lib/pq dates used for timestamps (0000-01-01) with timestamps that can be parsed by date libraries.

func Since Uses

func Since(t time.Time) time.Duration

Since returns the time elapsed since t. It is shorthand for Now().Sub(t).

func SleepUntil Uses

func SleepUntil(untilNanos int64, currentTimeNanos func() int64)

SleepUntil sleeps until the given time. The current time is refreshed every second in case there was a clock jump

untilNanos is the target time to sleep till in epoch nanoseconds currentTimeNanos is a function returning current time in epoch nanoseconds

func TimeZoneStringToLocation Uses

func TimeZoneStringToLocation(
    locStr string, std TimeZoneStringToLocationStandard,
) (*time.Location, error)

TimeZoneStringToLocation transforms a string into a time.Location. It supports the usual locations and also time zones with fixed offsets created by FixedOffsetTimeZoneToLocation().

func ToUnixMicros Uses

func ToUnixMicros(t time.Time) int64

ToUnixMicros returns t as the number of microseconds elapsed since UnixEpoch. Fractional microseconds are rounded, half up, using time.Round. Similar to time.Time.UnixNano, the result is undefined if the Unix time in microseconds cannot be represented by an int64.

func Unix Uses

func Unix(sec, nsec int64) time.Time

Unix wraps time.Unix ensuring that the result is in UTC instead of Local.

func Until Uses

func Until(t time.Time) time.Duration

Until returns the duration until t. It is shorthand for t.Sub(Now()).

type StopWatch Uses

type StopWatch struct {
    // contains filtered or unexported fields

StopWatch is a utility stop watch that can be safely started and stopped multiple times and can be used concurrently.

func NewStopWatch Uses

func NewStopWatch() *StopWatch

NewStopWatch creates a new StopWatch.

func NewTestStopWatch Uses

func NewTestStopWatch(timeSource func() time.Time) *StopWatch

NewTestStopWatch create a new StopWatch with the given time source. It is used for testing only.

func (*StopWatch) Elapsed Uses

func (w *StopWatch) Elapsed() time.Duration

Elapsed returns the total time measured by the stop watch so far.

func (*StopWatch) Start Uses

func (w *StopWatch) Start()

Start starts the stop watch if it hasn't already been started.

func (*StopWatch) Stop Uses

func (w *StopWatch) Stop()

Stop stops the stop watch if it hasn't already been stopped and accumulates the duration that elapsed since it was started. If the stop watch has already been stopped, it is a noop.

type TestTimeSource Uses

type TestTimeSource struct {
    // contains filtered or unexported fields

TestTimeSource is a source of time that remembers when it was created (in terms of the real time) and returns the time based on its creation time and the number of "advances" it has had. It is used for testing only.

func NewTestTimeSource Uses

func NewTestTimeSource() *TestTimeSource

NewTestTimeSource create a new TestTimeSource.

func (*TestTimeSource) Advance Uses

func (t *TestTimeSource) Advance()

Advance advances the current time according to t by 1 nanosecond.

func (*TestTimeSource) Elapsed Uses

func (t *TestTimeSource) Elapsed() time.Duration

Elapsed returns how much time has passed since t has been created. Note that it is equal to the number of advances in nanoseconds.

func (*TestTimeSource) Now Uses

func (t *TestTimeSource) Now() time.Time

Now tells the current time according to t.

type TimeZoneStringToLocationStandard Uses

type TimeZoneStringToLocationStandard uint32

TimeZoneStringToLocationStandard is an option for the standard to use for parsing in TimeZoneStringToLocation.

const (
    // TimeZoneStringToLocationISO8601Standard parses int UTC offsets as *east* of
    // the GMT line, e.g. `-5` would be 'America/New_York' without daylight savings.
    TimeZoneStringToLocationISO8601Standard TimeZoneStringToLocationStandard = iota
    // TimeZoneStringToLocationPOSIXStandard parses int UTC offsets as *west* of the
    // GMT line, e.g. `+5` would be 'America/New_York' without daylight savings.

type Timer Uses

type Timer struct {

    // C is a local "copy" of timer.C that can be used in a select case before
    // the timer has been initialized (via Reset).
    C    <-chan time.Time
    Read bool
    // contains filtered or unexported fields

The Timer type represents a single event. When the Timer expires, the current time will be sent on Timer.C.

This timer implementation is an abstraction around the standard library's time.Timer that provides a temporary workaround for the issue described in As such, this timer should only be used when Reset is planned to be called continually in a loop. For this Reset pattern to work, Timer.Read must be set to true whenever a timestamp is read from the Timer.C channel. If Timer.Read is not set to true when the channel is read from, the next call to Timer.Reset will deadlock. This pattern looks something like:

var timer timeutil.Timer
defer timer.Stop()
for {
    switch {
    case <-timer.C:
        timer.Read = true

Note that unlike the standard library's Timer type, this Timer will not begin counting down until Reset is called for the first time, as there is no constructor function.

func NewTimer Uses

func NewTimer() *Timer

NewTimer allocates a new timer.

func (*Timer) Reset Uses

func (t *Timer) Reset(d time.Duration)

Reset changes the timer to expire after duration d and returns the new value of the timer. This method includes the fix proposed in, but requires users of Timer to set Timer.Read to true whenever they successfully read from the Timer's channel.

func (*Timer) Stop Uses

func (t *Timer) Stop() bool

Stop prevents the Timer from firing. It returns true if the call stops the timer, false if the timer has already expired, been stopped previously, or had never been initialized with a call to Timer.Reset. Stop does not close the channel, to prevent a read from succeeding incorrectly. Note that a Timer must never be used again after calls to Stop as the timer object will be put into an object pool for reuse.


pgdatePackage pgdate contains parsing functions and types for dates and times in a manner that is compatible with PostgreSQL.

Package timeutil imports 8 packages (graph) and is imported by 1227 packages. Updated 2020-07-01. Refresh now. Tools for package owners.