globalclock

Documentation

Overview

Package globalclock provides clients for updating and reading the global virtual time, stored in the MongoDB database.

Multiple global clock updaters may run concurrently, but concurrent updates will fail. This simplifies failover in a multi-node controller, while preserving the invariant that a global clock second is at least as long as a wall-clock second.

Schema design -------------

We maintain a single collection, with a single document containing the current global time. Whenever time is to be advanced, we update the document while ensuring that the global time has not advanced by any other updater.

Index

• func GlobalEpoch() time.Time
• type Config
• type Mongo
• type Reader
  • func NewReader(config ReaderConfig) (*Reader, error)
  • func (r *Reader) Now() (time.Time, error)
• type ReaderConfig
• type Updater
  • func NewUpdater(config UpdaterConfig) (*Updater, error)
  • func (u *Updater) Advance(d time.Duration) error
• type UpdaterConfig

Functions

func GlobalEpoch

func GlobalEpoch() time.Time

GlobalEpoch returns the global clock's epoch, an arbitrary reference time at which the global clock started.

Types

type Config

type Config struct {
	// Collection names the MongoDB collection in which the clock
	// documents are stored.
	Collection string

	// Mongo exposes the mgo capabilities required by a Client
	// for updating and reading the clock.
	Mongo Mongo
}

Config contains the common resources and information required to create an Updater or Reader.

type Mongo

type Mongo interface {
	// GetCollection should probably call the mongo.CollectionFromName func
	GetCollection(name string) (collection mongo.Collection, closer func())
}

Mongo exposes MongoDB operations for use by the globalclock package.

type Reader

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

Reader provides a means of reading the global clock time.

Reader is not goroutine-safe.

func NewReader

func NewReader(config ReaderConfig) (*Reader, error)

NewReader returns a new Reader using the supplied config, or an error.

Readers will not function past the lifetime of their configured Mongo.

func (*Reader) Now

func (r *Reader) Now() (time.Time, error)

Now returns the current global time.

type ReaderConfig

type ReaderConfig struct {
	Config
}

ReaderConfig contains the resources and information required to create a Reader.

type Updater

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

Updater provides a means of updating the global clock time.

Updater is not goroutine-safe.

func NewUpdater

func NewUpdater(config UpdaterConfig) (*Updater, error)

NewUpdater returns a new Updater using the supplied config, or an error.

Updaters do not need to be cleaned up themselves, but they will not function past the lifetime of their configured *mgo.Session.

func (*Updater) Advance

func (u *Updater) Advance(d time.Duration) error

Advance adds the given duration to the global clock, ensuring that the clock has not been updated concurrently.

Advance will return ErrConcurrentUpdate if another updater updates the clock concurrently. In this case, the updater will refresh its view of the clock, and the caller can attempt Advance later.

If Advance returns any error other than ErrConcurrentUpdate, the Updater should be considered invalid, and the caller should obtain a new Updater. Failing to do so could lead to non-monotonic time, since there is no way of knowing in general whether or not the database was updated.

type UpdaterConfig

type UpdaterConfig struct {
	Config
}

UpdaterConfig contains the resources and information required to create an Updater.