Documentation

Overview

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

    Index

    Constants

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

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

      Variables

      This section is empty.

      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

                  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(c 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(c 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.

                                            Directories

                                            Path Synopsis