time

package
v0.0.0-...-957f62e Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2023 License: Apache-2.0, MIT Imports: 10 Imported by: 0

Documentation

Overview

Package time defines the Timer type, which provides a periodic timer that works by sampling a user-provided clock.

Index

Constants

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

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 (
	// 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 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, 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

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 Clock.

func (*ClockEventsQueue) EventRegister

func (c *ClockEventsQueue) EventRegister(e *waiter.Entry) error

EventRegister implements waiter.Waitable.

func (*ClockEventsQueue) Readiness

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.
	//
	// 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.

func (*NoClockEvents) Readiness

func (*NoClockEvents) Readiness(mask waiter.EventMask) waiter.EventMask

Readiness implements waiter.Waitable.Readiness.

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(stateSourceObject state.Source)

+checklocksignore

func (*Setting) StateSave

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

+checklocksignore

func (*Setting) StateTypeName

func (s *Setting) 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(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 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 Listener) *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) Clock

func (t *Timer) Clock() Clock

Clock returns the Clock used by t.

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

func (t *Timer) Get() (Time, Setting)

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

func (*Timer) StateLoad

func (t *Timer) StateLoad(stateSourceObject state.Source)

+checklocksignore

func (*Timer) StateSave

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

+checklocksignore

func (*Timer) StateTypeName

func (t *Timer) StateTypeName() string

func (*Timer) Swap

func (t *Timer) Swap(s Setting) (Time, Setting)

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

func (t *Timer) SwapAnd(s Setting, f func()) (Time, Setting)

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.

func (*Timer) Tick

func (t *Timer) Tick()

Tick requests that the Timer immediately check for expirations and re-evaluate when it should next check for expirations.

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.

func (*VariableTimer) Stop

func (r *VariableTimer) Stop() bool

Stop implements tcpip.Timer.Stop.

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.

Jump to

Keyboard shortcuts

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