clock

package
v0.19.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 6, 2024 License: MIT Imports: 5 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	Provider = NewRealClock()
)

Functions

func FromUnixNano

func FromUnixNano(nanoSeconds int64) time.Time

FromUnixNano is the inverse of ToUnixNano and will return a timestamp in UTC if configured to do so, otherwise it will return a timestamp in the local time zone.

func ToUnixNano

func ToUnixNano(t time.Time) int64

ToUnixNano converts a timestamp to a 64-bit unsigned integer, namely the number of nanoseconds since 1970-01-01T00:00:00Z.

func WithNonBlockingSleep

func WithNonBlockingSleep(c *fakeClock)

func WithProvider

func WithProvider(def Clock)

func WithUseUTC

func WithUseUTC(useUTC bool)

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).Chan().
	// The underlying Timer is not recovered by the garbage collector until the timer fires.
	// If efficiency is a concern, use NewTimer instead and call Timer.Stop if the timer is no longer needed.
	//
	// If you enabled UTC, the timestamps are converted to UTC before you receive them.
	After(d time.Duration) <-chan time.Time
	// NewTicker returns a new Ticker containing a channel that will send the time on the channel after each tick.
	// The period of the ticks is specified by the duration argument. The ticker will drop ticks for slow receivers.
	// The duration d must be greater than zero; if not, NewTicker will panic. Stop the ticker to release associated resources.
	//
	// If you enabled UTC, the timestamps are converted to UTC before you receive them.
	NewTicker(d time.Duration) Ticker
	// NewTimer creates a new Timer that will send the current time on its channel after at least duration d. If you specify
	// a duration less than or equal to 0, the timer will fire immediately.
	//
	// If you enabled UTC, the timestamps are converted to UTC before you receive them.
	NewTimer(d time.Duration) Timer
	// Now will return the current time either in local time or UTC, if you enabled that.
	Now() time.Time
	// Since returns the time which passed since t.
	Since(t time.Time) time.Duration
	// Sleep blocks execution of your go routine for at least the given duration.
	Sleep(d time.Duration)
}

A Clock provides the most commonly needed functions from the time package while allowing you to substitute them for unit and integration tests.

func NewRealClock

func NewRealClock() Clock

NewRealClock creates a new Clock which uses the current system time. If you enabled UTC, all timestamps will be converted to UTC before they are returned. Use clock.Provider instead if you need the ability to replace the clock your code uses.

type FakeClock

type FakeClock interface {
	Clock
	// Advance advances the FakeClock to a new point in time as well as any tickers and timers created from it.
	Advance(d time.Duration)
	// BlockUntil will block until the FakeClock has the given number of calls to Clock.Sleep or Clock.After.
	BlockUntil(n int)
	// BlockUntilTimers will block until the FakeClock has at least the given number of timers created (similar to BlockUntil).
	// Only timers which are currently not stopped or expired are counted.
	BlockUntilTimers(n int)
	// BlockUntilTickers will block until the FakeClock has at least the given number of tickers created (similar to BlockUntil).
	// Only tickers which are currently not stopped are counted (expired tickers are still counted, they will trigger
	// again after more time passes).
	BlockUntilTickers(n int)
}

A FakeClock provides the functionality of a Clock with the added functionality to Advance said Clock and block until at least a given number of timers, tickers, or channels (Clock.After and Clock.Sleep) wait for the time to Advance.

func NewFakeClock

func NewFakeClock(options ...FakeClockOption) FakeClock

NewFakeClock creates a new FakeClock at a non-zero and fixed date.

func NewFakeClockAt

func NewFakeClockAt(t time.Time, options ...FakeClockOption) FakeClock

NewFakeClockAt creates a new FakeClock at the given time.Time.

type FakeClockOption

type FakeClockOption func(*fakeClock)

type Ticker

type Ticker interface {
	// Chan returns the channel to which the current time will be sent every time the Ticker expires.
	//
	// If you enabled UTC, the timestamps are converted to UTC before you receive them.
	Chan() <-chan time.Time
	// Reset stops a ticker and resets its period to the specified duration. The next tick will arrive after the new period
	// elapses. If you did Stop the Ticker before, it will be restarted.
	Reset(d time.Duration)
	// Stop turns off a ticker. After Stop, no more ticks will be sent. Stop does not close the channel, to prevent a
	// concurrent goroutine reading from the channel from seeing an erroneous "tick".
	Stop()
}

A Ticker is similar to a Timer, but it sends the current time continuously to the channel returned by Chan.

func NewRealTicker

func NewRealTicker(d time.Duration) Ticker

NewRealTicker creates a new Ticker based on the current system time. Use Clock.NewTicker instead if you need to replace the ticker with a fake ticker for unit and integration tests.

type Timer

type Timer interface {
	// Chan returns the channel to which the current time will be sent once the Timer expires.
	//
	// If you enabled UTC, the timestamps are converted to UTC before you receive them.
	Chan() <-chan time.Time
	// Reset changes the timer to expire after duration d.
	//
	// For a Timer created with Clock.NewTimer, Reset should be invoked only on stopped or expired timers with drained channels.
	//
	// If a program has already received a value from t.Chan(), the timer is known to have expired and the channel drained, so
	// t.Reset can be used directly. If a program has not yet received a value from t.Chan(), however, the timer must be
	// stopped and—if Stop reports that the timer expired before being stopped—the channel explicitly drained:
	//
	// 	if !t.Stop() {
	// 		<-t.Chan()
	// 	}
	// 	t.Reset(d)
	//
	// This should not be done concurrent to other receives from the Timer's channel.
	//
	// Note that, unlike the time.Timer's Reset method, this one doesn't return a value as it is not possible to use it correctly.
	// If you try to drain the channel after calling Reset, the timer might already expire. Thus, you would drain the value
	// you would afterwards be waiting for. Reset should always be invoked on stopped or expired channels, as described above.
	//
	// A call to Reset is not thread safe. You should only ever have a single go routine responsible for a Timer or have
	// some way to coordinate between different go routines.
	//
	// If you did not drain the channel after resetting a timer and that timer expires a second time, the first value will
	// be dropped and only the second value will be available in the channel for reading.
	Reset(d time.Duration)
	// 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.
	//
	// To ensure the channel is empty after a call to Stop, check the return value and drain the channel.
	// For example, assuming the program has not received from t.Chan() already:
	//
	// 	if !t.Stop() {
	// 		<-t.Chan()
	// 	}
	//
	// This cannot be done concurrent to other receives from the Timer's channel or other calls to the Timer's Stop method.
	//
	// A call to Stop is not thread safe. You should only ever have a single go routine responsible for cleaning up a Timer
	// or have some way to coordinate between different go routines.
	Stop() bool
}

A Timer will send the current time to a channel after a delay elapsed.

func NewRealTimer

func NewRealTimer(d time.Duration) Timer

NewRealTimer creates a new Timer based on the current system time. Use Clock.NewTimer instead if you need to replace the timer with a fake timer for unit and integration tests.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL