README
¶
Context
Overview
Context is entirely experimental and has zero test coverage. The API may break at any time. It is conceptually similar to https://godoc.org/golang.org/x/net/context but easier (for me) to understand. I am sharing this primarily for discussion around https://github.com/golang/go/issues/14660.
Basic Use
Please see the godocs for additional information.
Authors
Bob Ziuchkovski (@bobziuchkovski)
License (MIT)
Copyright (c) 2016 Bob Ziuchkovski
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
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.
Source Files