golang context源码

解析

context结构

Deadline：返回 context 的过期时间；
Done：返回 context 中的 channel；
Err：返回错误；
Value：返回 context 中的对应 key 的值.

type Context interface {Deadline() (deadline time.Time, ok bool)Done() <-chan struct{}Err() errorValue(key any) any
}

//Context包含截止日期、取消信号和其他值
//API边界。
//Context的方法可能会被多个goroutine同时调用。
type Context interface {//Deadline返回代表此上下文完成工作的时间//应该取消。当没有截止日期时，截止日期返回ok==false//集。连续调用Deadline返回相同的结果。Deadline() (deadline time.Time, ok bool)//Done返回一个通道，当代表此完成工作时，该通道将关闭//上下文应该被取消。如果此上下文可以，Done可能会返回nil//永远不会被取消。连续调用Done返回相同的值。//Done通道的关闭可以异步发生，//在取消功能返回后。////WithCancel安排在调用取消时关闭Done；//WithDeadline安排在截止日期前关闭“完成”//到期；WithTimeout安排在超时时关闭“完成”//过去了。////Done用于选择语句：//Stream使用DoSomething生成值并将其发送到out直到DoSomething返回错误或ctx。完成已关闭。//func流（ctx context.context，out chan<-值）错误{//for{//v，err:=DoSomething（ctx）//如果错误！=无{//返回错误//  		}//选择{//病例<-ctx。Done（）：//返回ctx。错误（）//case out<-v：//  		}//  	}//  }////请参阅https://blog.golang.org/pipelines有关如何使用的更多示例//a取消的完成频道。Done() <-chan struct{}//如果Done尚未关闭，Err将返回nil。//如果Done关闭，Err返回一个非nil错误，解释原因：//如果上下文被取消，则取消//或超过上下文的截止日期。//在Err返回非nil错误后，对Err的连续调用将返回相同的错误。Err() error//Value返回与key或nil的上下文关联的值//如果没有值与键相关联。连续调用Value//相同的键返回相同的结果。////仅对传输的请求范围数据使用上下文值//进程和API边界，不用于将可选参数传递到//功能。////键标识上下文中的特定值。希望的功能//在Context中存储值通常会在全局中分配一个键//然后，变量将该键用作上下文的参数。WithValue和//背景。价值。密钥可以是任何支持相等的类型；//包应将密钥定义为未导出类型，以避免//碰撞。////定义Context键的包应提供类型安全的访问器//对于使用该键存储的值：//包用户定义了一个存储在上下文中的用户类型。//包用户////导入“上下文”//用户是存储在上下文中的值的类型。//type用户结构｛…｝//key是此包中定义的密钥的未导出类型。这可以防止与其他包中定义的键发生冲突。//类型键int//userKey是用户的密钥。上下文中的用户值。它是未报告；客户端使用用户。NewContext和用户。从上下文而不是直接使用此键。//var用户密钥//NewContext返回一个携带值u的新Context。//func-NewContext（ctx-context.context，u*User）上下文。背景{//返回上下文。WithValue（ctx、userKey、u）// 	}//FromContext返回存储在ctx中的User值（如果有的话）。//func FromContext（ctx context.context）（*用户，bool）{//u，ok：=ctx。值（userKey）。（*用户）//还你，好吗// 	}Value(key any) any
}

自定义一些结构

Error

//Canceled是取消上下文时[Context.Err]返回的错误。
var Canceled = errors.New("context canceled")//DeadlineExceded是[Context.Err]在上下文发生错误时返回的错误
// 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 }

//当满足以下条件时，stopCtx用作cancelCtx的父上下文
//AfterFunc已向父级注册。
//它包含用于注销AfterFunc的stop函数。
type stopCtx struct {Contextstop func() bool
}

//goroutines统计曾经创建的goroutines的数量；用于测试。
var goroutines atomic.Int32

//&cancelCtxKey是cancelCtx返回自己的密钥。
var cancelCtxKey int//parentCancelCtx返回父级的基础*cancelCtx。
//它通过查找父母来做到这一点。要查找的值（&cancelCtxKey）
//最里面的封闭*cancelCtx，然后检查是否
//父母。Done（）与*cancelCtx匹配。（如果没有，*cancelCtx
//已被封装在自定义实现中，提供
//不同的完成渠道，在这种情况下，我们不应该绕过它。）
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}pdone, _ := p.done.Load().(chan struct{})if pdone != done {return nil, false}return p, true
}//removeChild从其父级删除上下文。
func removeChild(parent Context, child canceler) {if s, ok := parent.(stopCtx); ok {s.stop()return}p, ok := parentCancelCtx(parent)if !ok {return}p.mu.Lock()if p.children != nil {delete(p.children, child)}p.mu.Unlock()
}//canceler是一种可以直接取消的上下文类型。这个
//实现是*cancelCtx和*timerCtx。
type canceler interface {cancel(removeFromParent bool, err, cause error)Done() <-chan struct{}
}//closedchan是一种可重复使用的封闭通道。
var closedchan = make(chan struct{})func init() {close(closedchan)
}

四种Context

emptyCtx

//emptyCtx永远不会被取消，没有值，也没有截止日期。
//它是背景Ctx和todoCtx的共同基础。
type emptyCtx struct{}
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 any) any {return nil
}

type backgroundCtx struct{ emptyCtx }func (backgroundCtx) String() string {return "context.Background"
}type todoCtx struct{ emptyCtx }func (todoCtx) String() string {return "context.TODO"
}//Background返回一个非nil的空[Context]。它从未被取消，没有
//值，并且没有截止日期。它通常由主功能使用，
//初始化和测试，并作为传入的顶级上下文请求：
func Background() Context {return backgroundCtx{}
}//TODO返回一个非nil的空[Context]。代码应该使用上下文。TODO何时
//不清楚使用哪个上下文，或者它还不可用（因为
//周围函数尚未扩展为接受上下文
//参数）。
func TODO() Context {return todoCtx{}
}

cancelCtx

embed 了一个 context 作为其父 context. 可见，cancelCtx 必然为某个 context 的子 context；
内置了一把锁，用以协调并发场景下的资源获取；
done：实际类型为 chan struct{}，即用以反映 cancelCtx 生命周期的通道；
children：一个 set，指向 cancelCtx 的所有子 context；
err：记录了当前 cancelCtx 的错误. 必然为某个 context 的子 context；

//cancelCtx可以取消。取消后，它也会取消任何孩子
// that implement canceler.
type cancelCtx struct {Contextmu       sync.Mutex            //保护以下字段done     atomic.Value          //chan-struct{}，延迟创建，由第一个cancel调用关闭children map[canceler]struct{} //在第一次取消呼叫时设置为nilerr      error                 //在第一次取消调用时设置为非nilcause    error                 //在第一次取消调用时设置为非nil
}func (c *cancelCtx) Value(key any) any {if key == &cancelCtxKey {return c}return value(c.Context, key)
}func (c *cancelCtx) Done() <-chan struct{} {d := c.done.Load()if d != nil {return d.(chan struct{})}c.mu.Lock()defer c.mu.Unlock()d = c.done.Load()if d == nil {d = make(chan struct{})c.done.Store(d)}return d.(chan struct{})
}func (c *cancelCtx) Err() error {c.mu.Lock()err := c.errc.mu.Unlock()return err
}//propagateCancel安排在父级为时取消子级。
//它设置cancelCtx的父上下文。
func (c *cancelCtx) propagateCancel(parent Context, child canceler) {c.Context = parentdone := parent.Done()if done == nil {return //家长永远不会被取消}select {case <-done:
//家长已取消child.cancel(false, parent.Err(), Cause(parent))returndefault:}if p, ok := parentCancelCtx(parent); ok {
//parent是一个*cancelCtx，或从其派生而来。p.mu.Lock()if p.err != nil {
//家长已被取消child.cancel(false, p.err, p.cause)} else {if p.children == nil {p.children = make(map[canceler]struct{})}p.children[child] = struct{}{}}p.mu.Unlock()return}if a, ok := parent.(afterFuncer); ok {
//parent实现了AfterFunc方法。c.mu.Lock()stop := a.AfterFunc(func() {child.cancel(false, parent.Err(), Cause(parent))})c.Context = stopCtx{Context: parent,stop:    stop,}c.mu.Unlock()return}goroutines.Add(1)go func() {select {case <-parent.Done():child.cancel(false, parent.Err(), Cause(parent))case <-child.Done():}}()
}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关闭c.done，取消c的每个孩子，如果
//removeFromParent为true，从其父级的子级中删除c。
//如果这是第一次取消c，则设置c。
func (c *cancelCtx) cancel(removeFromParent bool, err, cause error) {if err == nil {panic("context: internal error: missing cancel error")}if cause == nil {cause = err}c.mu.Lock()if c.err != nil {c.mu.Unlock()return // already canceled}c.err = errc.cause = caused, _ := c.done.Load().(chan struct{})if d == nil {c.done.Store(closedchan)} else {close(d)}for child := range c.children {//注意：在持有父母锁的同时获取孩子的锁。child.cancel(false, err, cause)}c.children = nilc.mu.Unlock()if removeFromParent {removeChild(c.Context, c)}
}//WithoutCancel返回父级的副本，当父级被取消时，该副本不会被取消。
//返回的上下文不返回Deadline或Err，其Done通道为nil。
//对返回的上下文调用[Cause]返回nil。
func WithoutCancel(parent Context) Context {if parent == nil {panic("cannot create context from nil parent")}return withoutCancelCtx{parent}
}type withoutCancelCtx struct {c Context
}func (withoutCancelCtx) Deadline() (deadline time.Time, ok bool) {return
}func (withoutCancelCtx) Done() <-chan struct{} {return nil
}func (withoutCancelCtx) Err() error {return nil
}func (c withoutCancelCtx) Value(key any) any {return value(c, key)
}func (c withoutCancelCtx) String() string {return contextName(c.c) + ".WithoutCancel"
}//WithDeadline返回父上下文的副本，并调整了截止日期
//如果家长的截止日期已经早于d，
//WithDeadline（parent，d）在语义上等同于parent。回归
//[Context.Done]通道在截止日期到期时关闭，当返回
//cancel函数被调用，或者当父上下文的Done通道为
//关闭，以先发生者为准。
//
//取消此上下文会释放与其关联的资源，因此代码应该
//一旦在此[Context]中运行的操作完成，就调用cancel。
func WithDeadline(parent Context, d time.Time) (Context, CancelFunc) {return WithDeadlineCause(parent, d, nil)
}//WithDeadlineCause的行为类似于[WithDeadline]，但也设置了
//超过截止日期时返回上下文。返回的[CancelFunc]
//不确定原因。
func WithDeadlineCause(parent Context, d time.Time, cause error) (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{deadline: d,}c.cancelCtx.propagateCancel(parent, c)dur := time.Until(d)if dur <= 0 {c.cancel(true, DeadlineExceeded, cause) // deadline has already passedreturn c, func() { c.cancel(false, Canceled, nil) }}c.mu.Lock()defer c.mu.Unlock()if c.err == nil {c.timer = time.AfterFunc(dur, func() {c.cancel(true, DeadlineExceeded, cause)})}return c, func() { c.cancel(true, Canceled, nil) }
}

timerCtx

timerCtx 在 cancelCtx 基础上又做了一层封装，除了继承 cancelCtx 的能力之外，新增了一个 time.Timer 用于定时终止 context；另外新增了一个 deadline 字段用于字段 timerCtx 的过期时间.

//timerCtx包含计时器和截止日期。它嵌入了cancelCtx
//实现完成和错误。它通过停止计时器来实现取消
//委托取消Ctx.cancel。
type timerCtx struct {cancelCtxtimer *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, cause error) {c.cancelCtx.cancel(false, err, cause)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))
}// WithTimeoutCause behaves like [WithTimeout] but also sets the cause of the
// returned Context when the timeout expires. The returned [CancelFunc] does
// not set the cause.
func WithTimeoutCause(parent Context, timeout time.Duration, cause error) (Context, CancelFunc) {return WithDeadlineCause(parent, time.Now().Add(timeout), cause)
}

valueCtx

//WithValue返回父项的副本，其中与键关联的值为
//瓦尔。
//
//仅对传输进程和进程的请求范围数据使用上下文值
//API，不用于向函数传递可选参数。
//
//提供的密钥必须具有可比性，并且不应为同一类型
//string或任何其他内置类型，以避免它们之间的冲突
//使用上下文的包。WithValue的用户应该定义自己的
//按键类型。为了避免在分配时进行分配
//接口｛｝，上下文键通常具有具体类型
//结构｛｝。或者，导出上下文键变量的静态
//类型应该是指针或接口。
func WithValue(parent Context, key, val any) 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 &valueCtx{parent, key, val}
}//valueCtx包含一个键值对。它为该键实现了Value
//将所有其他调用委托给嵌入式Context。
type valueCtx struct {Contextkey, val any
}//stringify尝试在不使用fmt的情况下对v进行字符串化，因为我们没有
//希望上下文取决于unicode表。这仅用于
//*valueCtx。String（）。
func stringify(v any) string {switch s := v.(type) {case stringer:return s.String()case string:return scase nil:return "<nil>"}return reflectlite.TypeOf(v).String()
}func (c *valueCtx) String() string {return contextName(c.Context) + ".WithValue(" +stringify(c.key) + ", " +stringify(c.val) + ")"
}func (c *valueCtx) Value(key any) any {if c.key == key {return c.val}return value(c.Context, key)
}func value(c Context, key any) any {for {switch ctx := c.(type) {case *valueCtx:if key == ctx.key {return ctx.val}c = ctx.Contextcase *cancelCtx:if key == &cancelCtxKey {return c}c = ctx.Contextcase withoutCancelCtx:if key == &cancelCtxKey {//这实现了Cause（ctx）==nil
//当使用WithoutCancel创建ctx时。return nil}c = ctx.ccase *timerCtx:if key == &cancelCtxKey {return &ctx.cancelCtx}c = ctx.Contextcase backgroundCtx, todoCtx:return nildefault:return c.Value(key)}}
}

其他

函数

CancelFunc

//CancelFunc告诉一个操作放弃它的工作。
//CancelFunc不会等待工作停止。
//CancelFunc可以被多个goroutines同时调用。
//在第一次调用之后，对CancelFunc的后续调用什么也不做。
type CancelFunc func()//WithCancel返回一个父级的副本，其中包含一个新的“完成”频道。回归
//当调用返回的cancel函数时，上下文的Done通道关闭
//或者当父上下文的“完成”通道关闭时，以先发生者为准。
//
//取消此上下文会释放与其关联的资源，因此代码应该
//一旦在此[Context]中运行的操作完成，就调用cancel。
func WithCancel(parent Context) (ctx Context, cancel CancelFunc) {c := withCancel(parent)return c, func() { c.cancel(true, Canceled, nil) }
}

CancelCauseFunc

//CancelCauseFunc的行为类似于[CancelFunc]，但还会设置取消原因。
//可以通过在取消的上下文或上调用[cause]来检索此原因
//其衍生的任何上下文。
//
//如果上下文已被取消，CancelCauseFunc不会设置原因。
//例如，如果childContext派生自parentContext：
//-如果parentContext在childContext被cause 2取消之前被cause 1取消，
//那么原因（parentContext）==原因（childContext）==Cause 1
//-如果childContext在parentContext被cause 1取消之前被cause 2取消，
//那么原因（parentContext）==原因1和原因（childContext）==s原因2
type CancelCauseFunc func(cause error)//WithCancelCause的行为类似于[WithCancel]，但返回的是[CancelCauseFunc]而不是[CancelFunc]。
//调用带有非nil错误（“cause”）的cancel会在ctx中记录该错误；
//然后可以使用Cause（ctx）检索它。
//使用nil调用cancel会将原因设置为Canceled。
//
//示例用法：
//
//ctx，取消：=上下文。取消原因（父）
//取消（myError）
//ctx。Err（）//返回上下文。被取消
//背景。Cause（ctx）//返回myError
func WithCancelCause(parent Context) (ctx Context, cancel CancelCauseFunc) {c := withCancel(parent)return c, func(cause error) { c.cancel(true, Canceled, cause) }
}func withCancel(parent Context) *cancelCtx {if parent == nil {panic("cannot create context from nil parent")}c := &cancelCtx{}c.propagateCancel(parent, c)return c
}//Cause返回一个非nil错误，解释为什么c被取消。
//c或其父项之一的首次取消确定了原因。
//如果取消是通过调用CancelCauseFunc（err）发生的，
//则[Cause]返回err。
//否则，Cause（c）返回与c.Err（）相同的值。
//如果c尚未取消，则Cause返回nil。
func Cause(c Context) error {if cc, ok := c.Value(&cancelCtxKey).(*cancelCtx); ok {cc.mu.Lock()defer cc.mu.Unlock()return cc.cause}//没有cancelCtxKey值，所以我们知道c是//不是WithCancelCause创建的某些上下文的后代。//因此，没有具体的返回原因。//如果这不是标准上下文类型之一，//即使没有原因，它也可能仍然有错误。return c.Err()
}

AfterFunc

//AfterFunc安排在ctx完成后在自己的goroutine中调用f
//（已取消或超时）。
//如果ctx已经完成，AfterFunc会立即在自己的goroutine中调用f。
//
//在一个上下文中对AfterFunc的多个调用独立操作；
//一个不能取代另一个。
//
//调用返回的stop函数停止ctx与f的关联。
//如果调用停止f的运行，则返回true。
//如果stop返回false，
//要么上下文已经完成，f已经在自己的goroutine中启动；
//或者f已经停止了。
//stop函数在返回之前不会等待f完成。
//如果呼叫者需要知道f是否完成，
//它必须与f显式协调。
//
//如果ctx有一个“AfterFunction（func）func（bool）”方法，
//AfterFunc将使用它来安排通话。
func AfterFunc(ctx Context, f func()) (stop func() bool) {a := &afterFuncCtx{f: f,}a.cancelCtx.propagateCancel(ctx, a)return func() bool {stopped := falsea.once.Do(func() {stopped = true})if stopped {a.cancel(true, Canceled, nil)}return stopped}
}

afterFuncer

type afterFuncer interface {AfterFunc(func()) func() bool
}type afterFuncCtx struct {cancelCtxonce sync.Once //要么开始运行f，要么停止运行ff    func()
}func (a *afterFuncCtx) cancel(removeFromParent bool, err, cause error) {a.cancelCtx.cancel(false, err, cause)if removeFromParent {removeChild(a.Context, a)}a.once.Do(func() {go a.f()})
}