Documentation ¶
Overview ¶
Package context provides a key/value storage with cancelation signaling.
Basics ¶
Context provides both key/value storage as well as cancelation signaling. New, empty contexts may be created via the New function:
ctx = New()
A new context contains no key/value pairs and has no expiry associated with it. Child contexts may be created with key/value pairs using Context.WithValue and Context.WithFields. Expiring children may be created using Context.WithTimeout.
Cancelation ¶
Contexts may be canceled either explicitly, using Context.Cancel, or implicitly after a timeout using Context.WithTimeout. When a Context is canceled, all child Contexts are canceled at the same time, using the same cancelation reason (either ErrCanceled or ErrTimeout).
A subscriber may wait for cancellation using Context.Terminated or Context.Error. Context.Terminated returns a channel that is closed when the context is canceled. Context.Error blocks until the context is canceled and returns the cancelation reason.
ctx := New() expiring := ctx.WithTimeout(time.Second) // This will block for a second <- expiring.Terminated()
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrTimeout is returned from Context.Error() when the context is canceled // due to timeout. ErrTimeout = errors.New("context timed-out") // ErrCanceled is returned from Context.Error() when the context is // canceled via Context.Cancel(). ErrCanceled = errors.New("context cancelled") )
Functions ¶
This section is empty.
Types ¶
type Context ¶
type Context interface { // WithFields returns a new Context with fields added to the existing // key/value pairs. WithFields(fields Fields) Context // WithValue returns a new Context with key and value added to the existing // key/value pairs. WithValue(key interface{}, value interface{}) Context // GetValue returns the value associated with key, setting present to // true if the value is found. GetValue(key interface{}) (value interface{}, present bool) // WithTimeout returns a new Context with an expiry. If timeout elapses // and the context has not already been canceled, it is canceled with // ErrTimeout. If an ancestor context has an existing expiration prior to // the timeout parameter, the ancestor's timeout is inherited instead. WithTimeout(timeout time.Duration) Context // TimeRemaining returns the time remaining before the Context expires. // If a timeout has not been set for the context or any of its ancestors, // timeoutPresent is false. If the timeout has already elapsed, // timeoutPresent is true and remaining is set to zero. TimeRemaining() (remaining time.Duration, timeoutPresent bool) // Cancel cancels the current context and all child contexts with // ErrCanceled. The call is a no-op for contexts that have already been // canceled. Cancel() // Terminated returns a channel that is closed when the current context // is canceled. Terminated() <-chan struct{} // Error returns the cancelation reason for the context. It blocks until // the context is canceled. Error() error }
Context carries key/value pairs and provides signaling capabilities to cancel unneeded work.