ktime

package
v0.0.0-...-aa8ecac Latest Latest
Warning

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

 Go to latest Published: Dec 10, 2024 License: Apache-2.0, MIT Imports: 14 Imported by: 0

Documentation

Overview

Package ktime provides an API for clocks and timers implemented by the sentry.

Index

Constants

View Source 
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)
)
View Source 
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.

View Source 
const (
	// CtxRealtimeClock is a Context.Value key for the current real time.
	CtxRealtimeClock contextID = iota
)

Variables

View Source 
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 SeqAtomicStoreSampledClock 

func SeqAtomicStoreSampledClock(seq *sync.SeqCount, ptr *SampledClock, val SampledClock)

SeqAtomicStore sets *ptr to a copy of val, ensuring that any racing reader critical sections are forced to retry.

func SeqAtomicStoreSeqedSampledClock 

func SeqAtomicStoreSeqedSampledClock(ptr *SampledClock, val SampledClock)

SeqAtomicStoreSeqed sets *ptr to a copy of val.

Preconditions: ptr is protected by a SeqCount that will be in a writer critical section throughout the call to SeqAtomicStore.

func SpecFromSetting 

func SpecFromSetting(now Time, s Setting) (value, period time.Duration)

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 

func RealtimeClockFromContext(ctx context.Context) Clock

RealtimeClockFromContext returns the real time clock associated with context ctx.

type ClockEventsQueue 

type ClockEventsQueue struct {
	waiter.Queue
}

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.

func SeqAtomicLoadSampledClock 

func SeqAtomicLoadSampledClock(seq *sync.SeqCount, ptr *SampledClock) SampledClock

SeqAtomicLoad returns a copy of *ptr, ensuring that the read does not race with any writer critical sections in seq.

func SeqAtomicTryLoadSampledClock 

func SeqAtomicTryLoadSampledClock(seq *sync.SeqCount, epoch sync.SeqCountEpoch, ptr *SampledClock) (val SampledClock, ok bool)

SeqAtomicTryLoad returns a copy of *ptr while in a reader critical section in seq initiated by a call to seq.BeginRead() that returned epoch. If the read would race with a writer critical section, SeqAtomicTryLoad returns (unspecified, false).

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.

func (*SampledTimer) StateFields 

func (t *SampledTimer) StateFields() []string

func (*SampledTimer) StateLoad 

func (t *SampledTimer) StateLoad(ctx context.Context, stateSourceObject state.Source)

+checklocksignore

func (*SampledTimer) StateSave 

func (t *SampledTimer) StateSave(stateSinkObject state.Sink)

+checklocksignore

func (*SampledTimer) StateTypeName 

func (t *SampledTimer) StateTypeName() string

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 

func SettingFromAbsSpec(value Time, interval time.Duration) (Setting, error)

SettingFromAbsSpec converts a (value, interval) pair to a Setting. value is interpreted as an absolute time.

func SettingFromItimerspec 

func SettingFromItimerspec(its linux.Itimerspec, abs bool, c Clock) (Setting, error)

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 

func SettingFromSpec(value time.Duration, interval time.Duration, c Clock) (Setting, error)

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 

func SettingFromSpecAt(value time.Duration, interval time.Duration, now Time) (Setting, error)

SettingFromSpecAt converts a (value, interval) pair to a Setting. value is interpreted as a time relative to now.

func (Setting) At 

func (s Setting) At(now Time) (Setting, uint64)

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 (s *Setting) StateFields() []string

func (*Setting) StateLoad 

func (s *Setting) StateLoad(ctx context.Context, stateSourceObject state.Source)

+checklocksignore

func (*Setting) StateSave 

func (s *Setting) StateSave(stateSinkObject state.Sink)

+checklocksignore

func (*Setting) StateTypeName 

func (s *Setting) StateTypeName() string

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) StateFields 

func (c *SyntheticClock) StateFields() []string

func (*SyntheticClock) StateLoad 

func (c *SyntheticClock) StateLoad(ctx context.Context, stateSourceObject state.Source)

+checklocksignore

func (*SyntheticClock) StateSave 

func (c *SyntheticClock) StateSave(stateSinkObject state.Sink)

+checklocksignore

func (*SyntheticClock) StateTypeName 

func (c *SyntheticClock) StateTypeName() string

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) Next 

func (e *SyntheticTimer) Next() *SyntheticTimer

Next returns the entry that follows e in the list.

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) Prev 

func (e *SyntheticTimer) Prev() *SyntheticTimer

Prev returns the entry that precedes e in the list.

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.

func (*SyntheticTimer) SetNext 

func (e *SyntheticTimer) SetNext(elem *SyntheticTimer)

SetNext assigns 'entry' as the entry that follows e in the list.

func (*SyntheticTimer) SetPrev 

func (e *SyntheticTimer) SetPrev(elem *SyntheticTimer)

SetPrev assigns 'entry' as the entry that precedes e in the list.

func (*SyntheticTimer) StateFields 

func (t *SyntheticTimer) StateFields() []string

func (*SyntheticTimer) StateLoad 

func (t *SyntheticTimer) StateLoad(ctx context.Context, stateSourceObject state.Source)

+checklocksignore

func (*SyntheticTimer) StateSave 

func (t *SyntheticTimer) StateSave(stateSinkObject state.Sink)

+checklocksignore

func (*SyntheticTimer) StateTypeName 

func (t *SyntheticTimer) StateTypeName() string

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 

func FromNanoseconds(ns int64) Time

FromNanoseconds returns a Time representing the point ns nanoseconds after an unspecified Clock's zero time.

func FromSeconds 

func FromSeconds(s int64) Time

FromSeconds returns a Time representing the point s seconds after an unspecified Clock's zero time.

func FromTimespec 

func FromTimespec(ts linux.Timespec) Time

FromTimespec converts from Linux Timespec to Time.

func FromTimeval 

func FromTimeval(tv linux.Timeval) Time

FromTimeval converts a Linux Timeval to Time.

func FromUnix 

func FromUnix(s int64, ns int64) Time

FromUnix converts from Unix seconds and nanoseconds to Time, assuming a real time Unix clock domain.

func NowFromContext 

func NowFromContext(ctx context.Context) Time

NowFromContext returns the current real time associated with context ctx.

func (Time) Add 

func (t Time) Add(d time.Duration) Time

Add adds the duration of d to t.

func (Time) AddTime 

func (t Time) AddTime(u Time) Time

AddTime adds the duration of u to t.

func (Time) After 

func (t Time) After(u Time) bool

After reports whether the instant t is after the instant u.

func (Time) Before 

func (t Time) Before(u Time) bool

Before reports whether the instant t is before the instant u.

func (Time) Equal 

func (t Time) Equal(u Time) bool

Equal reports whether the two times represent the same instant in time.

func (Time) IsMin 

func (t Time) IsMin() bool

IsMin returns whether t represents the lowest possible time instant.

func (Time) IsZero 

func (t Time) IsZero() bool

IsZero returns whether t represents the zero time instant in t's Clock domain.

func (Time) Microseconds 

func (t Time) Microseconds() int64

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 

func (t Time) Nanoseconds() int64

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 

func (t Time) Seconds() int64

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 (t *Time) StateFields() []string

func (*Time) StateLoad 

func (t *Time) StateLoad(ctx context.Context, stateSourceObject state.Source)

+checklocksignore

func (*Time) StateSave 

func (t *Time) StateSave(stateSinkObject state.Sink)

+checklocksignore

func (*Time) StateTypeName 

func (t *Time) StateTypeName() string

func (Time) StatxTimestamp 

func (t Time) StatxTimestamp() linux.StatxTimestamp

StatxTimestamp converts Time to a Linux statx_timestamp.

func (Time) String 

func (t Time) String() string

String returns the time represented in nanoseconds as a string.

func (Time) Sub 

func (t Time) Sub(u Time) time.Duration

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 

func (t Time) TimeT() linux.TimeT

TimeT converts Time to a Linux time_t.

func (Time) Timespec 

func (t Time) Timespec() linux.Timespec

Timespec converts Time to a Linux timespec.

func (Time) Timeval 

func (t Time) Timeval() linux.Timeval

Timeval converts Time to a Linux timeval.

func (Time) Unix 

func (t Time) Unix() (s int64, ns int64)

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

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.