luci: go.chromium.org/luci/common/clock Index | Files | Directories

package clock

import "go.chromium.org/luci/common/clock"

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

Index

Package Files

clock.go clockcontext.go external.go systemclock.go systemtimer.go tags.go timer.go

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.

func After Uses

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

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

func Now Uses

func Now(ctx context.Context) time.Time

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

func Set Uses

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

Set creates a new Context using the supplied Clock.

func SetFactory Uses

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

SetFactory creates a new Context using the supplied Clock factory.

func Since Uses

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

Since is an equivalent of time.Since.

func Tag Uses

func Tag(c 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 Uses

func Tags(c context.Context) []string

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

func Until Uses

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

Until is an equivalent of time.Until.

func WithDeadline Uses

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 Uses

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.

type Clock Uses

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(c context.Context) Timer

    // Waits a duration, then sends the current time over the returned channel.
    //
    // If the supplied Context is canceled, the timer will expire immediately.
    After(context.Context, time.Duration) <-chan TimerResult
}

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 Uses

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 Uses

func GetSystemClock() Clock

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

type Factory Uses

type Factory func(context.Context) Clock

Factory is a generator function that produces a Clock instnace.

type Timer Uses

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 Uses

func NewTimer(ctx context.Context) Timer

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

type TimerResult Uses

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 one of the valid Context Err() return values.

func Sleep Uses

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 Uses

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.

Directories

PathSynopsis
clockflag
testclock

Package clock imports 4 packages (graph) and is imported by 202 packages. Updated 2018-12-19. Refresh now. Tools for package owners.