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 ¶
Constants ¶
This section is empty.
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 ¶
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 ¶ added in v1.1.0
Context returns a context which expires when the given deadline is reached, using `now` as the current time.
Source Files