Documentation
¶
Overview ¶
Package time defines the Timer type, which provides a periodic timer that works by sampling a user-provided clock.
Index ¶
- Constants
- Variables
- func After(clock Clock, duration time.Duration) (*Timer, Time, <-chan struct{})
- func ItimerspecFromSetting(now Time, s Setting) linux.Itimerspec
- func SpecFromSetting(now Time, s Setting) (value, period time.Duration)
- type ChannelNotifier
- type Clock
- type ClockEventsQueue
- type NoClockEvents
- type Setting
- func SettingFromAbsSpec(value Time, interval time.Duration) (Setting, error)
- func SettingFromItimerspec(its linux.Itimerspec, abs bool, c Clock) (Setting, error)
- func SettingFromSpec(value time.Duration, interval time.Duration, c Clock) (Setting, error)
- func SettingFromSpecAt(value time.Duration, interval time.Duration, now Time) (Setting, error)
- type TcpipTimer
- type Time
- func (t Time) Add(d time.Duration) Time
- func (t Time) AddTime(u Time) Time
- func (t Time) After(u Time) bool
- func (t Time) Before(u Time) bool
- func (t Time) Equal(u Time) bool
- func (t Time) IsMin() bool
- func (t Time) IsZero() bool
- func (t Time) Nanoseconds() int64
- func (t Time) Seconds() int64
- func (t *Time) StateFields() []string
- func (t *Time) StateLoad(stateSourceObject state.Source)
- func (t *Time) StateSave(stateSinkObject state.Sink)
- func (t *Time) StateTypeName() string
- func (t Time) StatxTimestamp() linux.StatxTimestamp
- func (t Time) String() string
- func (t Time) Sub(u Time) time.Duration
- func (t Time) TimeT() linux.TimeT
- func (t Time) Timespec() linux.Timespec
- func (t Time) Timeval() linux.Timeval
- func (t Time) Unix() (s int64, ns int64)
- type Timer
- func (t *Timer) Atomically(f func())
- func (t *Timer) Clock() Clock
- func (t *Timer) Destroy()
- func (t *Timer) Get() (Time, Setting)
- func (t *Timer) Pause()
- func (t *Timer) Resume()
- func (t *Timer) StateFields() []string
- func (t *Timer) StateLoad(stateSourceObject state.Source)
- func (t *Timer) StateSave(stateSinkObject state.Sink)
- func (t *Timer) StateTypeName() string
- func (t *Timer) Swap(s Setting) (Time, Setting)
- func (t *Timer) SwapAnd(s Setting, f func()) (Time, Setting)
- func (t *Timer) Tick()
- type TimerListener
- type WallRateClock
Constants ¶
const ( // ClockEventSet occurs when a Clock undergoes a discontinuous change. ClockEventSet waiter.EventMask = 1 << iota // ClockEventRateIncrease occurs when the rate at which a Clock advances // increases significantly, such that values returned by previous calls to // Clock.WallTimeUntil may be too large. ClockEventRateIncrease )
Events that may be generated by a Clock.
const ( // MinDuration is the minimum duration representable by time.Duration. MinDuration = time.Duration(math.MinInt64) // MaxDuration is the maximum duration representable by time.Duration. MaxDuration = time.Duration(math.MaxInt64) )
const ( // CtxRealtimeClock is a Context.Value key for the current real time. CtxRealtimeClock contextID = iota )
Variables ¶
var ( // MinTime is the zero time instant, the lowest possible time that can // be represented by Time. MinTime = Time{/* contains filtered or unexported fields */} // MaxTime is the highest possible time that can be represented by // Time. MaxTime = Time{/* contains filtered or unexported fields */} // ZeroTime represents the zero time in an unspecified Clock's domain. ZeroTime = Time{/* contains filtered or unexported fields */} )
Functions ¶
func After ¶
After waits for the duration to elapse according to clock and then sends a notification on the returned channel. The timer is started immediately and will fire exactly once. The second return value is the start time used with the duration.
Callers must call Timer.Destroy.
func ItimerspecFromSetting ¶
func ItimerspecFromSetting(now Time, s Setting) linux.Itimerspec
ItimerspecFromSetting converts a Setting to a linux.Itimerspec.
Types ¶
type ChannelNotifier ¶
type ChannelNotifier struct {
// contains filtered or unexported fields
}
ChannelNotifier is a TimerListener that sends a message on an empty struct channel.
ChannelNotifier cannot be saved or loaded.
func (*ChannelNotifier) Destroy ¶
func (c *ChannelNotifier) Destroy()
Destroy implements ktime.TimerListener.Destroy and will close the channel.
type Clock ¶
type Clock interface {
// Now returns the current time in nanoseconds according to the Clock.
Now() Time
// WallTimeUntil returns the estimated wall time until Now will return a
// value greater than or equal to t, given that a recent call to Now
// returned now. If t has already passed, WallTimeUntil may return 0 or a
// negative value.
//
// WallTimeUntil must be abstract to support Clocks that do not represent
// wall time (e.g. thread group execution timers). Clocks that represent
// wall times may embed the WallRateClock type to obtain an appropriate
// trivial implementation of WallTimeUntil.
//
// WallTimeUntil is used to determine when associated Timers should next
// check for expirations. Returning too small a value may result in
// spurious Timer goroutine wakeups, while returning too large a value may
// result in late expirations. Implementations should usually err on the
// side of underestimating.
WallTimeUntil(t, now Time) time.Duration
// Waitable methods may be used to subscribe to Clock events. Waiters will
// not be preserved by Save and must be re-established during restore.
//
// Since Clock events are transient, implementations of
// waiter.Waitable.Readiness should return 0.
waiter.Waitable
}
A Clock is an abstract time source.
func RealtimeClockFromContext ¶
RealtimeClockFromContext returns the real time clock associated with context ctx.
type ClockEventsQueue ¶
ClockEventsQueue implements waiter.Waitable by wrapping waiter.Queue and defining waiter.Waitable.Readiness as required by Clock.
type NoClockEvents ¶
type NoClockEvents struct{}
NoClockEvents implements waiter.Waitable for Clocks that do not generate events.
func (*NoClockEvents) EventRegister ¶
func (*NoClockEvents) EventRegister(e *waiter.Entry, mask waiter.EventMask)
EventRegister implements waiter.Waitable.EventRegister.
func (*NoClockEvents) EventUnregister ¶
func (*NoClockEvents) EventUnregister(e *waiter.Entry)
EventUnregister implements waiter.Waitable.EventUnregister.
type Setting ¶
type Setting struct {
// Enabled is true if the timer is running.
Enabled bool
// Next is the time in nanoseconds of the next expiration.
Next Time
// Period is the time in nanoseconds between expirations. If Period is
// zero, the timer will not automatically restart after expiring.
//
// Invariant: Period >= 0.
Period time.Duration
}
Setting contains user-controlled mutable Timer properties.
+stateify savable
func SettingFromAbsSpec ¶
SettingFromAbsSpec converts a (value, interval) pair to a Setting. value is interpreted as an absolute time.
func SettingFromItimerspec ¶
SettingFromItimerspec converts a linux.Itimerspec to a Setting. If abs is true, its.Value is interpreted as an absolute time. Otherwise, it is interpreted as a time relative to c.Now().
func SettingFromSpec ¶
SettingFromSpec converts a (value, interval) pair to a Setting based on a reading from c. value is interpreted as a time relative to c.Now().
func SettingFromSpecAt ¶
SettingFromSpecAt converts a (value, interval) pair to a Setting. value is interpreted as a time relative to now.
func (Setting) At ¶
At returns an updated Setting and a number of expirations after the associated Clock indicates a time of now.
Settings may be created by successive calls to At with decreasing values of now (i.e. time may appear to go backward). Supporting this is required to support non-monotonic clocks, as well as allowing Timer.clock.Now() to be called without holding Timer.mu.
func (*Setting) StateFields ¶
func (*Setting) StateTypeName ¶
type TcpipTimer ¶
type TcpipTimer struct {
// contains filtered or unexported fields
}
TcpipTimer is a resettable timer with variable duration expirations. Implements tcpip.Timer, which does not define a Destroy method; instead, all resources are released after timer expiration and calls to Timer.Stop.
Must be created by AfterFunc.
func TcpipAfterFunc ¶
func TcpipAfterFunc(clock Clock, duration time.Duration, fn func()) *TcpipTimer
TcpipAfterFunc waits for duration to elapse according to clock then runs fn. The timer is started immediately and will fire exactly once.
func (*TcpipTimer) Reset ¶
func (r *TcpipTimer) Reset(d time.Duration)
Reset implements tcpip.Timer.Reset.
type Time ¶
type Time struct {
// contains filtered or unexported fields
}
Time represents an instant in time with nanosecond precision.
Time may represent time with respect to any clock and may not have any meaning in the real world.
+stateify savable
func FromNanoseconds ¶
FromNanoseconds returns a Time representing the point ns nanoseconds after an unspecified Clock's zero time.
func FromSeconds ¶
FromSeconds returns a Time representing the point s seconds after an unspecified Clock's zero time.
func FromTimespec ¶
FromTimespec converts from Linux Timespec to Time.
func FromTimeval ¶
FromTimeval converts a Linux Timeval to Time.
func FromUnix ¶
FromUnix converts from Unix seconds and nanoseconds to Time, assuming a real time Unix clock domain.
func NowFromContext ¶
NowFromContext returns the current real time associated with context ctx.
func (Time) Nanoseconds ¶
Nanoseconds returns nanoseconds elapsed since the zero time in t's Clock domain. If t represents walltime, this is nanoseconds since the Unix epoch.
func (Time) Seconds ¶
Seconds returns seconds elapsed since the zero time in t's Clock domain. If t represents walltime, this is seconds since Unix epoch.
func (*Time) StateFields ¶
func (*Time) StateTypeName ¶
func (Time) StatxTimestamp ¶
func (t Time) StatxTimestamp() linux.StatxTimestamp
StatxTimestamp converts Time to a Linux statx_timestamp.
func (Time) Sub ¶
Sub returns the duration of t - u.
N.B. This measure may not make sense for every Time returned by ktime.Clock. Callers who need wall time duration can use ktime.Clock.WallTimeUntil to estimate that wall time.
type Timer ¶
type Timer struct {
// contains filtered or unexported fields
}
Timer is an optionally-periodic timer driven by sampling a user-specified Clock. Timer's semantics support the requirements of Linux's interval timers (setitimer(2), timer_create(2), timerfd_create(2)).
Timers should be created using NewTimer and must be cleaned up by calling Timer.Destroy when no longer used.
+stateify savable
func NewTimer ¶
func NewTimer(clock Clock, listener TimerListener) *Timer
NewTimer returns a new Timer that will obtain time from clock and send expirations to listener. The Timer is initially stopped and has no first expiration or period configured.
func (*Timer) Atomically ¶
func (t *Timer) Atomically(f func())
Atomically invokes f atomically with respect to expirations of t; that is, t cannot generate expirations while f is being called.
Preconditions: f cannot call any Timer methods since it is called with the Timer mutex locked.
func (*Timer) Destroy ¶
func (t *Timer) Destroy()
Destroy releases resources owned by the Timer. A Destroyed Timer must not be used again; in particular, a Destroyed Timer should not be Saved.
func (*Timer) Get ¶
Get returns a snapshot of the Timer's current Setting and the time (according to the Timer's Clock) at which the snapshot was taken.
Preconditions: The Timer must not be paused (since its Setting cannot be advanced to the current time while it is paused.)
func (*Timer) Pause ¶
func (t *Timer) Pause()
Pause pauses the Timer, ensuring that it does not generate any further expirations until Resume is called. If the Timer is already paused, Pause has no effect.
func (*Timer) Resume ¶
func (t *Timer) Resume()
Resume ends the effect of Pause. If the Timer is not paused, Resume has no effect.
func (*Timer) StateFields ¶
func (*Timer) StateTypeName ¶
func (*Timer) Swap ¶
Swap atomically changes the Timer's Setting and returns the Timer's previous Setting and the time (according to the Timer's Clock) at which the snapshot was taken. Setting s.Enabled to true starts the Timer, while setting s.Enabled to false stops it.
Preconditions: The Timer must not be paused.
func (*Timer) SwapAnd ¶
SwapAnd atomically changes the Timer's Setting, calls f if it is not nil, and returns the Timer's previous Setting and the time (according to the Timer's Clock) at which the Setting was changed. Setting s.Enabled to true starts the timer, while setting s.Enabled to false stops it.
Preconditions:
- The Timer must not be paused.
- f cannot call any Timer methods since it is called with the Timer mutex locked.
type TimerListener ¶
type TimerListener interface {
// Notify is called when its associated Timer expires. exp is the number of
// expirations. setting is the next timer Setting.
//
// Notify is called with the associated Timer's mutex locked, so Notify
// must not take any locks that precede Timer.mu in lock order.
//
// If Notify returns true, the timer will use the returned setting
// rather than the passed one.
//
// Preconditions: exp > 0.
Notify(exp uint64, setting Setting) (newSetting Setting, update bool)
// Destroy is called when the timer is destroyed.
Destroy()
}
A TimerListener receives expirations from a Timer.
func NewChannelNotifier ¶
func NewChannelNotifier() (TimerListener, <-chan struct{})
NewChannelNotifier creates a new channel notifier.
If the notifier is used with a timer, Timer.Destroy will close the channel returned here.
type WallRateClock ¶
type WallRateClock struct{}
WallRateClock implements Clock.WallTimeUntil for Clocks that elapse at the same rate as wall time.
func (*WallRateClock) WallTimeUntil ¶
func (*WallRateClock) WallTimeUntil(t, now Time) time.Duration
WallTimeUntil implements Clock.WallTimeUntil.
Source Files