深入Go：Context

// 一个emptyCtx不能被取消、没有Values或deadline。
// 它不是struct{}类型因为每个emptyCtx实例都需要不同的地址㊟。
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 { /* 见下方 var background 和 todo */
    switch e {
    case background:
        return "context.Background"
    case todo:
        return "context.TODO"
    }
    return "unknown empty Context"
}

var (
    background = new(emptyCtx)
    todo       = new(emptyCtx)
)
/* 即，emptyCtx的实例有且仅有这里的 backgroud 与 todo */

// Background 返回非nil的空Context。它不能被取消、没有Values或deadline。
// 它被用于main函数、初始化、测试与顶层的请求。
func Background() Context {
    return background
}

// TODO 返回非nil的空Context。当不确定应该使用哪一个Context或Context暂时不可用
// （因该处的函数还没有被扩展以接收Context参数）时，代码应使用context.TODO。
func TODO() Context {
    return todo
}

type S struct{}

func s1() {
    s1, s2 := S{}, S{}
    println(&s1 == &s2)
}

func s2() {
    s1, s2 := S{}, S{}
    fmt.Printf("%p, %p, %t\n", &s1, &s2, &s1 == &s2)
}

func main() {
    s1()
    s2()
}

false
0x119e408, 0x119e408, true

./main.go:19:2: moved to heap: s1
./main.go:19:6: moved to heap: s2
./main.go:20:43: &s1 == &s2 escapes to heap
./main.go:20:12: []interface {} literal does not escape

// 一个CancelFunc告知相关操作应被取消。
// 一个CancelFunc并不等待操作结束。
// 一个CancelFunc可以被多个goroutine并发调用。
// 第一次调用后，对CancelFunc的随后调用无实际效果。
type CancelFunc func()

// WithCancel 返回parent的一个拷贝以及一个新的Done channel。
// 在返回的cancel函数被调用时，或其父context的Done channel被关闭时，
// 返回的context的Done channel被关闭。
//
// 取消该context将释放相关的资源⑴，
// 因此代码应该在本Context相关的操作结束时立即调用cancel。
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 返回初始化后的cancelCtx实例。
func newCancelCtx(parent Context) cancelCtx {
    return cancelCtx{Context: parent}
}

// goroutines ...; 测试用。
var goroutines int32

// propagateCancel 使得parent被cancel时，cancel掉child。
func propagateCancel(parent Context, child canceler) {
    done := parent.Done()
    if done == nil {
        return // parent不能被cancel
    }

    select {
    case <-done:
        // 此时parent已经被cancel
        child.cancel(false, parent.Err())
        return
    default:
    }
    /* parentCancelCtx 尝试返回parent的cancelCtx指针 */
    if p, ok := parentCancelCtx(parent); ok { 
        p.mu.Lock()
        if p.err != nil {
            // parent 已经被cancel
            child.cancel(false, p.err)
        } else {
            if p.children == nil {
                p.children = make(map[canceler]struct{})
            }
            p.children[child] = struct{}{}
        }
        p.mu.Unlock()
    } else { /* 例外，此时只能新启动协程监听parent.Done */
    /* 例如parent恰好被cancel，或parent为非cancelCtx结构(没法通过children来cancel) */
        atomic.AddInt32(&goroutines, +1)
        go func() {
            select {
            case <-parent.Done():
                child.cancel(false, parent.Err())
            case <-child.Done():
            }
        }()
    }
}

// &cancelCtxKey 为cancelCtx返回其自身的指针值的key。
var cancelCtxKey int

// parentCancelCtx 返回承载parent的*cancelCtx。
// 本函数通过查parent.Value(&cancelCtxKey)来找到最里层的*cancelCtx，
// 并检查parent.Done()是否匹配该*cancelCtx。
// （如果不匹配，则该*cancelCtx已被嵌入非默认的、提供不同done channel的实现中，
// 此时我们不应绕过该它⑵。）
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 从parent处移除该context。
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()
}

// 一个canceler为可以被直接cancel的context类型。
// 实现包括：*cancelCtx和*timerCtx。
type canceler interface {
    cancel(removeFromParent bool, err error)
    Done() <-chan struct{}
}

// closedchan 为用于复用的、代表已关闭的channel⑶。
/* 在init中确保closedchan被关闭 */
var closedchan = make(chan struct{})

func init() {
    close(closedchan)
}

// cancelCtx实例可以被cancel。当其被cancel，
// 该实例也将cancel其所有实现了canceler的子节点
type cancelCtx struct {
    Context /* 此即parent Context */

  mu       sync.Mutex            // mu用于保护下列字段
  done     atomic.Value          // 延迟创建的done用于存储chan struct{}
                                  // 并在第一次cancel时被关闭
    children map[canceler]struct{} // 第一次cancel将该字段设为nil
    err      error                 // 第一次cancel将该字段设为非nil
}

func (c *cancelCtx) Value(key interface{}) interface{} {
    if key == &cancelCtxKey {
        return c
    }
    return c.Context.Value(key) /* 在parent的Value中查找 */
}

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.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 关闭c.done、cancel所有c的子Context，且如果
// removeFromParent为true，则将其从parent的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 // 已经被cancel过
    }
    c.err = err
    d, _ := c.done.Load().(chan struct{})
  if d == nil { // done还没被使用chan struct{}创建
        c.done.Store(closedchan)
    } else {
        close(d)
    }
    for child := range c.children {
        // 注意：此时持有parent的锁，并申请child的锁
        child.cancel(false, err)
    }
    c.children = nil
    c.mu.Unlock()

    if removeFromParent {
        removeChild(c.Context, c)
    }
}

go func() {
  select {
    case <-parent.Done():
    child.cancel(false, parent.Err())
    case <-child.Done():
    }
}()

type CustomContext struct {
    context.Context
    c chan struct{}
}

func (c *CustomContext) Done() <-chan struct{} {
    return c.c
}

func main() {
    println(runtime.NumGoroutine()) // 1
    inner, cancel := context.WithCancel(context.Background())
    defer cancel()
    c := &CustomContext{inner, make(chan struct{})}
    _, cancel2 := context.WithCancel(c)
    defer cancel2()
    println(runtime.NumGoroutine()) // 2
}

// WithDeadline 返回附有截止时间不晚于d的parent的拷贝。
// 如果parent的deadline早于d，
// WithDeadline(parent, d)语义上与parent相同。
// 返回的Context的Done channel将被关闭，当下列任一情况满足：
// 到达截止时间，或
// 返回的cancel函数被调用，或
// parent的Done channel被关闭。
//
// 取消该context将释放相关的资源㊟，
// 因此代码应该在本Context相关的操作结束时立即调用cancel。
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) {
        // 已有的截止时间早于参数d
        return WithCancel(parent)
    }
    c := &timerCtx{
        cancelCtx: newCancelCtx(parent),
        deadline:  d,
    }
    propagateCancel(parent, c)
    dur := time.Until(d)
    if dur <= 0 {
        c.cancel(true, DeadlineExceeded) // 截止时间已超过
        return c, func() { c.cancel(false, Canceled) } /* 此时返回的c已被cancel */
    }
    c.mu.Lock() /* 因为可能此时parent被cancel，所以需要用c.mu保护 */
    defer c.mu.Unlock()
    if c.err == nil { /* 也是防止在获取锁之前因parent而被cancel */
        c.timer = time.AfterFunc(dur, func() {
            c.cancel(true, DeadlineExceeded)
        })
    }
    return c, func() { c.cancel(true, Canceled) }
}

// timerCtx实例包含一个计时器与截止时间。它嵌入了一个cancelCtx来实现Done与Err。
// 它通过停止其计时器并使用cancelCtx.cancel来实现cancel。
type timerCtx struct {
    cancelCtx
    timer *time.Timer // 受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 {
        // 从parent处移除c
        removeChild(c.cancelCtx.Context, c) /* 真正的parent是c.cancelCtx.Context */
    }
    c.mu.Lock()
    if c.timer != nil {
        c.timer.Stop()
        c.timer = nil
    }
    c.mu.Unlock()
}

// WithTimeout 返回WithDeadline(parent, time.Now().Add(timeout))。
//
// 取消该context将释放相关的资源，
// 因此代码应该在本Context相关的操作结束时立即调用cancel：
//
//     func slowOperationWithTimeout(ctx context.Context) (Result, error) {
//         ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)
//         defer cancel()  // 如果slowOperation在超时之前就完成了，则释放资源
//         return slowOperation(ctx)
//     }
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
    return WithDeadline(parent, time.Now().Add(timeout))
}

// WithValue 返回parent的拷贝，并附上key对应的值val。
//
// 仅对不同进程与API间转移的请求范畴内的数据使用context的Value，
// 而不是用以传递函数的可选参数。
//
// 提供的key必须是可比较的类型，且为避免在各使用context的包内冲突，
// 它不应是字符串或任意内置类型。使用WithValue的用户应自定义key的类型。
// 为避免赋值给interface{}时的内存分配，context key通常使用类型struct{}。
// 另外，导出的context key变量的静态类型应该为pointer或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 &valueCtx{parent, key, val}
}

// valueCtx实例携带key-value pair。它对该key实现了Value函数，
// 并使用嵌入的Context来应对其余函数调用。
It implements Value for that key and
// delegates all other calls to the embedded Context.
type valueCtx struct {
    Context
    key, val interface{}
}

// stringify 尝试在不使用fmt的情况下将v转换为字符串，这是因为
// context并不希望依赖unicode表。本函数仅在*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) + ")"
}
/* Value 以类似链表的形式实现，我们在稍后会讨论到 */
func (c *valueCtx) Value(key interface{}) interface{} {
    if c.key == key {
        return c.val
    }
    return c.Context.Value(key)
}

func main() { // 注意，不要用内置类型作为key的类型
    c1 := context.WithValue(context.Background(), hello, "world")
    c2 := context.WithValue(c1, foo, "bar")
    c3 := context.WithValue(c2, hello, "today")
    c4 := context.WithValue(c3, bar, "baz")
    fmt.Println(c4.Value(hello)) // today
    fmt.Println(c2.Value(hello)) // world
}

v1 := context.WithValue(context.Background(), foo, 1)
c, cancel := context.WithCancel(v1)
defer cancel()
done := c.Done()
t, cancel1 := context.WithTimeout(c, time.Second)
defer cancel2()
v2 := context.WithValue(t, bar, "baz")
c2, cancel3 := context.WithCancel(t)
cancel3()
// <- now we give the image representing the state here
return