Documentation
¶
Overview ¶
Package clock provides clock-related types and utilities.
Index ¶
- Variables
- type Clock
- type FakeClock
- func (c *FakeClock) Add(d time.Duration)
- func (c *FakeClock) After(d time.Duration) <-chan time.Time
- func (c *FakeClock) AfterFunc(d time.Duration, fn func()) *Timer
- func (c *FakeClock) Nanotime() int64
- func (c *FakeClock) NewStopwatch() *Stopwatch
- func (c *FakeClock) NewTicker(d time.Duration) *Ticker
- func (c *FakeClock) NewTimer(d time.Duration) *Timer
- func (c *FakeClock) Now() time.Time
- func (c *FakeClock) SetNanotime(ns int64)
- func (c *FakeClock) SetTime(t time.Time)
- func (c *FakeClock) Since(t time.Time) time.Duration
- func (c *FakeClock) SinceNanotime(ns int64) time.Duration
- func (c *FakeClock) Sleep(d time.Duration)
- func (c *FakeClock) Tick(d time.Duration) <-chan time.Time
- type NanotimeFunc
- type Option
- type Options
- type Stopwatch
- type ThrottledClock
- func (c *ThrottledClock) After(d time.Duration) <-chan time.Time
- func (c *ThrottledClock) AfterFunc(d time.Duration, fn func()) *Timer
- func (c *ThrottledClock) Interval() time.Duration
- func (c *ThrottledClock) Nanotime() int64
- func (c *ThrottledClock) NewStopwatch() *Stopwatch
- func (c *ThrottledClock) NewTicker(d time.Duration) *Ticker
- func (c *ThrottledClock) NewTimer(d time.Duration) *Timer
- func (c *ThrottledClock) Now() time.Time
- func (c *ThrottledClock) Since(t time.Time) time.Duration
- func (c *ThrottledClock) SinceNanotime(ns int64) time.Duration
- func (c *ThrottledClock) Sleep(d time.Duration)
- func (c *ThrottledClock) Stop()
- func (c *ThrottledClock) Tick(d time.Duration) <-chan time.Time
- type Ticker
- type TimeFunc
- type Timer
Constants ¶
This section is empty.
Variables ¶
var ErrNoClockFunc = errors.New("no clock function provided")
ErrNoClockFunc is returned when creating a new Clock without a valid TimeFunc or NanotimeFunc.
Functions ¶
This section is empty.
Types ¶
type Clock ¶
type Clock interface {
// After waits for the duration to elapse and then sends the current time
// on the returned channel. It is equivalent to NewTimer(d).C. The
// underlying [Timer] is not recovered by the garbage collector until the
// it fires. If efficiency is a concern, use [NewTimer] instead and call
// [Timer.Stop] if the timer is no longer needed.
After(d time.Duration) <-chan time.Time
// AfterFunc waits for the duration to elapse and then calls fn in its own
// goroutine. It returns a [Timer] that can be used to cancel the call using
// its [Timer.Stop] method.
AfterFunc(d time.Duration, fn func()) *Timer
// Nanotime returns the current time in nanoseconds.
Nanotime() int64
// NewStopwatch returns a new [Stopwatch] that uses the [Clock] for
// measuring time.
NewStopwatch() *Stopwatch
// NewTicker returns a new [Ticker] containing a channel that will send the
// current time on the channel after each tick. The period of the ticks is
// specified by the duration argument. The ticker will adjust the time
// interval or drop ticks to make up for slow receivers. The duration d
// must be greater than zero; if not, NewTicker will panic. Stop the ticker
// to release associated resources.
NewTicker(d time.Duration) *Ticker
// NewTimer creates a new [Timer] that will send the current time on its
// channel after at least d has elapsed.
NewTimer(d time.Duration) *Timer
// Now returns the current time. For wall clocks, this is the local time;
// for monotonic clocks, this is the system's monotonic time. Other Clock
// implementations may have different locale or clock time semantics.
Now() time.Time
// Since returns the time elapsed since t. It is shorthand for
// Now().Sub(t).
Since(t time.Time) time.Duration
// Since returns the time elapsed since ns. It is shorthand for
// Nanotime()-ns.
SinceNanotime(ns int64) time.Duration
// Sleep pauses the current goroutine for at least the duration d. A
// negative or zero duration causes Sleep to return immediately.
Sleep(d time.Duration)
// Tick is a convenience wrapper for [NewTicker] providing access to the
// ticking channel only. While Tick is useful for clients that have no need
// to shut down the [Ticker], be aware that without a way to shut it down
// the underlying Ticker cannot be recovered by the garbage collector; it
// "leaks". Like [NewTicker], Tick will panic if d <= 0.
Tick(time.Duration) <-chan time.Time
}
A Clock tells time.
func MustClock ¶
MustClock panics if the given error is not nil, otherwise it returns the given Clock.
func NewMonotonicClock ¶
func NewMonotonicClock() Clock
NewMonotonicClock returns a new monotonic Clock.
type FakeClock ¶
type FakeClock struct {
// contains filtered or unexported fields
}
A FakeClock is a manually-adjusted clock useful for mocking the flow of time in tests. It does not keep time by itself: use FakeClock.Add, FakeClock.SetTime, and related functions to manage the clock's time.
func (*FakeClock) After ¶
After returns a channel that receives the current time after d has elapsed.
func (*FakeClock) AfterFunc ¶
AfterFunc returns a timer that will invoke the given function after d has elapsed. The timer may be stopped and reset.
func (*FakeClock) NewStopwatch ¶ added in v0.2.0
NewStopwatch returns a new Stopwatch that uses the current clock for measuring time. The clock's current time is used as the stopwatch's epoch.
func (*FakeClock) NewTicker ¶
NewTicker returns a new Ticker that receives time ticks every d. If d is not greater than zero, [NewTicker] will panic.
func (*FakeClock) SetNanotime ¶
SetNanotime sets the clock's time to ns.
func (*FakeClock) Since ¶
Since returns the amount of time that elapsed between the clock's internal time and t.
func (*FakeClock) SinceNanotime ¶
SinceNanotime returns the amount of time that elapsed between the clock's internal time and ns.
type NanotimeFunc ¶
type NanotimeFunc = func() int64
A NanotimeFunc is a function that returns time as integer nanoseconds.
func DefaultNanotimeFunc ¶
func DefaultNanotimeFunc() NanotimeFunc
DefaultNanotimeFunc returns a new NanotimeFunc that uses chrono.Nanotime to tell time.
func DefaultWallNanotimeFunc ¶ added in v0.4.0
func DefaultWallNanotimeFunc() NanotimeFunc
DefaultWallNanotimeFunc returns a new, default NanotimeFunc that reports wall time as nanoseconds.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
An Option configures a Clock.
func WithNanotimeFunc ¶
func WithNanotimeFunc(f NanotimeFunc) Option
WithNanotimeFunc returns an Option that configures a Clock to use f as its time function.
type Options ¶
type Options struct {
// TimeFunc configures the [TimeFunc] for a [Clock].
// If both TimeFunc and NanotimeFunc are provided, NanotimeFunc is used.
TimeFunc TimeFunc
// NanotimeFunc configures the [NanotimeFunc] for a [Clock].
// If both TimeFunc and NanotimeFunc are provided, NanotimeFunc is used.
NanotimeFunc NanotimeFunc
}
Options configure a Clock.
func DefaultOptions ¶
func DefaultOptions() Options
DefaultOptions returns a new Options with sane defaults.
type Stopwatch ¶
type Stopwatch struct {
// contains filtered or unexported fields
}
A Stopwatch measures elapsed time. A Stopwatch is created by calling [Clock.NewStopwatch].
func (*Stopwatch) Elapsed ¶
Elapsed returns the time elapsed since the last call to Stopwatch.Reset.
type ThrottledClock ¶
type ThrottledClock struct {
// contains filtered or unexported fields
}
ThrottledClock provides a simple interface to memoize repeated time syscalls within a given threshold.
func NewThrottledClock ¶
func NewThrottledClock( nowfn NanotimeFunc, interval time.Duration, ) *ThrottledClock
NewThrottledClock creates a new ThrottledClock that uses the given NanoFunc to update its internal time at the given interval. A ThrottledClock should be stopped via ThrottledClock.Stop once it is no longer used.
Note that interval should be tuned to be greater than the actual frequency of calls to ThrottledClock.Nanos or ThrottledClock.Now (otherwise the clock will generate more time calls than it is saving).
func NewThrottledMonotonicClock ¶
func NewThrottledMonotonicClock(interval time.Duration) *ThrottledClock
NewThrottledMonotonicClock creates a new ThrottledClock that uses NewMonotonicNanoFunc as its backing time function. See NewThrottledClock for more information.
func NewThrottledWallClock ¶
func NewThrottledWallClock(interval time.Duration) *ThrottledClock
NewThrottledWallClock creates a new ThrottledClock that uses NewWallNanoFunc as its backing time function. See NewThrottledClock for more information.
func (*ThrottledClock) After ¶
func (c *ThrottledClock) After(d time.Duration) <-chan time.Time
After returns a channel that receives the current time after d has elapsed. This method is not throttled and uses Go's runtime timers.
func (*ThrottledClock) AfterFunc ¶
func (c *ThrottledClock) AfterFunc(d time.Duration, fn func()) *Timer
AfterFunc returns a timer that will invoke the given function after d has elapsed. The timer may be stopped and reset. This method is not throttled and uses Go's runtime timers.
func (*ThrottledClock) Interval ¶
func (c *ThrottledClock) Interval() time.Duration
Interval returns the interval at which the clock updates its internal time.
func (*ThrottledClock) Nanotime ¶
func (c *ThrottledClock) Nanotime() int64
Nanotime returns the current time as integer nanoseconds.
func (*ThrottledClock) NewStopwatch ¶ added in v0.2.0
func (c *ThrottledClock) NewStopwatch() *Stopwatch
NewStopwatch returns a new Stopwatch that uses the current clock for measuring time. The clock's current time is used as the stopwatch's epoch.
func (*ThrottledClock) NewTicker ¶
func (c *ThrottledClock) NewTicker(d time.Duration) *Ticker
NewTicker returns a new Ticker that receives time ticks every d. This method is not throttled and uses Go's runtime timers. If d is not greater than zero, NewTicker will panic.
func (*ThrottledClock) NewTimer ¶
func (c *ThrottledClock) NewTimer(d time.Duration) *Timer
NewTimer returns a new Timer that receives a time tick after d. This method is not throttled and uses Go's runtime timers.
func (*ThrottledClock) Now ¶
func (c *ThrottledClock) Now() time.Time
Now returns the current time as time.Time.
func (*ThrottledClock) Since ¶
func (c *ThrottledClock) Since(t time.Time) time.Duration
Since returns the amount of time that elapsed between the clock's internal time and t.
func (*ThrottledClock) SinceNanotime ¶
func (c *ThrottledClock) SinceNanotime(ns int64) time.Duration
SinceNanotime returns the amount of time that elapsed between the clock's internal time and ns.
func (*ThrottledClock) Sleep ¶
func (c *ThrottledClock) Sleep(d time.Duration)
Sleep puts the current goroutine to sleep for d. This method is not throttled and uses Go's runtime timers.
func (*ThrottledClock) Stop ¶
func (c *ThrottledClock) Stop()
Stop stops the clock. Note that this has no effect on currently-running timers.
type Ticker ¶
A Ticker is functionally equivalent to a time.Ticker. A Ticker must be created by [Clock.NewTicker].
type TimeFunc ¶
A TimeFunc is a function that returns time as a time.Time object.
func DefaultTimeFunc ¶
func DefaultTimeFunc() TimeFunc
DefaultTimeFunc returns a new TimeFunc that uses time.Now to tell time.
type Timer ¶
A Timer is functionally equivalent to a time.Timer. A Timer must be created by [Clock.NewTimer].
func (*Timer) Reset ¶
Reset changes the timer to expire after duration d. It returns true if the timer had been active, false if the timer had expired or been stopped.
See Reset documentation on time.Timer for more information.
func (*Timer) Stop ¶
Stop prevents the Timer from firing. It returns true if the call stops the timer, false if the timer has already expired or been stopped. Stop does not close the channel, to prevent a read from the channel succeeding incorrectly.
See Stop documentation on time.Timer for more information.
Source Files
Directories