1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

type Context interface {
    // 返回绑定当前ctx的任务被取消的时间 （如果没设置截止时间, 将返回 ok == false）
    Deadline() (deadline time.Time, ok bool)

    // Done returns a channel that is closed when this Context is canceled or times out.
    // 返回一个channel，这个Channel会在 ctx 被取消（调用cancel方法） / 到期（times out）时被关闭，
    // 可以用来监听Context何时被取消。
    Done() <-chan struct{}

    // Err indicates why this context was canceled, after the Done channel is closed.
    // 如果Done返回的chan，没有关闭，err()返回nil；已经关闭，err()返回非nil，解释goroutine被取消的原因，
    // 通常是 context.Canceled 或 context.DeadlineExceeded。
    Err() error
    // Deadline returns the time when this Context will be canceled, if any.

    // Value returns the value associated with key or nil if none.
    // 返回ctx存储的键值对中当前key对应的value（如果没有对应的key, 则返回nil）
    Value(key interface{}) interface{}
}

1
2
3
4
5
6
7
8
9

var Canceled = errors.New("context canceled") 

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 }

1
2
3
4

type canceler interface {
 cancel(removeFromParent bool, err error)
 Done() <-chan struct{}
}

1
2

ctx, cancel := context.WithCancel(context.Background()) 
defer cancel() // 当我们不再需要这个 Context 时，确保释放资源

1

func WithValue(parent Context, key, val interface{}) Context 

1
2
3

func DoSomething(ctx context.Context，arg Arg) error { 
    // ... use ctx ... 
}

1
2

ctx, cancel := context.WithCancel(context.Background()) 
defer cancel() // 当不再需要这个context时，调用cancel释放资源

1
2
3
4
5
6
7

select { 
    case <-ctx.Done(): // 如果收到这个信号，表示上级调用已经取消了这个 Context 
        return ctx.Err() 
    default: // 执行正常的业务逻辑 
        // TODO: worker
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

func main() {
    parentCtx := context.Background()
    ctx, cancel := context.WithTimeout(parentCtx, 1*time.Millisecond)
    defer cancel()
    
    select {
        case <-time.After(1 * time.Second):
            fmt.Println("overslept")
        case <-ctx.Done():
            fmt.Println(ctx.Err())
    }
}

1
2
3
4
5
6

type Context interface {
    Deadline() (deadline time.Time, ok bool)    // 返回context的过期时间
    Done() <-chan struct{}                      // 返回context中的chan，当times out 或 调用cancel方法时，返回的c是close掉的 chan
    Err() error                                 // 返回错误，该context为什么被取消掉。
    Value(key any) any                          // 返回context中存储对应key的值
}

1
2
3
4
5
6
7
8
9

var Canceled = errors.New("context canceled") 

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 }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

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

var (
	background = new(emptyCtx)
	todo       = new(emptyCtx)
)

// Background returns a non-nil, empty Context. It is never canceled, has no
// values, and has no deadline. It is typically used by the main function,
// initialization, and tests, and as the top-level Context for incoming
// requests.
func Background() Context {
	return background
}

// TODO returns a non-nil, empty Context. Code should use context.TODO when
// it's unclear which Context to use or it is not yet available (because the
// surrounding function has not yet been extended to accept a Context
// parameter).
func TODO() Context {
	return todo
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

/*
 *  给parent ctx新建一个子节点（类型cancleCtx）
 * @return  ctx: 新子节点  cacle: 取消函数
 */
func WithCancel(parent Context) (ctx Context, cancel CancelFunc) {
	if parent == nil {
		panic("cannot create context from nil parent")
	}
	c := newCancelCtx(parent) // 新建cancleCtx（详细见4.4.）
	propagateCancel(parent, &c) // 来建立当前节点与祖先节点这个取消关联逻辑
	return &c, func() { c.cancel(true, Canceled) }
}

// newCancelCtx returns an initialized cancelCtx.
func newCancelCtx(parent Context) cancelCtx {
	return cancelCtx{Context: parent}
}

1
2
3
4
5
6

/*
 *  给parent ctx新建一个子节点（带超时, 类型cancleCtx）
 * @param [in] deadline   过期时间点
 * @return  ctx: 新子节点  cacle: 取消函数
 */
func WithDeadline(parent Context, deadline time.Time) (Context, CancelFunc)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

package main

import (
	"context"
	"fmt"
	"time"
)

func main() {
	// 创建son ctx, 到期时间设置为50ms
	ctx, cancel := context.WithDeadline(context.Background(), time.Now().Add(50 * time.Millisecond))

	//即使ctx将过期，在任何情况下调用它的cancel函数都是一个好习惯。
	//如果不这样做，可能会使ctx及其父节点存活的时间超过必要时间。
	defer cancel()

	select {
	case <-time.After(100 * time.Millisecond):  // parent ctx, 到期时间为100ms
		fmt.Printf("parent ctx is finish: overslept\n")
	case <-ctx.Done():  // son ctx先到期(50ms), 到期后会向ctx.Done()写入数据 ==> 因此执行下面的语句
		fmt.Printf("son ctx is finish, err:%s\n", ctx.Err())
	}
}

1
2
3
4
5
6
7

/*
 *  给parent ctx新建一个子节点（带超时, 类型cancleCtx）
 * @param [in] deadline  接收一个相对当前时间的过期时长timeout
 *	  等待于 WithDeadline(parent, time.Now().Add(timeout))
 * @return  ctx: 新子节点  cacle: 取消函数
 */
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// 为parent创建新的子ctx，该ctx携带<key,val>键值对信息
func WithValue(parent Context, key, val interface{}) Context {
	if parent == nil { // 断言：parent不为nil
		panic("cannot create context from nil parent")
	}
	if key == nil {    // 断言：key不为nil
		panic("nil key")
	}
	if !reflectlite.TypeOf(key).Comparable() { // 断言：key可比较
		panic("key is not comparable")
	}
    // 以parent为父亲，创建新的子节点valueCtx，包含<key,val>
	return &valueCtx{parent, key, val}
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

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

var (
	background = new(emptyCtx)
	todo       = new(emptyCtx)
)

// Background returns a non-nil, empty Context. It is never canceled, has no
// values, and has no deadline. It is typically used by the main function,
// initialization, and tests, and as the top-level Context for incoming
// requests.
func Background() Context {
	return background
}

// TODO returns a non-nil, empty Context. Code should use context.TODO when
// it's unclear which Context to use or it is not yet available (because the
// surrounding function has not yet been extended to accept a Context
// parameter).
func TODO() Context {
	return todo
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

type cancelCtx struct {
    Context   // 继承了Context接口，表示valueCtx所属的父节点
    mu       sync.Mutex            // 保护下面的字段
    done     atomic.Value          // of chan struct{}, created lazily, closed by first cancel call, chan(用来传递关闭信号): 惰性创建
    children map[canceler]struct{} // 存储当前ctx节点下所有的子节点
    err      error                 // 存储错误信息，表示人物结束的原因
}

// cancleer接口
type canceler interface {
    cancel(removeFromParent bool, err error)
    Done() <-chan struct{}
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// 创建done通道, 用于通信
func (c *cancelCtx) Done() <-chan struct{} {
    c.mu.Lock()
    // 如果c.done不存在, 就创建一个 
    if c.done == nil {  
        c.done = make(chan struct{})
    }
    d := c.done // 保存到变量d
    c.mu.Unlock()
    return d    // 返回d
}

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

    if c.done == nil { // 设置一个关闭的channel
        c.done = closedchan
    } else {  // 将c.done通道关闭，用以发送关闭信号
        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 {
        removeChild(c.Context, c) // 将当前context节点从父节点上移除
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

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

	deadline time.Time
}

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

type valueCtx struct {
    Context  // 继承了Context接口，表示valueCtx所属的父节点
    key, val interface{}  // 携带key-value键值对，同来保存额外信息
}
// 实现了Value方法：用来在context链上(直到根节点)，寻找key对应的value
func (c *valueCtx) Value(key interface{}) interface{} {
    if c.key == key { /* 当前c上找到, 就返回val */
        return c.val
    }
    /* 在c所属的父节点c.Context上继续调用Value, 查找key对应的val */
    return c.Context.Value(key) 
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

// src/context/context.go 
// propagateCancel arranges for child to be canceled when parent is.
func propagateCancel(parent Context, child canceler) {
	// 当父级上下文（parent）的 Done 结果为 nil 时，将会直接返回，
	// 因为其不会具备取消事件的基本条件，可能该 context 是 Background、TODO 等方法产生的空白 context。
	done := parent.Done()
	if done == nil {
		return // parent is never canceled
	}

	// 当父级上下文（parent）的 Done 结果不为 nil 时，继续往下走
	select {
	case <-done:  // 发现父级上下文已经被取消，作为其子级，该 context 将会触发取消事件并返回父级上下文的取消原因。
		// parent is already canceled
		child.cancel(false, parent.Err(), Cause(parent))
		return
	default:
	}

	// 父级 context 未触发取消事件，当前父级和子级 context 均正常（未取消），继续往下走
	// 调用 parentCancelCtx 方法找到具备取消功能的父级 context。
	// 并将当前 context，也就是 child 加入到 父级 context 的 children 列表中，
	// 等待后续父级 context 的取消事件通知和响应。
	if p, ok := parentCancelCtx(parent); ok { 
		p.mu.Lock()
		if p.err != nil {
			// parent has already been canceled
			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()
	} else {
		// 如果调用 parentCancelCtx 方法没有找到具备取消功能的父级 context，
		// 将会启动一个新的 goroutine 去监听父子 context 的取消事件通知。
		goroutines.Add(1)
		go func() {
			select {
			case <-parent.Done():
				child.cancel(false, parent.Err(), Cause(parent))
			case <-child.Done():
			}
		}()
	}
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

package main

import (
	"context"
	"fmt"
)

func func1(ctx context.Context) {
	// WithValue创建：携带(k1,v1)的子节点ctx
	ctx = context.WithValue(ctx, "k1", "v1")
	// 获取ctx的key="k1"对应的val值
	func2(ctx)
}

func func2(ctx context.Context) {
    // Value获取
	fmt.Println(ctx.Value("k1").(string))
}

func main() {
	ctx := context.Background()
	func1(ctx)
}
// 执行结果: v1