timeutil

Documentation

Index

• func LoadLocation(name string) (*time.Location, error)
• func Now() time.Time
• func Since(t time.Time) time.Duration
• func Strftime(time time.Time, fmt string) (string, error)
• func Strptime(time, fmt string) (time.Time, error)
• type Timer
  • func (t *Timer) Reset(d time.Duration)
  • func (t *Timer) Stop() bool

Functions

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 local time with an optional offset specified by the environment. The offset functionality is guarded by the "clockoffset" build tag - if built with that tag, the clock offset is parsed from the "COCKROACH_SIMULATED_OFFSET" environment variable using time.ParseDuration, which supports quasi-human values like "1h" or "1m".

func Since

func Since(t time.Time) time.Duration

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

func Strftime

func Strftime(time time.Time, fmt string) (string, error)

Strftime converts a time to a string using some C-style format.

func Strptime

func Strptime(time, fmt string) (time.Time, error)

Strptime converts a string to a time using some C-style format.

Types

type Timer

type Timer struct {
	*time.Timer
	Read bool
}

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 (*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. Reset operates on and returns a value so that Timer can be stack allocated.

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.