package ktime
import "gvisor.dev/gvisor/pkg/sentry/ktime"
Package ktime provides an API for clocks and timers implemented by the sentry.
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
- func (c *ClockEventsQueue) EventRegister(e *waiter.Entry) error
- func (*ClockEventsQueue) Readiness(mask waiter.EventMask) waiter.EventMask
- type Listener
- type NoClockEvents
- func (*NoClockEvents) EventRegister(e *waiter.Entry) error
- func (*NoClockEvents) EventUnregister(e *waiter.Entry)
- func (*NoClockEvents) Readiness(mask waiter.EventMask) waiter.EventMask
- type SampledClock
- type SampledTimer
- func NewSampledTimer(clock SampledClock, listener Listener) *SampledTimer
- func (t *SampledTimer) Clock() Clock
- func (t *SampledTimer) Destroy()
- func (t *SampledTimer) Get() (Time, Setting)
- func (t *SampledTimer) Pause()
- func (t *SampledTimer) Resume()
- func (t *SampledTimer) Set(s Setting, f func()) (Time, Setting)
- func (t *SampledTimer) SetClock(c SampledClock, s Setting)
- 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)
- func (s Setting) At(now Time) (Setting, uint64)
- type SyntheticClock
- func (c *SyntheticClock) Add(delta time.Duration)
- func (c *SyntheticClock) NewTimer(listener Listener) Timer
- func (c *SyntheticClock) Now() Time
- func (c *SyntheticClock) Store(now Time)
- type SyntheticTimer
- func NewSyntheticTimer(clock *SyntheticClock, listener Listener) *SyntheticTimer
- func (t *SyntheticTimer) Clock() Clock
- func (t *SyntheticTimer) Destroy()
- func (t *SyntheticTimer) Get() (Time, Setting)
- func (t *SyntheticTimer) Init(clock *SyntheticClock, listener Listener)
- func (t *SyntheticTimer) Pause()
- func (t *SyntheticTimer) Resume()
- func (t *SyntheticTimer) Set(s Setting, f func()) (Time, Setting)
- type Time
- func FromNanoseconds(ns int64) Time
- func FromSeconds(s int64) Time
- func FromTimespec(ts linux.Timespec) Time
- func FromTimeval(tv linux.Timeval) Time
- func FromUnix(s int64, ns int64) Time
- func NowFromContext(ctx context.Context) 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) 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
- type WallRateClock
Constants ¶
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 ( // ClockEventSet occurs when a SampledClock undergoes a discontinuous // change. ClockEventSet waiter.EventMask = 1 << iota // ClockEventRateIncrease occurs when the rate at which a SampledClock // 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 SampledClock.
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.
func SpecFromSetting ¶
SpecFromSetting converts a timestamp and a Setting to a (relative value, interval) pair, as used by most Linux syscalls that return a struct itimerval or struct 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)
NotifyTimer implements Listener.NotifyTimer.
type Clock ¶
type Clock interface {
// Now returns the current time in nanoseconds according to the Clock.
Now() Time
// NewTimer returns a Timer whose time source is the Clock, which sends
// expirations to the given Listener. The Timer is initially stopped
// and has no first expiration or period configured.
NewTimer(Listener) Timer
}
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 SampledClock.
func (*ClockEventsQueue) EventRegister ¶
func (c *ClockEventsQueue) EventRegister(e *waiter.Entry) error
EventRegister implements waiter.Waitable.
func (*ClockEventsQueue) Readiness ¶
func (*ClockEventsQueue) Readiness(mask waiter.EventMask) waiter.EventMask
Readiness implements waiter.Waitable.Readiness.
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.
//
// NotifyTimer cannot call any Timer methods or take any locks preceding
// the Timer in the lock order.
//
// Preconditions: exp > 0.
NotifyTimer(exp uint64)
}
Listener receives expirations from a Timer.
func NewChannelNotifier ¶
func NewChannelNotifier() (Listener, <-chan struct{})
NewChannelNotifier creates a new channel notifier.
type NoClockEvents ¶
type NoClockEvents struct{}
NoClockEvents implements waiter.Waitable for SampledClocks 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.
func (*NoClockEvents) Readiness ¶
func (*NoClockEvents) Readiness(mask waiter.EventMask) waiter.EventMask
Readiness implements waiter.Waitable.Readiness.
type SampledClock ¶
type SampledClock interface {
Clock
// 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 SampledClocks that do not
// represent wall time (e.g. thread group execution timers). SampledClocks
// that represent wall times may embed the WallRateClock type to obtain an
// appropriate trivial implementation of WallTimeUntil.
//
// WallTimeUntil is used to determine when associated SampledTimers should
// next check for expirations. Returning too small a value may result in
// spurious SampledTimer 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 SampledClock events.
// Waiters will not be preserved by Save and must be re-established during
// restore.
//
// Since SampledClock events are transient, implementations of
// waiter.Waitable.Readiness should return 0.
waiter.Waitable
}
A SampledClock is a Clock that can be a time source for a SampledTimer.
type SampledTimer ¶
type SampledTimer struct {
// contains filtered or unexported fields
}
SampledTimer implements Timer using a goroutine that reads a SampledClock whenever an expiration is expected to have occurred.
+stateify savable
func NewSampledTimer ¶
func NewSampledTimer(clock SampledClock, listener Listener) *SampledTimer
NewSampledTimer returns a new SampledTimer consistent with the requirements of Clock.NewTimer().
func (*SampledTimer) Clock ¶
func (t *SampledTimer) Clock() Clock
Clock implements Timer.Clock.
func (*SampledTimer) Destroy ¶
func (t *SampledTimer) Destroy()
Destroy implements Timer.Destroy.
func (*SampledTimer) Get ¶
func (t *SampledTimer) Get() (Time, Setting)
Get implements Timer.Get.
func (*SampledTimer) Pause ¶
func (t *SampledTimer) Pause()
Pause implements Timer.Pause.
func (*SampledTimer) Resume ¶
func (t *SampledTimer) Resume()
Resume implements Timer.Resume.
func (*SampledTimer) Set ¶
func (t *SampledTimer) Set(s Setting, f func()) (Time, Setting)
Set implements Timer.Set.
func (*SampledTimer) SetClock ¶
func (t *SampledTimer) SetClock(c SampledClock, s Setting)
SetClock atomically changes a SampledTimer's Clock and Setting.
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.
type SyntheticClock ¶
type SyntheticClock struct {
// contains filtered or unexported fields
}
SyntheticClock is a Clock whose current time is set manually by calling Store or Add.
+stateify savable
func (*SyntheticClock) Add ¶
func (c *SyntheticClock) Add(delta time.Duration)
Add increases c's current time by d and notifies expired timers.
Preconditions:
- c's resulting current time >= 0.
- The caller must not hold locks following Timer methods in the lock order (since Listener notification requires acquiring such locks).
func (*SyntheticClock) NewTimer ¶
func (c *SyntheticClock) NewTimer(listener Listener) Timer
NewTimer implements Clock.NewTimer.
func (*SyntheticClock) Now ¶
func (c *SyntheticClock) Now() Time
Now implements Clock.Now.
func (*SyntheticClock) Store ¶
func (c *SyntheticClock) Store(now Time)
Store sets c's current time to now and notifies expired timers.
Preconditions:
- now.Nanoseconds() >= 0.
- The caller must not hold locks following Timer methods in the lock order (since Listener notification requires acquiring such locks).
type SyntheticTimer ¶
type SyntheticTimer struct {
// contains filtered or unexported fields
}
SyntheticTimer implements Timer for SyntheticClocks.
+stateify savable
func NewSyntheticTimer ¶
func NewSyntheticTimer(clock *SyntheticClock, listener Listener) *SyntheticTimer
NewSyntheticTimer returns an initialized heap-allocated SyntheticTimer.
func (*SyntheticTimer) Clock ¶
func (t *SyntheticTimer) Clock() Clock
Clock implements Timer.Clock.
func (*SyntheticTimer) Destroy ¶
func (t *SyntheticTimer) Destroy()
Destroy implements Timer.Destroy.
func (*SyntheticTimer) Get ¶
func (t *SyntheticTimer) Get() (Time, Setting)
Get implements Timer.Get.
func (*SyntheticTimer) Init ¶
func (t *SyntheticTimer) Init(clock *SyntheticClock, listener Listener)
Init makes a zero-value SyntheticTimer ready for use.
func (*SyntheticTimer) Pause ¶
func (t *SyntheticTimer) Pause()
Pause implements Timer.Pause. Since SyntheticTimer expirations are caused by changes to the corresponding SyntheticClock's time, Pause is a no-op; clients must ensure that the SyntheticClock's time cannot advance while the timer is paused.
func (*SyntheticTimer) Resume ¶
func (t *SyntheticTimer) Resume()
Resume implements Timer.Resume. Since Pause is a no-op, Resume is also a no-op.
func (*SyntheticTimer) Set ¶
func (t *SyntheticTimer) Set(s Setting, f func()) (Time, Setting)
Set implements Timer.Set.
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) Add ¶
Add adds the duration of d to t.
func (Time) AddTime ¶
AddTime adds the duration of u to t.
func (Time) After ¶
After reports whether the instant t is after the instant u.
func (Time) Before ¶
Before reports whether the instant t is before the instant u.
func (Time) Equal ¶
Equal reports whether the two times represent the same instant in time.
func (Time) IsMin ¶
IsMin returns whether t represents the lowest possible time instant.
func (Time) IsZero ¶
IsZero returns whether t represents the zero time instant in t's Clock domain.
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) StatxTimestamp ¶
func (t Time) StatxTimestamp() linux.StatxTimestamp
StatxTimestamp converts Time to a Linux statx_timestamp.
func (Time) String ¶
String returns the time represented in nanoseconds as a string.
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.
func (Time) TimeT ¶
TimeT converts Time to a Linux time_t.
func (Time) Timespec ¶
Timespec converts Time to a Linux timespec.
func (Time) Timeval ¶
Timeval converts Time to a Linux timeval.
func (Time) Unix ¶
Unix returns the (seconds, nanoseconds) representation of t such that seconds*1e9 + nanoseconds = t.
type Timer ¶
type Timer interface {
// Destroy releases resources owned by the Timer. Pause and Resume may be
// called on a destroyed Timer and are no-ops. No other methods may be
// called on a destroyed Timer.
Destroy()
// 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.
//
// Pause and Resume are used to pause Timers during sentry checkpointing;
// non-checkpoint/restore code should not call these functions.
Pause()
// Resume ends the effect of Pause. If the Timer is not paused, Resume has
// no effect.
Resume()
// Clock returns the Timer's time source.
Clock() Clock
// 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.)
Get() (Time, Setting)
// Set 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 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.
// - f cannot call any Timer methods or take any locks preceding Timer
// methods in the lock order.
Set(s Setting, f func()) (Time, Setting)
}
Timer is an optionally-periodic timer. Timer's semantics support the requirements of Linux's interval timers (setitimer(2), timer_create(2), timerfd_create(2)).
type WallRateClock ¶
type WallRateClock struct{}
WallRateClock implements SampledClock.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 SampledClock.WallTimeUntil.
Source Files ¶
context.go ktime.go sampled_timer.go synthetic_timer.go
- Version
- v0.0.0-20250605235530-a6711d1e1dc6 (latest)
- Published
- Jun 5, 2025
- Platform
- linux/amd64
- Imports
- 9 packages
- Last checked
- 4 hours ago –
Tools for package owners.