vttime

Documentation

Overview

Package vttime contains the definitions and implementations for the Vitess time library. This package is based on Google's TrueTime, as described in this Spanner paper for instance: http://static.googleusercontent.com/media/research.google.com/en//archive/spanner-osdi2012.pdf

The idea is that a timestamp is not enough, as clocks will drift apart between computers. However, it is usually possible to know how much drift happens. So instead of returning a timestamp that may be wrong, we return an interval [earliest, latest] with the following guarantees: - current time is greater or equal to 'earliest'. - current time is less or equal to 'latest'.

When comparing two intervals, we know one of them is smaller if there is no overlap and it is before:

[--------]
              [-----------]

If there is overlap, we can't say for sure:

[--------]
     [----------]

However, if the goal is to be sure we are producing events that clients will know are chonologically ordered, it is then possible to sleep for a few milliseconds and guarantee that. This becomes handy in Paxos-like algorithms, for instance. See the paper for more details.

Index

• func SetTestClockTime(now time.Time)
• func SetTestClockUncertainty(uncertainty time.Duration)
• func UseTestClock()
• type Clock
  • func GetClock() Clock
• type Interval
  • func NewInterval(earliest, latest time.Time) (Interval, error)
  • func (i Interval) Earliest() time.Time
  • func (i Interval) IsValid() bool
  • func (i Interval) Latest() time.Time
  • func (i Interval) Less(other Interval) bool
• type TestClock
  • func (t *TestClock) Now() (Interval, error)
  • func (t *TestClock) Set(now time.Time)
  • func (t *TestClock) SetUncertainty(uncertainty time.Duration)
• type TimeClock
  • func (t TimeClock) Now() (Interval, error)

Functions

func SetTestClockTime

func SetTestClockTime(now time.Time)

SetTestClockTime sets the 'test' implementation time to the provided value.

func SetTestClockUncertainty

func SetTestClockUncertainty(uncertainty time.Duration)

SetTestClockUncertainty sets the 'test' implementation uncertainty to the provided value.

func UseTestClock

func UseTestClock()

UseTestClock is meant to be used in tests to start using the test clock.

Types

type Clock

type Clock interface {
	// Now returns the current time as Interval.
	// This method should be thread safe (i.e. multiple go routines can
	// safely call this at the same time).
	// The returned interval is guaranteed to have earliest <= latest,
	// and all implementations enforce it.
	Now() (Interval, error)
}

Clock returns the current time.

func GetClock

func GetClock() Clock

GetClock returns the global Clock object. Since it depends on flags, be sure to call this after they have been parsed (i.e. *not* in init() functions), otherwise this will panic.

type Interval

type Interval struct {
	// contains filtered or unexported fields
}

Interval describes a time interval

func NewInterval

func NewInterval(earliest, latest time.Time) (Interval, error)

NewInterval creates a new Interval from the provided times. earliest has to be smaller or equal to latest, or an error is returned.

func (Interval) Earliest

func (i Interval) Earliest() time.Time

Earliest returns the earliest time in the interval. If Interval was from calling Now(), it is guaranteed the real time was greater or equal than Earliest().

func (Interval) IsValid

func (i Interval) IsValid() bool

IsValid returns true iff latest >= earliest, meaning the interval is actually a real valid interval.

func (Interval) Latest

func (i Interval) Latest() time.Time

Latest returns the latest time in the interval. If Interval was from calling Now(), it is guaranteed the real time was lesser or equal than Latest().

func (Interval) Less

func (i Interval) Less(other Interval) bool

Less returns true if the provided interval is earlier than the parameter. Since both intervals are inclusive, comparison has to be strict.

type TestClock

type TestClock struct {
	// contains filtered or unexported fields
}

TestClock is an implementation of Clock for tests, where it is possible to set the current time and the uncertainty at any time.

To use it: vttime.UseTestClock() vttime.SetTestClockTime(now) vttime.SetTestClockUncertainty(dur)

func (*TestClock) Now

func (t *TestClock) Now() (Interval, error)

Now is part of the Clock interface.

func (*TestClock) Set

func (t *TestClock) Set(now time.Time)

Set let the user set the time

func (*TestClock) SetUncertainty

func (t *TestClock) SetUncertainty(uncertainty time.Duration)

SetUncertainty lets the user set the uncertainty

type TimeClock

type TimeClock struct{}

TimeClock is an implementation of Clock that uses time.Now() and a flag-configured uncertainty.

func (TimeClock) Now

func (t TimeClock) Now() (Interval, error)

Now is part of the Clock interface.