本文源码版本基于 go1.21.13

# Context

标准库中的 Context 是一个接口，其具体实现有很多种，主要用于跨多个 Goroutine 设置截止时间、同步信号、传递上下文请求值等。

	// Context 携带截止时间、取消信号和其他跨 API 边界的值。
	// Context 的方法可能被多个 goroutine 同时调用。
	type Context interface {
	// Deadline 返回代表此 context 完成的工作应被取消的时间。
	// 当未设置截止日期时，Deadline 返回 ok==false。连续调用 Deadline 会返回相同的结果。
	Deadline() (deadline time.Time, ok bool)

	// Done 返回一个 chan，当代表此 Context 完成工作时，该通道将被关闭。
	// 如果此 Context 永远无法 cancel，则 Done 可能返回 nil。
	// 对 Done 的连续调用将返回相同的值。
	Done() <-chan struct{}

	// 如果 Done 尚未关闭，Err 将返回 nil。
	// 如果 Done 已关闭，Err 将返回一个非零错误，解释原因：
	// 如果 Context 被取消，则返回 Canceled
	// 如果 Context 的截止时间已过，则返回 DeadlineExceeded。
	// Err 返回非零错误后，对 Err 的连续调用将返回相同的错误。
	Err() error

	// Value 返回与此 context 关联的 key 值，如果没有与 key 关联的值，则返回 nil。
	// 使用相同 key 连续调用 Value 将返回相同结果。
	//context values 仅用于跨进程和 API 边界的请求范围数据传递，而非作为函数的可选参数进行传递。
	//key 用于标识 Context 中的特定值。希望将值存储在 Context 中的函数通常会在全局变量中分配一个 key，然后将该 key 作为 context.WithValue 和 Context.Value 的参数。
	//key 可以是任何支持相等比较的类型；
	// 为避免冲突，包应将 key 定义为 private 的类型。
	Value(key any) any
	}

Done 的 demo 用法

	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:
	}
	}
	}

Value 的 demo 用法

	// Package user defines a User type that's stored in Contexts.
	package user

	import "context"

	// User 是 Contexts 的值
	type User struct {...}

	//key 是此包中定义的 key 的未导出类型。
	// 这可以防止与其他包中定义的 key 发生冲突。
	type key int

	//userKey 是用户的 key。
	// 用于 Context 中的用户值。该 key 是 private 的；
	// 应使用 user.NewContext 和 user.FromContext 而非直接使用此 key。
	var userKey key

	// NewContext 返回一个新的 Context 携带 u 的值
	func NewContext(ctx context.Context, u *User) context.Context {
	return context.WithValue(ctx, userKey, u)
	}

	// FromContext 返回存储在 ctx 中的值
	func FromContext(ctx context.Context) (*User, bool) {
	u, ok := ctx.Value(userKey).(*User)
	return u, ok
	}

# Context 内部类型

# emptyCtx

emptyCtx 是一个没有 cancel 过的，没有 deadline 的，没有值的空 ctx。

emptyCtx 是 backgroundCtx 和 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
	}

# backgroundCtx

context.Background() 返回一个 backgroundCtx ，本质上是 emptyCtx，主要用于主函数、初始化、test case 作为请求的顶级 Contex 传入

	type backgroundCtx struct{ emptyCtx }

	func (backgroundCtx) String() string {
	return "context.Background"
	}
	func Background() Context {
	return backgroundCtx{}
	}

# todoCtx

context.TODO() 返回一个 todoCtx ，本质上是 emptyCtx，主要用于不清楚要用哪个 context 或者其他函数还没有开始定义接受 ctx 的参数，

	type todoCtx struct{ emptyCtx }

	func (todoCtx) String() string {
	return "context.TODO"
	}

	func TODO() Context {
	return todoCtx{}
	}

# cancelCtx

可以被 canceled 的 ctx，当它 canceled 时，也会取消它的 children

	type cancelCtx struct {
	Context

	mu sync.Mutex // 保护以下字段
	done atomic.Value // 惰性创建的 chan struct {}，通过第一次取消调用 close
	children map[canceler]struct{} // 通过第一次取消调用设置为空
	err error // 通过第一次取消调用设置为非空
	cause error // 通过第一次取消调用设置为非空
	}

具体的取消逻辑见下文

# stopCtx

stopCtx 被用作 cancelCtx 的 parent context 当一个 AfterFunc 已在 parent context 中注册时.
它包含用于取消注册 AfterFunc 的停止函数。

	type stopCtx struct {
	Context
	stop func() bool
	}

# timerCtx

timerCtx 带有一个计时器和一个截止时间。

通过停止计时器然后委托给 cancelCtx.cancel 来实现特定时间取消。

嵌入了 cancelCtx 来实现 Done 和 Err 操作。

	type timerCtx struct {
	cancelCtx
	timer *time.Timer // Under cancelCtx.mu.

	deadline time.Time
	}

# valueCtx

valueCtx 携带了两个无限制变量 key, val any 。嵌入了 Context 来实现其他调用。

	type valueCtx struct {
	Context
	key, val any
	}

# cancel

	type cancelCtx struct {
	Context

	mu sync.Mutex // 保护以下字段
	done atomic.Value // 惰性创建的 chan struct {}，通过第一次取消调用 close
	children map[canceler]struct{} // 通过第一次取消调用设置为空
	err error // 通过第一次取消调用设置为非空
	cause error // 通过第一次取消调用设置为非空
	}

# 创建 cancelCtx

	// CancelFunc 告诉操作放弃其工作。
	// CancelFunc 不会等待工作停止。
	// CancelFunc 可能被多个 goroutine 同时调用。
	// 第一次调用后，对 CancelFunc 的后续调用不会执行任何操作。
	type CancelFunc func()

	// WithCancel 返回父级的副本，其中包含新的 Done 通道。
	// 当调用返回的取消函数或关闭 parent context 的 Done 通道时（以先发生者为准），返回 context 的 Done 通道将关闭。
	// 取消此 context 会释放与其关联的资源，因此代码应在此 context 中操作完成后立即调用取消。
	func WithCancel(parent Context) (ctx Context, cancel CancelFunc) {
	c := withCancel(parent)
	return c, func() { c.cancel(true, Canceled, nil) }
	}



	// CancelCauseFunc 的行为类似于 [CancelFunc]，但还设置了取消原因。
	// 可以通过调用 [Cause] 方法在取消的 context 或其任何衍生的 context 来检索取消原因。

	// 如果 context 已被取消，则 CancelCauseFunc 不会设置 cause。
	// 例如，如果 childContext 衍生自 parentContext：
	// 如果在使用 cause2 取消 childContext 之前使用 cause1 取消了 parentContext，
	// 则 Cause (parentContext) == Cause (childContext) == cause1
	// 如果在使用 cause1 取消 parentContext 之前使用 cause2 取消了 childContext
	// 则 Cause (parentContext) == cause1 并且 Cause (childContext) == cause2
	type CancelCauseFunc func(cause error)

	// WithCancelCause 的行为类似于 [WithCancel]，但返回的是 [CancelCauseFunc]，而不是 [CancelFunc]。
	// 使用非空错误（cause）调用 cancel 会将该错误记录在 ctx 中；然后可以使用 Cause (ctx) 检索它。
	// 使用 nil 调用 cancel 会将原因设置为 Canceled。
	// Example use:
	// ctx, cancel := context.WithCancelCause(parent)
	// cancel(myError)
	// ctx.Err() // returns context.Canceled
	// context.Cause(ctx) // returns 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
	}

	//propagateCancel 设置了当 parent canceled 的时候 child 也会被 cancel
	func (c *cancelCtx) propagateCancel(parent Context, child canceler) {
	c.Context = parent

	done := parent.Done()
	if done == nil {
	return // parent is never canceled
	}

	// 如果 done channel 不是 nil，说明 parent Context 是一个可以取消的 Context
	// 如果 done channel 可读取，说明上面为无锁阶段
	// 如果 parent Context 已经被取消了，那么应该立即取消 child Context
	select {
	case <-done:
	// parent is already canceled
	child.cancel(false, parent.Err(), Cause(parent))
	return
	default:
	}

	// 获取最底层的 cancelCtx
	if p, ok := parentCancelCtx(parent); ok {
	//parent 为 *cancelCtx, 能转换成 cancelCtx
	p.mu.Lock()
	if p.err != nil {
	//parent 已经被 cancel 了
	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
	}

	// 当 parent cancel 时，同步 cancel child
	goroutines.Add(1)
	go func() {
	select {
	case <-parent.Done():
	child.cancel(false, parent.Err(), Cause(parent))
	case <-child.Done():
	}
	}()
	}

	//parentCancelCtx 返回父节点的底层 *cancelCtx。
	// 它通过查找 parent.Value (&cancelCtxKey) 来找到最内层的 * cancelCtx，然后检查 parent.Done () 是否与该 * cancelCtx 匹配（如果不匹配，则该 * cancelCtx 已被一个提供不同完成通道的自定义实现所封装，在这种情况下，我们不应跳过它）。
	func parentCancelCtx(parent Context) (*cancelCtx, bool) {
	done := parent.Done()
	// 如果 parent context 的 done 为可复用的 closedchan 说明 parent context 已经 cancel 了
	// 如果 parent context 的 done 为 nil 说明不支持 cancel，那么就不可能是 cancelCtx
	if done == closedchan \|\| done == nil {
	return nil, false
	}
	// 如果 parent context 属于原生的 *cancelCtx 或衍生类型 (timerCtx) 需要继续进行后续判断
	// 如果 parent context 无法转换到 *cancelCtx，则认为非 cancelCtx，返回 nil,fasle
	p, ok := parent.Value(&cancelCtxKey).(*cancelCtx)
	if !ok {
	return nil, false
	}

	// 经过上面的判断后，说明 parent context 可以被转换为 *cancelCtx，这时存在多种情况:
	// - parent context 就是 *cancelCtx
	// - parent context 是标准库中的 timerCtx
	// - parent context 是个自己自定义包装的 cancelCtx
	//
	// 针对这 3 种情况需要进行判断，判断方法就是:
	// 判断 parent context 通过 Done () 方法获取的 done channel 与 Value 查找到的 context 的 done channel 是否一致
	//
	// 一致情况说明 parent context 为 cancelCtx 或 timerCtx 或自定义的 cancelCtx 且未重写 Done ()，
	// 这种情况下可以认为拿到了底层的 *cancelCtx
	//
	// 不一致情况说明 parent context 是一个自定义的 cancelCtx 且重写了 Done () 方法，并且并未返回标准 *cancelCtx 的
	// 的 done channel，这种情况需要单独处理，故返回 nil, false
	pdone, _ := p.done.Load().(chan struct{})
	if pdone != done {
	return nil, false
	}
	return p, true
	}

# 取消 cancelCtx

cancelCtx 内部跨多个 Goroutine 实现信号传递其实靠的就是一个 done channel；如果要取消这个 Context，那么就需要让所有 <-c.Done() 停止阻塞，这时候最简单的办法就是把这个 channel 直接 close 掉，或者干脆换成一个已经被 close 的 channel

	//canceler 是一种可以直接取消的 context 类型。其实现是 cancelCtx 和 timerCtx。
	type canceler interface {
	cancel(removeFromParent bool, err, cause error)
	Done() <-chan struct{}
	}


	//cancel 关闭 c.done，取消 c 的每个 child，如果 removeFromParent 为 true，则从 parent 的 childen 中删除 c。
	// 如果这是第一次取消 c，cancel 会将 c.cause 设置为 cause。
	func (c *cancelCtx) cancel(removeFromParent bool, err, cause error) {
	if err == nil {
	panic("context: internal error: missing cancel error")
	}
	if cause == nil {
	cause = err
	}
	// 对 context 加锁，防止并发更改
	c.mu.Lock()
	// 如果加锁后有并发访问，那么二次判断 err 可以防止重复 cancel 调用
	if c.err != nil {
	c.mu.Unlock()
	return // already canceled
	}

	c.err = err
	c.cause = cause
	d, _ := c.done.Load().(chan struct{})
	if d == nil {
	// 如果 done channel 为 nil，那么就把它设置成共享可重用的一个已经被关闭的 channel
	c.done.Store(closedchan)
	} else {
	// 如果 done channel 已经被初始化，则直接 close 它
	close(d)
	}
	for child := range c.children {
	// NOTE: 持有 parent 锁的同时，获取 child 的锁
	child.cancel(false, err, cause)
	}
	c.children = nil
	c.mu.Unlock()

	// 如果 removeFromParent 为 true，那么从 parent Context 中清理掉自己
	if removeFromParent {
	removeChild(c.Context, c)
	}
	}

	// 从 parent 中删除一个 context
	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()
	}

# timerCtx

	type timerCtx struct {
	cancelCtx
	timer *time.Timer // Under cancelCtx.mu.

	deadline time.Time
	}

# 创建 timerCtx

timerCtx 的创建主要通过 context.WithDeadline 方法，

同时 context.WithTimeout 、 WithTimeoutCause 实际上也是调用的 context.WithDeadlineCause :

	// WithTimeout returns WithDeadline(parent, time.Now().Add(timeout)).
	//cancel 此 context 会释放与其相关的资源，因此代码应在此 context 中运行的操作完成后立即调用取消。
	func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
	return WithDeadline(parent, time.Now().Add(timeout))
	}


	// WithTimeoutCause 的行为与 [WithTimeout] 类似，但也会在超时时设置返回 Context 的 cause。返回的 [CancelFunc] 不会设置原因。
	func WithTimeoutCause(parent Context, timeout time.Duration, cause error) (Context, CancelFunc) {
	return WithDeadlineCause(parent, time.Now().Add(timeout), cause)
	}


	// WithDeadline 返回 parent context 的副本，deadline 调整为不晚于 d
	// 如果 parent context 的 deadline 已经早于 d，则 WithDeadline (parent, d) 在语义上等同于父 context。
	// 返回的 [Context.Done] channel 会在 deadline 到期、调用返回的取消函数或 parent context 的 Done 通道关闭时关闭 (以先发生者为准)。
	func WithDeadline(parent Context, d time.Time) (Context, CancelFunc) {
	return WithDeadlineCause(parent, d, nil)
	}


	// WithDeadlineCause 的行为与 [WithDeadline] 类似，但会在超过 deadline 时设置返回 Context 的 cause。返回的 [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) {
	// 目前的日期已经早于新的截止日期
	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 已经到期
	return 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

调用一下里面的 cancelCtx 的 cancel，然后再把定时器停掉:

	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()
	}

# valueCtx

	type valueCtx struct {
	Context
	key, val any
	}

	// WithValue 返回 parent 的副本，其中与 key 关联的值为 val。
	// 用 context 的值仅用于传输进程和 API 的请求范围数据，而不是用于向函数传递可选参数。
	// 提供的 key 必须具有可比性，且不应是字符串或任何其他内置类型，以避免使用 context 的软件包之间发生冲突。
	// WithValue 的用户应为 key 定义自己的类型。为避免在赋值给 interface {} 时进行分配，context key 通常采用具体的 struct {} 类型。或者，导出 context key 变量的静态类型应为指针或接口。
	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}
	}

	// 打印
	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 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.Context
	case *cancelCtx:
	if key == &cancelCtxKey {
	return c
	}
	c = ctx.Context
	case withoutCancelCtx:
	if key == &cancelCtxKey {
	// This implements Cause(ctx) == nil
	// when ctx is created using WithoutCancel.
	return nil
	}
	c = ctx.c
	case *timerCtx:
	if key == &cancelCtxKey {
	return &ctx.cancelCtx
	}
	c = ctx.Context
	case backgroundCtx, todoCtx:
	return nil
	default:
	return c.Value(key)
	}
	}
	}

# Context

# Context 内部类型

# emptyCtx

# backgroundCtx

# todoCtx

# cancelCtx

# stopCtx

# timerCtx

# valueCtx

# cancel

# 创建 cancelCtx

# 取消 cancelCtx

# timerCtx

# 创建 timerCtx

# 取消 timerCtx

# valueCtx

golang 多版本环境控制