timers

README

timers

Motivations

The Go standard library offers good timer management abstractions through the time and context packages. However those are built as general purpose solution to fit most programs out there, but aren't designed for very high performance applications, and can become sources of inefficiencies for high traffic services.

Take as an example the common pattern of using context.WithTimeout to acquire a context that will control the time limit for an HTTP request. The creation of such context constructs a new timer within the Go runtime, and allocates a few hundred bytes of memory on the heap. A large portion of the CPU time and memory allocation now ends up being spent on creating those timers which in most cases will never fire since the normal behavior is often for the request to succeed and not to timeout.

This is where the timers package come in play, offering timing management abstractions which are both compatible with code built on top of the standard library and designed for efficiency.

Timelines

Timelines are a key abstraction for efficient timer management. They expose APIs to create background contexts that expire on a defined deadline, but instead of creating a new context, it shares contexts that are expire within a same time window. This means that concurrent operations which are intended to expire at roughly the same time do not need to create and manage their own context, they can share one that a timeline has already set for expiration near their own deadline.

The trade off is on the accuracy of the expirations, when creating a new context the runtime will try its best to expire it exactly at the time it was set for. A Timeline on the other hand will use a configurable resolution to group expiration times together under a single timer. There are use cases where a program may want to get timers that are as accurate as possible, but often times (and especially to manage request timeouts) the program will have no issues dealing with a 10 seconds timeout which triggered after 11 seconds instead of 10.

Documentation

Overview

Package timers exposes efficient data structures for managing timers.

Index

• Variables
• func Sleep(ctx context.Context, duration time.Duration) (err error)
• type Timeline
  • func (t *Timeline) Cancel()
  • func (t *Timeline) Context(at time.Time, now time.Time) context.Context
  • func (t *Timeline) Deadline(deadline time.Time) context.Context
  • func (t *Timeline) Timeout(timeout time.Duration) context.Context

Variables

var (
	// HighRes is a timeline configured for high resolution timers, with 10
	// millisecond accuracy.
	HighRes = Timeline{
		Resolution: 10 * time.Millisecond,
	}

	// LowRes is a timeline configured for low resolution timers, with 1 second
	// accuracy. This timeline is typically useful for network timeouts.
	//
	// Here is an example of how the timeline may be used to set a timeout on an
	// http request:
	//
	//	req = req.WithContext(timers.LowRes.Timeout(10 * time.Second))
	//	res, err := httpClient.Do(req)
	//
	LowRes = Timeline{
		Resolution: 1 * time.Second,
	}
)

Functions

func Sleep

func Sleep(ctx context.Context, duration time.Duration) (err error)

Sleep puts the calling goroutine to sleep until the given duration has passed, or until the context is canceled, whichever comes first, in which case it will return the context's error.

Types

type Timeline

type Timeline struct {
	// Resolution represents the accuracy of timers managed by this timeline.
	// The lower the resolution the more accurate the timers are, but it also
	// means the timeline will put more pressure on the runtime and use more
	// memory.
	Resolution time.Duration

	// Background configures the background context used by contexts created by
	// the timeline. If nil, the default background context is used instead.
	Background context.Context
	// contains filtered or unexported fields
}

Timeline is a data structure that maintains a cache of deadlines represented by background contexts. A Timeline has a resolution attribute representing the accuracy of the deadlines it maintains. All deadlines that fall within the same resolution window share the same context, making it very efficient to create thousands, or even millions of them since the runtime only needs to maintain a single timer per resolution window.

Timelines are safe to use concurrently from multiple goroutines, however they should not be copied after being first used.

The zero-value is a valid timeline with a resolution of 100ms.

func (*Timeline) Cancel

func (t *Timeline) Cancel()

Cancel cancels all contexts and releases all internal resources managed by the timeline.

func (*Timeline) Context

func (t *Timeline) Context(at time.Time, now time.Time) context.Context

Context returns a context which expires when the given deadline is reached, using `now` as the current time.

func (*Timeline) Deadline

func (t *Timeline) Deadline(deadline time.Time) context.Context

Deadline returns a context which expires when the given deadline is reached, plus up to the timeline's resolution.

func (*Timeline) Timeout

func (t *Timeline) Timeout(timeout time.Duration) context.Context

Timeout returns a context which expires after the given amount of time has passed, plus up to the timeline's resolution.