Go 并发模式： context.Context 上下文详解
Posted 东海陈光剑
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了Go 并发模式： context.Context 上下文详解相关的知识，希望对你有一定的参考价值。
简介
Package context 中定义了 Context 类型, 用于跨 API 或跨进程之间传递数据，包含 deadlines, cancellation signals, 以及其他 request-scoped values 。
对服务器的传入请求应该创建一个Context上下文，对服务器的传出调用应该接受一个Context上下文。它们之间的函数调用链必须传播 Context，可选择将其替换为使用 WithCancel、WithDeadline、WithTimeout 或 WithValue 创建的派生 Context。
当一个上下文 Context 被取消时，所有从它派生的上下文也被取消。
使用规范
使用Context上下文的程序应遵循以下规则，以保持跨包的接口一致，并启用静态分析工具来检查上下文传播：
1.不要将上下文存储在结构类型中；
2.相反，将 Context 显式传递给需要它的每个函数。
3.即使函数允许，也不要传递 nil 上下文。
4.如果不确定要使用哪个 Context，请传递 context.TODO。
5.仅将Context值用于传输流程和 API 请求范围的数据(request-scoped data)，not for passing optional parameters to functions.
6.相同的 Context 可以传递给在不同的 goroutine 中运行的函数 (Context's methods may be called by multiple goroutines simultaneously.)；上下文 Context 对于多个 goroutine 同时使用是安全的。
Context 应该是第一个参数，通常命名为 ctx：
func DoSomething(ctx context.Context, arg Arg) error
// ... use ctx ...
源码阅读
// Copyright 2014 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// Package context defines the Context type, which carries deadlines,
// cancellation signals, and other request-scoped values across API boundaries
// and between processes.
//
// Incoming requests to a server should create a Context, and outgoing
// calls to servers should accept a Context. The chain of function
// calls between them must propagate the Context, optionally replacing
// it with a derived Context created using WithCancel, WithDeadline,
// WithTimeout, or WithValue. When a Context is canceled, all
// Contexts derived from it are also canceled.
//
// The WithCancel, WithDeadline, and WithTimeout functions take a
// Context (the parent) and return a derived Context (the child) and a
// CancelFunc. Calling the CancelFunc cancels the child and its
// children, removes the parent's reference to the child, and stops
// any associated timers. Failing to call the CancelFunc leaks the
// child and its children until the parent is canceled or the timer
// fires. The go vet tool checks that CancelFuncs are used on all
// control-flow paths.
//
// Programs that use Contexts should follow these rules to keep interfaces
// consistent across packages and enable static analysis tools to check context
// propagation:
//
// Do not store Contexts inside a struct type; instead, pass a Context
// explicitly to each function that needs it. The Context should be the first
// parameter, typically named ctx:
//
// func DoSomething(ctx context.Context, arg Arg) error
// // ... use ctx ...
//
//
// Do not pass a nil Context, even if a function permits it. Pass context.TODO
// if you are unsure about which Context to use.
//
// Use context Values only for request-scoped data that transits processes and
// APIs, not for passing optional parameters to functions.
//
// The same Context may be passed to functions running in different goroutines;
// Contexts are safe for simultaneous use by multiple goroutines.
//
// See https://blog.golang.org/context for example code for a server that uses
// Contexts.
package context
import (
"errors"
"internal/reflectlite"
"sync"
"sync/atomic"
"time"
)
// A Context carries a deadline, a cancellation signal, and other values across
// API boundaries.
//
// Context's methods may be called by multiple goroutines simultaneously.
type Context interface
// Deadline returns the time when work done on behalf of this context
// should be canceled. Deadline returns ok==false when no deadline is
// set. Successive calls to Deadline return the same results.
Deadline() (deadline time.Time, ok bool)
// Done returns a channel that's closed when work done on behalf of this
// context should be canceled. Done may return nil if this context can
// never be canceled. Successive calls to Done return the same value.
// The close of the Done channel may happen asynchronously,
// after the cancel function returns.
//
// WithCancel arranges for Done to be closed when cancel is called;
// WithDeadline arranges for Done to be closed when the deadline
// expires; WithTimeout arranges for Done to be closed when the timeout
// elapses.
//
// Done is provided for use in select statements:
//
// // Stream generates values with DoSomething and sends them to out
// // until DoSomething returns an error or ctx.Done is closed.
// func Stream(ctx context.Context, out chan<- Value) error
// for
// v, err := DoSomething(ctx)
// if err != nil
// return err
//
// select
// case <-ctx.Done():
// return ctx.Err()
// case out <- v:
//
//
//
//
// See https://blog.golang.org/pipelines for more examples of how to use
// a Done channel for cancellation.
Done() <-chan struct
// If Done is not yet closed, Err returns nil.
// If Done is closed, Err returns a non-nil error explaining why:
// Canceled if the context was canceled
// or DeadlineExceeded if the context's deadline passed.
// After Err returns a non-nil error, successive calls to Err return the same error.
Err() error
// Value returns the value associated with this context for key, or nil
// if no value is associated with key. Successive calls to Value with
// the same key returns the same result.
//
// Use context values only for request-scoped data that transits
// processes and API boundaries, not for passing optional parameters to
// functions.
//
// A key identifies a specific value in a Context. Functions that wish
// to store values in Context typically allocate a key in a global
// variable then use that key as the argument to context.WithValue and
// Context.Value. A key can be any type that supports equality;
// packages should define keys as an unexported type to avoid
// collisions.
//
// Packages that define a Context key should provide type-safe accessors
// for the values stored using that key:
//
// // Package user defines a User type that's stored in Contexts.
// package user
//
// import "context"
//
// // User is the type of value stored in the Contexts.
// type User struct ...
//
// // key is an unexported type for keys defined in this package.
// // This prevents collisions with keys defined in other packages.
// type key int
//
// // userKey is the key for user.User values in Contexts. It is
// // unexported; clients use user.NewContext and user.FromContext
// // instead of using this key directly.
// var userKey key
//
// // NewContext returns a new Context that carries value u.
// func NewContext(ctx context.Context, u *User) context.Context
// return context.WithValue(ctx, userKey, u)
//
//
// // FromContext returns the User value stored in ctx, if any.
// func FromContext(ctx context.Context) (*User, bool)
// u, ok := ctx.Value(userKey).(*User)
// return u, ok
//
Value(key interface) interface
// Canceled is the error returned by Context.Err when the context is canceled.
var Canceled = errors.New("context canceled")
// DeadlineExceeded is the error returned by Context.Err when the context's
// deadline passes.
var DeadlineExceeded error = deadlineExceededError
type deadlineExceededError struct
func (deadlineExceededError) Error() string return "context deadline exceeded"
func (deadlineExceededError) Timeout() bool return true
func (deadlineExceededError) Temporary() bool return true
// An emptyCtx is never canceled, has no values, and has no deadline. It is not
// struct, since vars of this type must have distinct addresses.
type emptyCtx int
func (*emptyCtx) Deadline() (deadline time.Time, ok bool)
return
func (*emptyCtx) Done() <-chan struct
return nil
func (*emptyCtx) Err() error
return nil
func (*emptyCtx) Value(key interface) interface
return nil
func (e *emptyCtx) String() string
switch e
case background:
return "context.Background"
case todo:
return "context.TODO"
return "unknown empty Context"
var (
background = new(emptyCtx)
todo = new(emptyCtx)
)
// Background returns a non-nil, empty Context. It is never canceled, has no
// values, and has no deadline. It is typically used by the main function,
// initialization, and tests, and as the top-level Context for incoming
// requests.
func Background() Context
return background
// TODO returns a non-nil, empty Context. Code should use context.TODO when
// it's unclear which Context to use or it is not yet available (because the
// surrounding function has not yet been extended to accept a Context
// parameter).
func TODO() Context
return todo
// A CancelFunc tells an operation to abandon its work.
// A CancelFunc does not wait for the work to stop.
// A CancelFunc may be called by multiple goroutines simultaneously.
// After the first call, subsequent calls to a CancelFunc do nothing.
type CancelFunc func()
// WithCancel returns a copy of parent with a new Done channel. The returned
// context's Done channel is closed when the returned cancel function is called
// or when the parent context's Done channel is closed, whichever happens first.
//
// Canceling this context releases resources associated with it, so code should
// call cancel as soon as the operations running in this Context complete.
func WithCancel(parent Context) (ctx Context, cancel CancelFunc)
if parent == nil
panic("cannot create context from nil parent")
c := newCancelCtx(parent)
propagateCancel(parent, &c)
return &c, func() c.cancel(true, Canceled)
// newCancelCtx returns an initialized cancelCtx.
func newCancelCtx(parent Context) cancelCtx
return cancelCtxContext: parent
// goroutines counts the number of goroutines ever created; for testing.
var goroutines int32
// propagateCancel arranges for child to be canceled when parent is.
func propagateCancel(parent Context, child canceler)
done := parent.Done()
if done == nil
return // parent is never canceled
select
case <-done:
// parent is already canceled
child.cancel(false, parent.Err())
return
default:
if p, ok := parentCancelCtx(parent); ok
p.mu.Lock()
if p.err != nil
// parent has already been canceled
child.cancel(false, p.err)
else
if p.children == nil
p.children = make(map[canceler]struct)
p.children[child] = struct
p.mu.Unlock()
else
atomic.AddInt32(&goroutines, +1)
go func()
select
case <-parent.Done():
child.cancel(false, parent.Err())
case <-child.Done():
()
// &cancelCtxKey is the key that a cancelCtx returns itself for.
var cancelCtxKey int
// parentCancelCtx returns the underlying *cancelCtx for parent.
// It does this by looking up parent.Value(&cancelCtxKey) to find
// the innermost enclosing *cancelCtx and then checking whether
// parent.Done() matches that *cancelCtx. (If not, the *cancelCtx
// has been wrapped in a custom implementation providing a
// different done channel, in which case we should not bypass it.)
func parentCancelCtx(parent Context) (*cancelCtx, bool)
done := parent.Done()
if done == closedchan || done == nil
return nil, false
p, ok := parent.Value(&cancelCtxKey).(*cancelCtx)
if !ok
return nil, false
p.mu.Lock()
ok = p.done == done
p.mu.Unlock()
if !ok
return nil, false
return p, true
// removeChild removes a context from its parent.
func removeChild(parent Context, child canceler)
p, ok := parentCancelCtx(parent)
if !ok
return
p.mu.Lock()
if p.children != nil
delete(p.children, child)
p.mu.Unlock()
// A canceler is a context type that can be canceled directly. The
// implementations are *cancelCtx and *timerCtx.
type canceler interface
cancel(removeFromParent bool, err error)
Done() <-chan struct
// closedchan is a reusable closed channel.
var closedchan = make(chan struct)
func init()
close(closedchan)
// A cancelCtx can be canceled. When canceled, it also cancels any children
// that implement canceler.
type cancelCtx struct
Context
mu sync.Mutex // protects following fields
done chan struct // created lazily, closed by first cancel call
children map[canceler]struct // set to nil by the first cancel call
err error // set to non-nil by the first cancel call
func (c *cancelCtx) Value(key interface) interface
if key == &cancelCtxKey
return c
return c.Context.Value(key)
func (c *cancelCtx) Done() <-chan struct
c.mu.Lock()
if c.done == nil
c.done = make(chan struct)
d := c.done
c.mu.Unlock()
return d
func (c *cancelCtx) Err() error
c.mu.Lock()
err := c.err
c.mu.Unlock()
return err
type stringer interface
String() string
func contextName(c Context) string
if s, ok := c.(stringer); ok
return s.String()
return reflectlite.TypeOf(c).String()
func (c *cancelCtx) String() string
return contextName(c.Context) + ".WithCancel"
// cancel closes c.done, cancels each of c's children, and, if
// removeFromParent is true, removes c from its parent's children.
func (c *cancelCtx) cancel(removeFromParent bool, err error)
if err == nil
panic("context: internal error: missing cancel error")
c.mu.Lock()
if c.err != nil
c.mu.Unlock()
return // already canceled
c.err = err
if c.done == nil
c.done = closedchan
else
close(c.done)
for child := range c.children
// NOTE: acquiring the child's lock while holding parent's lock.
child.cancel(false, err)
c.children = nil
c.mu.Unlock()
if removeFromParent
removeChild(c.Context, c)
// WithDeadline returns a copy of the parent context with the deadline adjusted
// to be no later than d. If the parent's deadline is already earlier than d,
// WithDeadline(parent, d) is semantically equivalent to parent. The returned
// context's Done channel is closed when the deadline expires, when the returned
// cancel function is called, or when the parent context's Done channel is
// closed, whichever happens first.
//
// Canceling this context releases resources associated with it, so code should
// call cancel as soon as the operations running in this Context complete.
func WithDeadline(parent Context, d time.Time) (Context, CancelFunc)
if parent == nil
panic("cannot create context from nil parent")
if cur, ok := parent.Deadline(); ok && cur.Before(d)
// The current deadline is already sooner than the new one.
return WithCancel(parent)
c := &timerCtx
cancelCtx: newCancelCtx(parent),
deadline: d,
propagateCancel(parent, c)
dur := time.Until(d)
if dur <= 0
c.cancel(true, DeadlineExceeded) // deadline has already passed
return c, func() c.cancel(false, Canceled)
c.mu.Lock()
defer c.mu.Unlock()
if c.err == nil
c.timer = time.AfterFunc(dur, func()
c.cancel(true, DeadlineExceeded)
)
return c, func() c.cancel(true, Canceled)
// A timerCtx carries a timer and a deadline. It embeds a cancelCtx to
// implement Done and Err. It implements cancel by stopping its timer then
// delegating to cancelCtx.cancel.
type timerCtx struct
cancelCtx
timer *time.Timer // Under cancelCtx.mu.
deadline time.Time
func (c *timerCtx) Deadline() (deadline time.Time, ok bool)
return c.deadline, true
func (c *timerCtx) String() string
return contextName(c.cancelCtx.Context) + ".WithDeadline(" +
c.deadline.String() + " [" +
time.Until(c.deadline).String() + "])"
func (c *timerCtx) cancel(removeFromParent bool, err error)
c.cancelCtx.cancel(false, err)
if removeFromParent
// Remove this timerCtx from its parent cancelCtx's children.
removeChild(c.cancelCtx.Context, c)
c.mu.Lock()
if c.timer != nil
c.timer.Stop()
c.timer = nil
c.mu.Unlock()
// WithTimeout returns WithDeadline(parent, time.Now().Add(timeout)).
//
// Canceling this context releases resources associated with it, so code should
// call cancel as soon as the operations running in this Context complete:
//
// func slowOperationWithTimeout(ctx context.Context) (Result, error)
// ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)
// defer cancel() // releases resources if slowOperation completes before timeout elapses
// return slowOperation(ctx)
//
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)
return WithDeadline(parent, time.Now().Add(timeout))
// WithValue returns a copy of parent in which the value associated with key is
// val.
//
// Use context Values only for request-scoped data that transits processes and
// APIs, not for passing optional parameters to functions.
//
// The provided key must be comparable and should not be of type
// string or any other built-in type to avoid collisions between
// packages using context. Users of WithValue should define their own
// types for keys. To avoid allocating when assigning to an
// interface, context keys often have concrete type
// struct. Alternatively, exported context key variables' static
// type should be a pointer or interface.
func WithValue(parent Context, key, val interface) Context
if parent == nil
panic("cannot create context from nil parent")
if key == nil
panic("nil key")
if !reflectlite.TypeOf(key).Comparable()
panic("key is not comparable")
return &valueCtxparent, key, val
// A valueCtx carries a key-value pair. It implements Value for that key and
// delegates all other calls to the embedded Context.
type valueCtx struct
Context
key, val interface
// stringify tries a bit to stringify v, without using fmt, since we don't
// want context depending on the unicode tables. This is only used by
// *valueCtx.String().
func stringify(v interface) string
switch s := v.(type)
case stringer:
return s.String()
case string:
return s
return "<not Stringer>"
func (c *valueCtx) String() string
return contextName(c.Context) + ".WithValue(type " +
reflectlite.TypeOf(c.key).String() +
", val " + stringify(c.val) + ")"
func (c *valueCtx) Value(key interface) interface
if c.key == key
return c.val
return c.Context.Value(key)
参考资料
https://blog.golang.org/contexthttps://pkg.go.dev/context
以上是关于Go 并发模式： context.Context 上下文详解的主要内容，如果未能解决你的问题，请参考以下文章