time

Documentation

Overview

Package time defines newtypes around zx.Time and zx.Duration that provide a subset of the std time.Time and time.Duration API.

The std time package unfortunately [blurs the distinction](https://pkg.go.dev/time#hdr-Monotonic_Clocks) between wallclock and monotonic times. Operations from std time provide no type safety to preserve monotonicity in time values. Indeed, some std time methods and functions will silently erase the monotonic component of the value. This package defines its newtypes as monotonic time values and as such are intended for use in setting deadlines and expirations in Fuchsia netstack.

Users of this package should use it in place of the std time package. Given the blurred semantics of std time, using this package alongside std time is potentially hazardous and should only be done with care.

Index

• Constants
• func After(d Duration) <-chan Time
• func ContextWithTimeout(parent context.Context, d Duration) (context.Context, context.CancelFunc)
• func Sleep(d Duration)
• type Duration
  • func Since(t Time) Duration
  • func (d Duration) Microseconds() int64
  • func (d Duration) Milliseconds() int64
  • func (d Duration) Nanoseconds() int64
  • func (d Duration) Seconds() float64
  • func (d Duration) String() string
• type Time
  • func Monotonic(n int64) Time
  • func Now() Time
  • func (t Time) Add(d Duration) Time
  • func (t Time) Before(u Time) bool
  • func (t Time) MonotonicNano() int64
  • func (t Time) String() string
  • func (t Time) Sub(u Time) Duration

Constants

const (
	Nanosecond  Duration = 1
	Microsecond          = 1000 * Nanosecond
	Millisecond          = 1000 * Microsecond
	Second               = 1000 * Millisecond
	Minute               = 60 * Second
	Hour                 = 60 * Minute
)

Functions

func After

func After(d Duration) <-chan Time

After waits for duration to elapse and then sends the current monotonic time on the returned channel.

func ContextWithTimeout

func ContextWithTimeout(parent context.Context, d Duration) (context.Context, context.CancelFunc)

ContextWithTimeout returns a copy of the parent context with its timeout set to the value of the supplied duration. This function allows current users of Duration to avoid a direct dependency on the std time package which has different semantics and should not be freely used with the types in this package.

func Sleep

func Sleep(d Duration)

Sleep pauses the current goroutine for at least the duration. A 0 or negative duration returns immediately.

Types

type Duration

type Duration zx.Duration

A Duration represents the nanosecond count between two Time instants.

func Since

func Since(t Time) Duration

Since returns the time elapsed since t.

func (Duration) Microseconds

func (d Duration) Microseconds() int64

Microseconds returns the duration as an integer microsecond count.

func (Duration) Milliseconds

func (d Duration) Milliseconds() int64

Milliseconds returns the duration as an integer millisecond count.

func (Duration) Nanoseconds

func (d Duration) Nanoseconds() int64

Nanoseconds returns the duration as an integer nanosecond count.

func (Duration) Seconds

func (d Duration) Seconds() float64

Seconds returns the duration as floating point number of seconds.

func (Duration) String

func (d Duration) String() string

String returns the string representation of the duration in the default form used by time.Duration.

type Time

type Time struct {
	// contains filtered or unexported fields
}

A Time represents a monotonic instant in time since system start with nanosecond precision.

func Monotonic

func Monotonic(n int64) Time

Monotonic returns the monotonic time corresponding to the given nanosecond count. It is the analogue of std time.Unix() but without any reference to the Unix epoch.

func Now

func Now() Time

Now returns the current monotonic time relative to system start.

func (Time) Add

func (t Time) Add(d Duration) Time

Add returns the Time t+d. If the sum is such as to exceed the maximum or minimum Time value, the maximum or minimum will be returned, respectively.

func (Time) Before

func (t Time) Before(u Time) bool

Before returns whether the instant t is before u.

func (Time) MonotonicNano

func (t Time) MonotonicNano() int64

MonotonicNano returns the time as a nanosecond count. It is the analogue of std time.Time.UnixNano() but without any reference to the Unix epoch.

func (Time) String

func (t Time) String() string

String returns the time formatted using the format string:

"m=+-<value>"

where m indicates the monotonic component of the value. This format is the analogue of the std time.Time.String() format, with the non-monotonic components of the string removed. String presents its value in decimal units of seconds. String is intended solely for debugging.

func (Time) Sub

func (t Time) Sub(u Time) Duration

Sub returns the Duration t-u. If the difference is such as to exceed the maximum or minimum Duration value, the maximum or minimum will be returned, respectively.