Go中的Context怎么使用

type Context interface {
  // Deadline returns the time when this Context will be canceled, if any.
	Deadline() (deadline time.Time, ok bool)
  // Done returns a channel that is closed when this Context is canceled
  // or times out.
	Done() <-chan struct{}
  // Err indicates why this context was canceled, after the Done channel
  // is closed.
	Err() error
  // Value returns the value associated with key or nil if none.
	Value(key any) any
}

func WithCancel(parent Context) (ctx Context, cancel CancelFunc) {}
func WithDeadline(parent Context, d time.Time) (Context, CancelFunc) {}
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {}
func WithValue(parent Context, key, val any) Context {}

var (
	background = new(emptyCtx)
	todo       = new(emptyCtx)
)
// Background 创建background context
func Background() Context {
	return background
}
// TODO 创建todo context
func TODO() Context {
	return todo
}

type emptyCtx int // 空context

type cancelCtx struct {
	Context // 父context
	mu       sync.Mutex            // protects following fields
	done     atomic.Value          // of chan struct{}, created lazily, closed by first cancel call
	children map[canceler]struct{} // set to nil by the first cancel call
	err      error                 // cancel的原因
}

type timerCtx struct {
	cancelCtx //父context
	timer *time.Timer // 定时器
	deadline time.Time // 截止时间
}

type valueCtx struct {
	Context // 父context
  key, val any // kv键值对
}

// 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 any) any {
	return nil
}
func (e *emptyCtx) String() string {
	switch e {
	case background:
		return "context.Background"
	case todo:
		return "context.TODO"
	}
	return "unknown empty Context"
}

func WithCancel(parent Context) (ctx Context, cancel CancelFunc) {
	if parent == nil { // 参数校验
		panic("cannot create context from nil parent")
	}
  // cancelCtx 初始化
	c := newCancelCtx(parent)
	propagateCancel(parent, &c) // cancelCtx 父子关系维护及传播取消信号
	return &c, func() { c.cancel(true, Canceled) } // 返回cancelCtx对象及cannel方法
}
// newCancelCtx returns an initialized cancelCtx.
func newCancelCtx(parent Context) cancelCtx {
	return cancelCtx{Context: parent}
}

type cancelCtx struct {
  // 父 context
	Context //  parent context
	// 锁 并发场景下保护cancelCtx结构中字段属性的设置
	mu       sync.Mutex            // protects following fields 
  // done里存储的是信号通道，其创建方式采用的是懒加载的方式
	done     atomic.Value          // of chan struct{}, created lazily, closed by first cancel call 
  // 记录与父子cancelCtx对象，
	children map[canceler]struct{} // set to nil by the first cancel call
  // 记录ctx被取消的原因
	err      error                 // set to non-nil by the first cancel call
}

// propagateCancel arranges for child to be canceled when parent is.
func propagateCancel(parent Context, child canceler) {
	done := parent.Done() // 获取parent ctx的信号通道 done
	if done == nil {  // nil 代表 parent ctx 不是canelctx 类型，不会被取消，直接返回
		return // parent is never canceled
	}
	select { // parent ctx 是cancelCtx类型，判断其是否被取消
	case <-done:
		// parent is already canceled
		child.cancel(false, parent.Err())
		return
	default:
	}
  //parentCancelCtx往树的根节点方向找到最近的context是cancelCtx类型的
	if p, ok := parentCancelCtx(parent); ok { // 查询到
		p.mu.Lock() // 加锁
		if p.err != nil { // 祖父 ctx 已经被取消了，则 子cancelCtx 也需要调用cancel 方法来取消
			// parent has already been canceled
			child.cancel(false, p.err)
		} else { // 使用map结构来维护 将child加入到祖父context中
			if p.children == nil {
				p.children = make(map[canceler]struct{})
			}
			p.children[child] = struct{}{}
		}
		p.mu.Unlock()// 解锁
	} else { // 开启协程监听 parent Ctx的取消信号 来通知child ctx 取消
		atomic.AddInt32(&goroutines, +1)
		go func() {
			select {
			case <-parent.Done():
				child.cancel(false, parent.Err())
			case <-child.Done():
			}
		}()
	}
}

// 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.)
// parentCancelCtx往树的根节点方向找到最近的context是cancelCtx类型的
func parentCancelCtx(parent Context) (*cancelCtx, bool) {
	done := parent.Done()
  // closedchan 代表此时cancelCtx 已取消， nil 代表 ctx不是cancelCtx 类型的且不会被取消
	if done == closedchan || done == nil { 
		return nil, false
	}
  // 向上遍历查询canelCtx 类型的ctx
	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
}

// 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{} // 只读通道，简称取消信号通道
}

// 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
	d, _ := c.done.Load().(chan struct{})
	if d == nil {
		c.done.Store(closedchan)
	} else {
		close(d)
	}
	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)
	}
}

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

// closedchan is a reusable closed channel.
var closedchan = make(chan struct{})
func init() {
	close(closedchan) // 调用close 方法关闭
}

func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
	return WithDeadline(parent, time.Now().Add(timeout))
}

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

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}
}
// 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 any
}

func (c *valueCtx) Value(key any) any {
	if c.key == key { // 判断当前valuectx对象中的key是否匹配
		return c.val
	}
	return value(c.Context, key)
}
// value（） 向根部方向遍历，直到找到与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 { // 获取cancelCtx对象
				return c
			}
			c = ctx.Context
		case *timerCtx:
			if key == &cancelCtxKey {
				return &ctx.cancelCtx
			}
			c = ctx.Context
		case *emptyCtx:
			return nil
		default:
			return c.Value(key)
		}
	}
}