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 ItimerspecFromSetting(now Time, s Setting) linux.Itimerspec
- func SpecFromSetting(now Time, s Setting) (value, period time.Duration)
- type ChannelNotifier
- type Clock
- type ClockEventsQueue
- type Listener
- 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 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) Microseconds() int64
- 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 VariableTimer
- 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 ItimerspecFromSetting ¶
func ItimerspecFromSetting(now Time, s Setting) linux.Itimerspec
ItimerspecFromSetting converts a Setting to a linux.Itimerspec.
Types ¶
type ChannelNotifier ¶
type ChannelNotifier chan struct{}
ChannelNotifier is a Listener that sends on a channel.
ChannelNotifier cannot be saved or loaded.
func (ChannelNotifier) NotifyTimer ¶
func (c ChannelNotifier) NotifyTimer(uint64, Setting) (Setting, bool)
NotifyTimer implements Listener.NotifyTimer.
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.
func (*ClockEventsQueue) EventRegister ¶
func (c *ClockEventsQueue) EventRegister(e *waiter.Entry) error
EventRegister implements waiter.Waitable.
type Listener ¶
type Listener interface {
// NotifyTimer 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.
NotifyTimer(exp uint64, setting Setting) (newSetting Setting, update bool)
}
Listener receives expirations from a Timer.
func NewChannelNotifier ¶
func NewChannelNotifier() (Listener, <-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 NoClockEvents ¶
type NoClockEvents struct{}
NoClockEvents implements waiter.Waitable for Clocks that do not generate events.
func (*NoClockEvents) EventRegister ¶
func (*NoClockEvents) EventRegister(e *waiter.Entry) error
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 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) Microseconds ¶
Microseconds returns microseconds elapsed since the zero time in t's Clock domain. If t represents walltime, this is microseconds since the Unix epoch.
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 ¶
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 VariableTimer ¶
type VariableTimer struct {
// contains filtered or unexported fields
}
VariableTimer 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 AfterFunc ¶
func AfterFunc(clock Clock, duration time.Duration, fn func()) *VariableTimer
AfterFunc waits for duration to elapse according to clock then runs fn. The timer is started immediately and will fire exactly once.
func (*VariableTimer) Reset ¶
func (r *VariableTimer) Reset(d time.Duration)
Reset implements tcpip.Timer.Reset.
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