tstime

Documentation

Overview

Package tstime defines Tailscale-specific time utilities.

Index

• func Parse3339(s string) (time.Time, error)
• func Parse3339B(b []byte) (time.Time, error)
• func ParseDuration(s string) (time.Duration, error)
• func RandomDurationBetween(min, max time.Duration) time.Duration
• func Sleep(ctx context.Context, d time.Duration) bool
• type Clock
• type DefaultClock
  • func (c DefaultClock) AfterFunc(d time.Duration, f func()) TimerController
  • func (c DefaultClock) NewTicker(d time.Duration) (TickerController, <-chan time.Time)
  • func (c DefaultClock) NewTimer(d time.Duration) (TimerController, <-chan time.Time)
  • func (c DefaultClock) Now() time.Time
  • func (c DefaultClock) Since(t time.Time) time.Duration
• type StdClock
  • func (StdClock) AfterFunc(d time.Duration, f func()) TimerController
  • func (StdClock) NewTicker(d time.Duration) (TickerController, <-chan time.Time)
  • func (StdClock) NewTimer(d time.Duration) (TimerController, <-chan time.Time)
  • func (StdClock) Now() time.Time
  • func (StdClock) Since(t time.Time) time.Duration
• type TickerController
• type TimerController

Functions

func Parse3339

func Parse3339(s string) (time.Time, error)

Parse3339 is a wrapper around time.Parse(time.RFC3339, s).

func Parse3339B

func Parse3339B(b []byte) (time.Time, error)

Parse3339B is Parse3339 but for byte slices.

func ParseDuration

func ParseDuration(s string) (time.Duration, error)

ParseDuration is more expressive than time.ParseDuration, also accepting 'd' (days) and 'w' (weeks) literals.

func RandomDurationBetween

func RandomDurationBetween(min, max time.Duration) time.Duration

RandomDurationBetween returns a random duration in range [min,max). If panics if max < min.

func Sleep

func Sleep(ctx context.Context, d time.Duration) bool

Sleep is like time.Sleep but returns early upon context cancelation. It reports whether the full sleep duration was achieved.

Types

type Clock

type Clock interface {
	// Now returns the current time, as in time.Now.
	Now() time.Time
	// NewTimer returns a timer whose notion of the current time is controlled
	// by this Clock. It follows the semantics of time.NewTimer as closely as
	// possible but is adapted to return an interface, so the channel needs to
	// be returned as well.
	NewTimer(d time.Duration) (TimerController, <-chan time.Time)
	// NewTicker returns a ticker whose notion of the current time is controlled
	// by this Clock. It follows the semantics of time.NewTicker as closely as
	// possible but is adapted to return an interface, so the channel needs to
	// be returned as well.
	NewTicker(d time.Duration) (TickerController, <-chan time.Time)
	// AfterFunc returns a ticker whose notion of the current time is controlled
	// by this Clock. When the ticker expires, it will call the provided func.
	// It follows the semantics of time.AfterFunc.
	AfterFunc(d time.Duration, f func()) TimerController
	// Since returns the time elapsed since t.
	// It follows the semantics of time.Since.
	Since(t time.Time) time.Duration
}

Clock offers a subset of the functionality from the std/time package. Normally, applications will use the StdClock implementation that calls the appropriate std/time exported funcs. The advantage of using Clock is that tests can substitute a different implementation, allowing the test to control time precisely, something required for certain types of tests to be possible at all, speeds up execution by not needing to sleep, and can dramatically reduce the risk of flakes due to tests executing too slowly or quickly.

type DefaultClock

type DefaultClock struct{ Clock }

DefaultClock is a wrapper around a Clock. It uses StdClock by default if Clock is nil.

func (DefaultClock) AfterFunc

func (c DefaultClock) AfterFunc(d time.Duration, f func()) TimerController

func (DefaultClock) NewTicker

func (c DefaultClock) NewTicker(d time.Duration) (TickerController, <-chan time.Time)

func (DefaultClock) NewTimer

func (c DefaultClock) NewTimer(d time.Duration) (TimerController, <-chan time.Time)

func (DefaultClock) Now

func (c DefaultClock) Now() time.Time

func (DefaultClock) Since

func (c DefaultClock) Since(t time.Time) time.Duration

type StdClock

type StdClock struct{}

StdClock is a simple implementation of Clock using the relevant funcs in the std/time package.

func (StdClock) AfterFunc

func (StdClock) AfterFunc(d time.Duration, f func()) TimerController

AfterFunc calls time.AfterFunc.

func (StdClock) NewTicker

func (StdClock) NewTicker(d time.Duration) (TickerController, <-chan time.Time)

NewTicker calls time.NewTicker. As an interface does not allow for struct members and other packages cannot add receivers to another package, the channel is also returned because it would be otherwise inaccessible.

func (StdClock) NewTimer

func (StdClock) NewTimer(d time.Duration) (TimerController, <-chan time.Time)

NewTimer calls time.NewTimer. As an interface does not allow for struct members and other packages cannot add receivers to another package, the channel is also returned because it would be otherwise inaccessible.

func (StdClock) Now

func (StdClock) Now() time.Time

Now calls time.Now.

func (StdClock) Since

func (StdClock) Since(t time.Time) time.Duration

Since calls time.Since.

type TickerController

type TickerController interface {
	// Reset follows the same semantics as with time.Ticker.Reset.
	Reset(d time.Duration)
	// Stop follows the same semantics as with time.Ticker.Stop.
	Stop()
}

TickerController offers the receivers of a time.Ticker to ensure compatibility with standard timers, but allows for the option of substituting a standard timer with something else for testing purposes.

type TimerController

type TimerController interface {
	// Reset follows the same semantics as with time.Timer.Reset.
	Reset(d time.Duration) bool
	// Stop follows the same semantics as with time.Timer.Stop.
	Stop() bool
}

TimerController offers the receivers of a time.Timer to ensure compatibility with standard timers, but allows for the option of substituting a standard timer with something else for testing purposes.