timing

Documentation

Overview

Package timing implements utilities for tracking timing information.

Index

• Constants
• type Interval
• type IntervalPrinter
  • func (p IntervalPrinter) Print(w io.Writer, intervals []Interval, now time.Duration) error
• type Timer
  • func NewTimer(name string) *Timer
  • func (t *Timer) Finish()
  • func (t *Timer) Now() time.Duration
  • func (t *Timer) Pop()
  • func (t *Timer) Push(name string)
  • func (t *Timer) String() string

Constants

const InvalidDuration = time.Duration(-1 << 63)

InvalidDuration is set on Interval.End to indicate that the end hasn't been set yet; i.e. the interval is open.

Types

type Interval

type Interval struct {
	Name       string
	Depth      int
	Start, End time.Duration
}

Interval represents a named time interval. The start and end time of the interval are represented as durations from a fixed "zero" time, rather than time.Time, for a more compact and faster implementation.

type IntervalPrinter

type IntervalPrinter struct {
	// Zero is the absolute start time to use for printing; all interval times are
	// computed relative to the zero time.  Typically this is set to Timer.Zero to
	// print actual timestamps, or time.Time{} to print relative timestamps
	// starting at the root.
	Zero time.Time
	// TimeFormat is passed to time.Format to format the start and end times.
	// Defaults to "15:04:05.000" if the value is empty.
	TimeFormat string
	// Indent is the number of spaces to indent each successive depth in the tree.
	// Defaults to 3 spaces if the value is 0; set to a negative value for no
	// indent.
	Indent int
	// MinGap is the minimum duration for gaps to be shown between successive
	// entries; only gaps that are larger than this threshold will be shown.
	// Defaults to 1 millisecond if the value is 0; set to a negative duration to
	// show all gaps.
	MinGap time.Duration
}

IntervalPrinter is a pretty-printer for Intervals. Example output:

00:00:01.000 root       98.000s       00:01:39.000
00:00:01.000    *           9.000s    00:00:10.000
00:00:10.000    foo        45.000s    00:00:55.000
00:00:10.000       *           5.000s 00:00:15.000
00:00:15.000       foo1       22.000s 00:00:37.000
00:00:37.000       foo2       18.000s 00:00:55.000
00:00:55.000    bar        25.000s    00:01:20.000
00:01:20.000    baz        19.000s    00:01:39.000

func (IntervalPrinter) Print

func (p IntervalPrinter) Print(w io.Writer, intervals []Interval, now time.Duration) error

Print writes formatted output to w representing the given intervals. The intervals must be in depth-first order; i.e. any slice or subslice of intervals produced by Timer are valid.

The time now is used as the end time for any open intervals, and is represented as a duration from the zero time for the intervals; e.g. use Timer.Now() for intervals collected by the Timer.

type Timer

type Timer struct {
	Zero      time.Time  // Absolute start time of the timer.
	Intervals []Interval // List of intervals, in depth-first order.
	// contains filtered or unexported fields
}

Timer provides support for tracking a tree of strictly hierarchical time intervals. If you need to track overlapping time intervals, simply use separate Timers.

Timer maintains a notion of a current interval, initialized to the root. The tree of intervals is constructed by push and pop operations, which add and update intervals to the tree, while updating the currently referenced interval. Finish should be called to finish all timing.

func NewTimer

func NewTimer(name string) *Timer

NewTimer returns a new Timer, with the root interval set to the given name.

func (*Timer) Finish

func (t *Timer) Finish()

Finish finishes all timing, closing all intervals including the root.

func (*Timer) Now

func (t *Timer) Now() time.Duration

Now returns the time now relative to timer.Zero.

func (*Timer) Pop

func (t *Timer) Pop()

Pop closes the current interval, and updates the current interval to refer to its parent. Pop does nothing if the current interval is the root.

func (*Timer) Push

func (t *Timer) Push(name string)

Push appends a child with the given name and an open interval to current, and updates the current interval to refer to the newly created child.

func (*Timer) String

func (t *Timer) String() string

String returns a formatted string describing the tree of time intervals.