---

摘要

Context是go语言用于上下文管理的包，主要用于携程间的上下文管理，控制携程按时或者按时间取消执行。多个Context按树形或者链表的结果向前连接。Context是一个接口类型，实现了接口下的方法的类型，都可以认为是Context类型。包括emptyCtx、valueCtx、cancelCtx、timerCtx，它们是Context的具体实现。其中：

• emptyCtx是一个空的Context，不能存储数据。常用作Context树的根节点。
• valueCtx是用来存储键值对数据的Context。
• cencelCtx是能够存储键值对数据并且能够取消的Context。
• timerCtx是能够用来存储键值对数据，能设置时间取消的Context。

1. context接口

type Context interface {

    Deadline() (deadline time.Time, ok bool) // 返回消息过期时间的方法。如果没设置过期时间，ok将为false

    Done() <-chan struct{} // 若当前context被取消，返回一个关闭的channel；否则，返回nil

    Err() error // 如果context未取消，返回nil；如果已经取消，返回取消原因。

    Value(key interface{}) interface{} // 返回context中存储的键值对。
}

2. 实现context接口的类型

2.1 emptyCtx

emptyCtx是一个等价于int类型的类型，实现了Context接口。它不能设置超时时间，不能存储消息。常用作Context的根节点（Context之间按树形或者链式结构向前连接）。

type emptyCtx int
// 不能设置过期时间，所有没过期时间，ok为false（bool类型的零值）
func (*emptyCtx) Deadline() (deadline time.Time, ok bool) {
    return
}
// 不会被取消，所以为nil
func (*emptyCtx) Done() <-chan struct{} {
    return nil
}
// 不会被取消，所以为nil
func (*emptyCtx) Err() error {
    return nil
}
// 不能存储值，所以为nil
func (*emptyCtx) Value(key interface{}) interface{} {
    return nil
}
// 显示当前的context是background还是todo
func (e *emptyCtx) String() string {
    switch e {
    case background:
        return "context.Background"
    case todo:
        return "context.TODO"
    }
    return "unknown empty Context"
}
// background和todo本质上一样，只是语义上不一样。
// background常在主函数、初始化、测试中使用。
// todo 是在不确定使用什么context的时候才会使用
var (
    background = new(emptyCtx)
    todo       = new(emptyCtx)
)

func Background() Context {
    return background
}

func TODO() Context {
    return todo
}

2.2 valueCtx

能够存储键值对数据信息的Context。

// 结构体类型，能够存储一对值
type valueCtx struct {
    Context
    key, val interface{}
}
// 获取值，如果当前context不存在key对应的值，会去上一个context节点中找，直至到根节点
func (c *valueCtx) Value(key interface{}) interface{} {
    if c.key == key {
        return c.val
    }
    return c.Context.Value(key)
}

如何添加值？

// 在context（valueCtx）链表尾部添加值
func WithValue(parent Context, key, val interface{}) Context {
    if key == nil {
        panic("nil key")
    }
    if !reflect.TypeOf(key).Comparable() {
        panic("key is not comparable")
    }
    return &valueCtx{parent, key, val}
}

添加的时候，要求传入的k是能够比较的值，并且也不是直接插入到Context（valueCtx）中的，而是重新创建一个新的context（valueCtx）存储（k,v）并插入到链表尾部。如下图所示。

2.3 cancelCtx

可取消的cancelCtx

type cancelCtx struct {
    Context

    mu       sync.Mutex            // protects following fields
    done     chan struct{}         // 用来传递关闭信号的channel
    children map[canceler]struct{} // 存储当前context下的子节点
    err      error                 // 存储任务结束的原因信息
}
// 用于撤销
type canceler interface {
    cancel(removeFromParent bool, err error)
    Done() <-chan struct{}
}

cancelCtx下的方法

// 返回c.done状态
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
}
// 返回c.err状态
func (c *cancelCtx) Err() error {
    c.mu.Lock()
    err := c.err
    c.mu.Unlock()
    return err
}
// 撤销context及它的子context
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
    // 设置一个关闭的channel或者将done channel关闭，用以发送关闭信号
    if c.done == nil {
        c.done = closedchan
    } else {
        close(c.done)
    }
    // 将子节点context依次取消
    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 {
        // 将当前context节点从父节点上移除
        removeChild(c.Context, c)
    }
}

怎么创建新的cancelCtx。使用WithCancel

type CancelFunc func()
// 
func WithCancel(parent Context) (ctx Context, cancel CancelFunc) {
    c := newCancelCtx(parent)
    propagateCancel(parent, &c)
    return &c, func() { c.cancel(true, Canceled) }
}

// newCancelCtx returns an initialized cancelCtx.
func newCancelCtx(parent Context) cancelCtx {
    // 将parent作为父节点context生成一个新的子节点
    return cancelCtx{Context: parent}
}

func propagateCancel(parent Context, child canceler) {
    if parent.Done() == nil {
        // parent.Done()返回nil表明父节点以上的路径上没有可取消的context
        return // parent is never canceled
    }
    // 获取最近的类型为cancelCtx的祖先节点
    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{})
            }
            // 将当前子节点加入最近cancelCtx祖先节点的children中
            p.children[child] = struct{}{}
        }
        p.mu.Unlock()
    } else {
        go func() {
            select {
            case <-parent.Done():
                child.cancel(false, parent.Err())
            case <-child.Done():
            }
        }()
    }
}

func parentCancelCtx(parent Context) (*cancelCtx, bool) {
    for {
        switch c := parent.(type) {
        case *cancelCtx:
            return c, true
        case *timerCtx:
            return &c.cancelCtx, true
        case *valueCtx:
            parent = c.Context
        default:
            return nil, false
        }
    }
}

2.4 timerCtx

能够存储数据，根据时间或者事件取消的Context。其结构对cencelCtx封装，并添加了个生命时间。

// 时间控制Context
type timerCtx struct {
    cancelCtx
    timer *time.Timer // Under cancelCtx.mu.

    deadline time.Time
}
// 返回Context的截至日期
func (c *timerCtx) Deadline() (deadline time.Time, ok bool) {
    return c.deadline, true
}
// 返回
func (c *timerCtx) cancel(removeFromParent bool, err error) {
    // 将内部的cancelCtx取消
    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()
}