clock

Documentation

Overview

Package clock is an interface to system time and timers which is easy to test.

Index

• Constants
• func After(ctx context.Context, d time.Duration) <-chan TimerResult
• func Now(ctx context.Context) time.Time
• func Set(ctx context.Context, c Clock) context.Context
• func SetFactory(ctx context.Context, f Factory) context.Context
• func Since(ctx context.Context, t time.Time) time.Duration
• func Tag(ctx context.Context, v string) context.Context
• func Tags(ctx context.Context) []string
• func Until(ctx context.Context, t time.Time) time.Duration
• func WithDeadline(parent context.Context, deadline time.Time) (context.Context, context.CancelFunc)
• func WithTimeout(parent context.Context, timeout time.Duration) (context.Context, context.CancelFunc)
• type Clock
  • func Get(ctx context.Context) (clock Clock)
  • func GetSystemClock() Clock
• type Factory
• type Timer
  • func NewTimer(ctx context.Context) Timer
• type TimerResult
  • func Sleep(ctx context.Context, d time.Duration) TimerResult
  • func (tr TimerResult) Incomplete() bool

Constants

const ContextDeadlineTag = "go.chromium.org/luci/common/clock.ContextDeadlineTag"

ContextDeadlineTag is the tag that will be applied to timers used for Context deadine timeout.

Functions

func After

func After(ctx context.Context, d time.Duration) <-chan TimerResult

After waits a duration using the Clock instance stored in the supplied Context. Then sends the current time over the returned channel.

If the supplied Context is canceled, the timer will expire immediately.

func Now

func Now(ctx context.Context) time.Time

Now calls Clock.Now on the Clock instance stored in the supplied Context.

func Set

func Set(ctx context.Context, c Clock) context.Context

Set creates a new Context using the supplied Clock.

func SetFactory

func SetFactory(ctx context.Context, f Factory) context.Context

SetFactory creates a new Context using the supplied Clock factory.

func Since

func Since(ctx context.Context, t time.Time) time.Duration

Since is an equivalent of time.Since.

func Tag

func Tag(ctx context.Context, v string) context.Context

Tag returns a derivative Context with the supplied Tag appended to it.

Tag chains can be used by timers to identify themselves.

func Tags

func Tags(ctx context.Context) []string

Tags returns a copy of the set of tags in the current Context.

func Until

func Until(ctx context.Context, t time.Time) time.Duration

Until is an equivalent of time.Until.

func WithDeadline

func WithDeadline(parent context.Context, deadline time.Time) (context.Context, context.CancelFunc)

WithDeadline is a clock library implementation of context.WithDeadline that uses the clock library's time features instead of the Go time library.

For more information, see context.WithDeadline.

func WithTimeout

func WithTimeout(parent context.Context, timeout time.Duration) (context.Context, context.CancelFunc)

WithTimeout is a clock library implementation of context.WithTimeout that uses the clock library's time features instead of the Go time library.

For more information, see context.WithTimeout.

Types

type Clock

type Clock interface {
	// Returns the current time (see time.Now).
	Now() time.Time

	// Sleeps the current goroutine (see time.Sleep).
	//
	// Sleep will return a TimerResult containing the time when it was awakened
	// and detailing its execution. If the sleep terminated prematurely from
	// cancellation, the TimerResult's Incomplete() method will return true.
	Sleep(context.Context, time.Duration) TimerResult

	// Creates a new Timer instance, bound to this Clock.
	//
	// If the supplied Context is canceled, the timer will expire immediately.
	NewTimer(ctx context.Context) Timer
}

Clock is an interface to system time.

The standard clock is SystemClock, which falls through to the system time library. Another clock, FakeClock, is available to simulate time facilities for testing.

func Get

func Get(ctx context.Context) (clock Clock)

Get returns the Clock set in the supplied Context, defaulting to SystemClock() if none is set.

func GetSystemClock

func GetSystemClock() Clock

GetSystemClock returns an instance of a Clock whose method calls directly use Go's "time" library.

type Factory

type Factory func(context.Context) Clock

Factory is a generator function that produces a Clock instnace.

type Timer

type Timer interface {
	// GetC returns the underlying timer's channel.
	//
	// If the Timer is interrupted via Stop, its channel will block indefinitely.
	GetC() <-chan TimerResult

	// Reset configures the timer to expire after a specified duration.
	//
	// If the timer is already running, its previous state will be cleared and
	// this method will return true. The channel returned by GetC() will not
	// change due to Reset.
	Reset(d time.Duration) bool

	// Stop clears any timer tasking, rendering it inactive.
	//
	// Stop may be called on an inactive timer, in which case nothing will happen
	// If the timer is active, it will be stopped and this method will return
	// true.
	//
	// If a timer is stopped, its GetC channel will block indefinitely to avoid
	// erroneously unblocking goroutines that are waiting on it. This is
	// consistent with time.Timer.
	Stop() bool
}

Timer is a wrapper around the time.Timer structure.

A Timer is instantiated from a Clock instance and started via its Reset() method.

func NewTimer

func NewTimer(ctx context.Context) Timer

NewTimer calls Clock.NewTimer on the Clock instance stored in the supplied Context.

type TimerResult

type TimerResult struct {
	time.Time

	// Err, if not nil, indicates that After did not finish naturally and contains
	// the reason why.
	Err error
}

TimerResult is the result for a timer operation.

Time will be set to the time when the result was generated. If the source of the result was prematurely terminated due to Context cancellation, Err will be non-nil, and will indicate the cancellation reason.

func Sleep

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

Sleep calls Clock.Sleep on the Clock instance stored in the supplied Context.

func (TimerResult) Incomplete

func (tr TimerResult) Incomplete() bool

Incomplete will return true if the timer result indicates that the timer operation was canceled prematurely due to Context cancellation or deadline expiration.