timeutil

Documentation

Index

• Constants
• Variables
• func FixedOffsetTimeZoneToLocation(offset int, origRepr string) *time.Location
• func FromUnixMicros(us int64) time.Time
• func LoadLocation(name string) (*time.Location, error)
• func Now() time.Time
• func ParseFixedOffsetTimeZone(location string) (offset int, origRepr string, success bool)
• func ReplaceLibPQTimePrefix(s string) string
• func Since(t time.Time) time.Duration
• func SleepUntil(untilNanos int64, currentTimeNanos func() int64)
• func TimeZoneStringToLocation(locStr string, std TimeZoneStringToLocationStandard) (*time.Location, error)
• func ToUnixMicros(t time.Time) int64
• func Unix(sec, nsec int64) time.Time
• func Until(t time.Time) time.Duration
• type StopWatch
  • func NewStopWatch() *StopWatch
  • func NewTestStopWatch(timeSource func() time.Time) *StopWatch
  • func (w *StopWatch) Elapsed() time.Duration
  • func (w *StopWatch) Start()
  • func (w *StopWatch) Stop()
• type TestTimeSource
  • func NewTestTimeSource() *TestTimeSource
  • func (t *TestTimeSource) Advance()
  • func (t *TestTimeSource) Elapsed() time.Duration
  • func (t *TestTimeSource) Now() time.Time
• type TimeZoneStringToLocationStandard
• type Timer
  • func NewTimer() *Timer
  • func (t *Timer) Reset(d time.Duration)
  • func (t *Timer) Stop() bool

Constants

const LibPQTimePrefix = "0000-01-01"

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

Variables

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

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

Functions

func FixedOffsetTimeZoneToLocation

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

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

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 zoneinfo.zip, 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

func Now() time.Time

Now returns the current UTC time.

func ParseFixedOffsetTimeZone

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

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

func Since(t time.Time) time.Duration

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

func SleepUntil

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

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

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

func Unix(sec, nsec int64) time.Time

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

func Until

func Until(t time.Time) time.Duration

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

Types

type StopWatch

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

func NewStopWatch() *StopWatch

NewStopWatch creates a new StopWatch.

func NewTestStopWatch

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

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

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

func (*StopWatch) Start

func (w *StopWatch) Start()

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

func (*StopWatch) Stop

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

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

func NewTestTimeSource() *TestTimeSource

NewTestTimeSource create a new TestTimeSource.

func (*TestTimeSource) Advance

func (t *TestTimeSource) Advance()

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

func (*TestTimeSource) Elapsed

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

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

Now tells the current time according to t.

type TimeZoneStringToLocationStandard

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.
	TimeZoneStringToLocationPOSIXStandard
)

type Timer

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 https://github.com/golang/go/issues/14038. 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 {
    timer.Reset(wait)
    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

func NewTimer() *Timer

NewTimer allocates a new timer.

func (*Timer) Reset

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 https://github.com/golang/go/issues/11513#issuecomment-157062583, but requires users of Timer to set Timer.Read to true whenever they successfully read from the Timer's channel.

func (*Timer) Stop

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.