monotime

README

monotime

monotime provides a portable monotonic timer for Go / Golang.

• Linux: Uses runtime.nanotime
• Windows: Uses QueryPerformanceCounter docs
• macOS: Uses mach_absolute_time docs (requires CGO)
• FreeBSD: Uses clock_gettime(CLOCK_MONOTONIC) docs

About runtime.nanotime

The Go standard library provides time.Now for getting the current time, but this timestamp is not monotonic -- it can jump forward or backwards depending on the operating systems' time synchronization. The standard library does not provide a public API for getting the monotonic time from the operating system, but on some operating systems runtime.nanotime, a private method, is available, and generally is the fastest method to get a monotonic time. However, on many operating systems including macOS and Windows, runtime.nanotime doesn't actually implement a monotonic timer.

When possible this library uses runtime.nanotime, but on platforms where it is not available monotime may use other methods.

See the following golang/go issues for more background:

• #12914: runtime: time: expose monotonic clock source
• #17610: runtime: use mach_absolute_time for runtime.nanotime
• #6007: time: use monotonic time on netbsd

Documentation

Index

• func Duration(start Monotime, end Monotime) time.Duration
• type Monotime
  • func Now() Monotime
• type Timer
  • func New() Timer

Functions

func Duration

func Duration(start Monotime, end Monotime) time.Duration

Duration returns a time.Duration from two previously captured Now() calls.

Types

type Monotime

type Monotime = time.Time

func Now

func Now() Monotime

Now returns the current time from a monotonic clock, it must be treated as an opaque, platform specific value.

For most purposes, you should subtract two of these values by using the Duration() method.

type Timer

type Timer interface {
	// Returns the elaspsed time since this Timer was created.
	Elapsed() time.Duration
}

func New

func New() Timer

New creates a portable monotonic timer. If the underlying system changes times, this interface will still return an increasing duration.