Golang Context Source Code Analysis

 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
50

// 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 interface{}) interface{} {
	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
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
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

// A cancelCtx can be canceled. When canceled, it also cancels any children
// that implement canceler.
type cancelCtx struct {
	Context

	mu       sync.Mutex            // protects following fields
	done     chan struct{}         // created lazily, closed by first cancel call
	children map[canceler]struct{} // set to nil by the first cancel call
	err      error                 // set to non-nil by the first cancel call
}

func (c *cancelCtx) Value(key interface{}) interface{} {
	if key == &cancelCtxKey {
		return c
	}
	return c.Context.Value(key)
}

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
}

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 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
	if c.done == nil {
		c.done = closedchan
	} else {
		close(c.done)
	}
	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)
	}
}

 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

// 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) 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 {
		// 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
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// 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 interface{}
}

// stringify tries a bit to stringify v, without using fmt, since we don't
// want context depending on the unicode tables. This is only used by
// *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) + ")"
}

func (c *valueCtx) Value(key interface{}) interface{} {
	if c.key == key {
		return c.val
	}
	return c.Context.Value(key)
}

1
2
3
4
5
6
7
8

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

  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
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103

// propagateCancel This method is responsible for ensuring that when the parent Context is cancelled, the child Context will also be cancelled in conjunction
func propagateCancel(parent Context, child canceler) {
	// 针For Context(emptyCtx) created by context.Background()/TODO(), its done channel will always be nil
	// For other standard cancelable Contexts (cancelCtx, timerCtx) calling the Done() method will delay the initialization of the done channel (created when called)
	// So a done channel of nil means that the parent context must never be cancelled, so there is no need to link to the child Context
	done := parent.Done()
	if done == nil {
		return // parent is never canceled
	}

	// If the done channel is not nil, the parent Context is a Context that can be cancelled
	// Here you need to immediately determine whether the done channel can be read, if it can be read, it means that the above lock-free phase
	// parent Context has been cancelled, then the child Context should be cancelled immediately
	select {
	case <-done:
		// parent is already canceled
		child.cancel(false, parent.Err())
		return
	default:
	}

	// parentCancelCtx is used to get the underlying cancelable Context of the parent Context(cancelCtx)
	//
	// Returns true if the parent Context is itself *cancelCtx or a Context derived from cancelCtx in the standard library
	// Returns false if the parent Context has been cancelled / or cannot be cancelled at all
	// If the parent Context cannot be converted to a *cancelCtx it will also return false
	// If the parent Context is a custom deep wrapped cancelCtx (with its own defined done channel) then it will also return false
	if p, ok := parentCancelCtx(parent); ok { // ok is true means that the parent Context is a standard library cancelCtx or at least can be fully converted to *cancelCtx
		// Lock the parent Context first to prevent changes
		p.mu.Lock()
		// Because ok is true, it has been determined that the parent Context must be *cancelCtx, and cancelCtx must set err when canceling
		// So if the err of the parent Context is not empty in the case of concurrent locking, it has been cancelled
		if p.err != nil {
			// parent has already been canceled
			child.cancel(false, p.err)
		} else {
			// When ok is true, the parent Context must be *cancelCtx, and err is nil
			// This means that the parent Context has not been cancelled yet, so you have to associate the child Context with the children map of the parent Context
			// This children map will be traversed when the parent Context is cancelled and the child Context's cancel method will be called in bulk
			if p.children == nil {
				p.children = make(map[canceler]struct{})
			}
			p.children[child] = struct{}{}
		}
		p.mu.Unlock()
	} else { // ok is false, means: "parent Context has been cancelled" or "Cannot be cancelled at all" or "Cannot be converted to a *cancelCtx" or "Is a custom deep wrapped cancelCtx"
		atomic.AddInt32(&goroutines, +1)
		// Since the code determines at the beginning of the method that the parent Context is "cancelled" or "cannot be cancelled at all"
		// So these two cases do not happen here, so <-parent.Done() does not generate panic
		// 
		// The only remaining possibility is that the parent Context "cannot be converted to a *cancelCtx" or "is a custom cancelCtx that is overwritten with a done channel"
		// In both cases, the association cannot be established through the children map of the parent Context, and can only be done by creating a Goroutine and unlinking it.
		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.)
func parentCancelCtx(parent Context) (*cancelCtx, bool) {
	// If the done of the parent context is nil, which means cancel is not supported, then it can't be cancelCtx
	// If `done` of `parent context` is a reusable `closedchan` it means that `parent context` has `canceled`
	// At this point to take out the cancelCtx does not make sense (the specific why no sense will be analyzed later in the chapter))
	done := parent.Done()
	if done == closedchan || done == nil {
		return nil, false
	}

	// If the parent context belongs to the native *cancelCtx or a derived type (timerCtx), you need to continue with the subsequent determination
	// If the parent context cannot be converted to *cancelCtx, it is considered non-cancelCtx and returns nil,fasle
	p, ok := parent.Value(&cancelCtxKey).(*cancelCtx)
	if !ok {
		return nil, false
	}
	p.mu.Lock()
	// After the above determination, the parent context can be converted to *cancelCtx, and there are several cases:
	//   - parent context is `*cancelCtx`
	//   - parent context is timerCtx from the standard library
	//   - parent context is a custom wrapped cancelCtx
	//
	// For these 3 cases need to be judged, the judgment method is: 
	//   Determine whether the done channel obtained by the parent context through the Done() method is the same as the done channel of the context found by Value
	// 
	// Consistency means that the parent context is a cancelCtx or timerCtx or a custom cancelCtx and Done() is not overridden.
	// In this case it can be assumed that the underlying *cancelCtx is obtained
	// 
	// The inconsistency means that the parent context is a custom cancelCtx that overrides the Done() method and does not return the done channel of the standard *cancelCtx, which needs to be handled separately and therefore returns nil, false
	ok = p.done == done
	p.mu.Unlock()
	if !ok {
		return nil, false
	}
	return p, 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

// 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) {
    // First determine whether err is nil, if not nil then directly panic
    // The reason for this is that the cancel method is a private method, and any call to cancel in the standard library is guaranteed to pass in err, so if it doesn't, it's an abnormal call, so you can just panic
	if err == nil {
		panic("context: internal error: missing cancel error")
	}
	// Lock on context to prevent concurrent changes
	c.mu.Lock()
	// If there are concurrent accesses after locking, then a second judgment err can prevent repeated cancel calls
	if c.err != nil {
		c.mu.Unlock()
		return // already canceled
	}
	// The internal err is set here, so the above judgment c.err ! = nil corresponds to this
	// That is, after locking there must be a Goroutine cannel first, after cannel c.err must not be nil
	c.err = err
	// Determine whether the internal done channel is nil or not, because the done channel was not initialized immediately when context.WithCancel created the cancelCtx (delayed initialization), so it may be nil here
	// If the done channel is nil, then set it to a shared reusable channel that has already been closed
	if c.done == nil {
		c.done = closedchan
	} else { // If the done channel has already been initialized, close it directly
		close(c.done)
	}
	// If there are associated child Contexts below the current Context, and these child Contexts are all Contexts that can be converted to *cancelCtx (see the propagateCancel method analysis above), then
	// Iterate over the childre map directly and call cancel on the child Context
	// If the associated child Context cannot be converted to *cancelCtx, then a separate Goroutine has been created in the propagateCancel method to close these child Contexts
	for child := range c.children {
		// NOTE: acquiring the child's lock while holding parent's lock.
		child.cancel(false, err)
	}
	// Clear the c.children map and unlock it
	c.children = nil
	c.mu.Unlock()

    // If removeFromParent is true, then clear yourself from the parent Context
	if removeFromParent {
		removeChild(c.Context, c)
	}
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

func parentCancelCtx(parent Context) (*cancelCtx, bool) {
	// If the done of the parent context is nil, which means cancel is not supported, then it can't be cancelCtx
	// If `done` of `parent context` is a reusable `closedchan` it means that `parent context` has `canceled`
	// At this point to take out `cancelCtx` does not make sense (the specific why no sense later chapter will have analysis)
	done := parent.Done()
	if done == closedchan || done == nil {
		return nil, false
	}
	
	// ...... Abbreviation
}

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

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{})
        }
        p.children[child] = struct{}{}
    }
    p.mu.Unlock()
} else {
    atomic.AddInt32(&goroutines, +1)
    go func() {
        select {
        case <-parent.Done():
            child.cancel(false, parent.Err())
        case <-child.Done():
        }
    }()
}

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

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

 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

// WithDeadline returns a copy of the parent context with the deadline adjusted
// to be no later than d. If the parent's deadline is already earlier than d,
// WithDeadline(parent, d) is semantically equivalent to parent. The returned
// context's Done channel is closed when the deadline expires, when the returned
// cancel function is called, or when the parent context's Done channel is
// closed, whichever happens first.
//
// Canceling this context releases resources associated with it, so code should
// call cancel as soon as the operations running in this Context complete.
func WithDeadline(parent Context, d time.Time) (Context, CancelFunc) {
    // As with cancelCtx, first check the parent Context
	if parent == nil {
		panic("cannot create context from nil parent")
	}
    
    // Determine whether the parent Context supports Deadline, if so, you need to determine the cutoff time of the parent Context
    // Assuming that the expiration time of the parent Context is earlier than the currently set expiration time, it means that the parent Context will definitely be cancelled first, and the current child Context will also be cancelled due to the parent Context's cancellation
    // So this time directly return a cancelCtx on the line, the timer has no need to exist
	if cur, ok := parent.Deadline(); ok && cur.Before(d) {
		// The current deadline is already sooner than the new one.
		return WithCancel(parent)
	}

    // Create a timerCtx
	c := &timerCtx{
		cancelCtx: newCancelCtx(parent),
		deadline:  d,
	}

    // The same propagation operation as cancelCtx
	propagateCancel(parent, c)

    // Determine if the current time has passed the deadline, if it exceeds the deadline directly cancel
	dur := time.Until(d)
	if dur <= 0 {
		c.cancel(true, DeadlineExceeded) // deadline has already passed
		return c, func() { c.cancel(false, Canceled) }
	}

    // If all checks are OK, create a timer that will automatically cancel when the time is up
	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) }
}

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

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

 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
50
51
52
53
54
55
56
57
58
59
60
61
62
63

// WithValue returns a copy of parent in which the value associated with key is
// val.
//
// Use context Values only for request-scoped data that transits processes and
// APIs, not for passing optional parameters to functions.
//
// The provided key must be comparable and should not be of type
// string or any other built-in type to avoid collisions between
// packages using context. Users of WithValue should define their own
// types for keys. To avoid allocating when assigning to an
// interface{}, context keys often have concrete type
// struct{}. Alternatively, exported context key variables' static
// type should be a pointer or interface.
func WithValue(parent Context, key, val interface{}) Context {
    // parent Detection
	if parent == nil {
		panic("cannot create context from nil parent")
	}
    // key Detection
	if key == nil {
		panic("nil key")
	}
    // key must be comparable
	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 interface{}
}

// stringify tries a bit to stringify v, without using fmt, since we don't
// want context depending on the unicode tables. This is only used by
// *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) + ")"
}

func (c *valueCtx) Value(key interface{}) interface{} {
    // First, determine whether the key is present in the current Context
	if c.key == key {
		return c.val
	}
    // If there is no recursive upward lookup
	return c.Context.Value(key)
}