context

1
2
3

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

1

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

1

var DeadlineExceeded error = deadlineExceededError{}

1

func AfterFunc(ctx Context, f func()) (stop func() bool)

 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

package main

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

func main() {
	waitOnCond := func(ctx context.Context, cond *sync.Cond, conditionMet func() bool) error {
		stopf := context.AfterFunc(ctx, func() {
			// We need to acquire cond.L here to be sure that the Broadcast
			// below won't occur before the call to Wait, which would result
			// in a missed signal (and deadlock).
            // 我们需要在这里获取 cond.L，以确保在调用 Wait 之前不会发生下面的 Broadcast，
			// 其将导致信号丢失（和死锁）。
			cond.L.Lock()
			defer cond.L.Unlock()
            
			// If multiple goroutines are waiting on cond simultaneously,
			// we need to make sure we wake up exactly this one.
			// That means that we need to Broadcast to all of the goroutines,
			// which will wake them all up.
            // 如果多个 goroutine 同时在 cond 上等待，
			// 我们需要确保我们只唤醒这一个。
			// 这意味着我们需要 Broadcast 到所有 goroutine，
			// 这将唤醒它们所有。
			//            
			// If there are N concurrent calls to waitOnCond, each of the goroutines
			// will spuriously wake up O(N) other goroutines that aren't ready yet,
			// so this will cause the overall CPU cost to be O(N²).
            // 如果有 N 个并发的 waitOnCond 调用，每个 goroutine
			// 都会让 O(N) 其他尚未准备好的 goroutine 被虚假唤醒，
			// 所以这将导致总体 CPU 成本为 O(N²)。
			cond.Broadcast()
		})
		defer stopf()

		// Since the wakeups are using Broadcast instead of Signal, this call to
		// Wait may unblock due to some other goroutine's context becoming done,
		// so to be sure that ctx is actually done we need to check it in a loop.
        // 由于唤醒使用的是 Broadcast 而不是 Signal，所以调用 Wait 可能由于其他 goroutine 的上下文完成而取消，
		// 因此为了确保 ctx 实际上已完成，我们需要在循环中检查它。
		for !conditionMet() {
			cond.Wait()
			if ctx.Err() != nil {
				return ctx.Err()
			}
		}

		return nil
	}

	cond := sync.NewCond(new(sync.Mutex))

	var wg sync.WaitGroup
	for i := 0; i < 4; i++ {
		wg.Add(1)
		go func() {
			defer wg.Done()

			ctx, cancel := context.WithTimeout(context.Background(), 1*time.Millisecond)
			defer cancel()

			cond.L.Lock()
			defer cond.L.Unlock()

			err := waitOnCond(ctx, cond, func() bool { return false })
			fmt.Println(err)
		}()
	}
	wg.Wait()

}
Output:

context deadline exceeded
context deadline exceeded
context deadline exceeded
context deadline exceeded

 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

package main

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

func main() {
	readFromConn := func(ctx context.Context, conn net.Conn, b []byte) (n int, err error) {
		stopc := make(chan struct{})
		stop := context.AfterFunc(ctx, func() {
			conn.SetReadDeadline(time.Now())
			close(stopc)
		})
		n, err = conn.Read(b)
		if !stop() {
			// The AfterFunc was started.
			// Wait for it to complete, and reset the Conn's deadline.
            // AfterFunc已经启动。
			// 等待它完成，并重置Conn的截止时间。
			<-stopc
			conn.SetReadDeadline(time.Time{})
			return n, ctx.Err()
		}
		return n, err
	}

	listener, err := net.Listen("tcp", ":0")
	if err != nil {
		fmt.Println(err)
		return
	}
	defer listener.Close()

	conn, err := net.Dial(listener.Addr().Network(), listener.Addr().String())
	if err != nil {
		fmt.Println(err)
		return
	}
	defer conn.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Millisecond)
	defer cancel()

	b := make([]byte, 1024)
	_, err = readFromConn(ctx, conn, b)
	fmt.Println(err)

}
Output:

context deadline exceeded

 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

package main

import (
	"context"
	"errors"
	"fmt"
)

func main() {
	// mergeCancel returns a context that contains the values of ctx,
	// and which is canceled when either ctx or cancelCtx is canceled.
    // mergeCancel 返回一个包含ctx值的上下文，当ctx或cancelCtx被取消时，该上下文也将被取消。
	mergeCancel := func(ctx, cancelCtx context.Context) (context.Context, context.CancelFunc) {
		ctx, cancel := context.WithCancelCause(ctx)
		stop := context.AfterFunc(cancelCtx, func() {
			cancel(context.Cause(cancelCtx))
		})
		return ctx, func() {
			stop()
			cancel(context.Canceled)
		}
	}

	ctx1, cancel1 := context.WithCancelCause(context.Background())
	defer cancel1(errors.New("ctx1 canceled"))

	ctx2, cancel2 := context.WithCancelCause(context.Background())

	mergedCtx, mergedCancel := mergeCancel(ctx1, ctx2)
	defer mergedCancel()

	cancel2(errors.New("ctx2 canceled"))
	<-mergedCtx.Done()
	fmt.Println(context.Cause(mergedCtx))

}

1

func Cause(c Context) error

1

func WithCancel(parent Context) (ctx Context, cancel CancelFunc)

 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

package main

import (
	"context"
	"fmt"
)

func main() {
    // gen generates integers in a separate goroutine and
	// sends them to the returned channel.
	// The callers of gen need to cancel the context once
	// they are done consuming generated integers not to leak
	// the internal goroutine started by gen.
    // gen在一个单独的goroutine中生成整数，并将它们发送到返回的通道中。
	// gen的调用者在消耗完生成的整数后需要取消上下文，以免泄露gen启动的内部goroutine。
	gen := func(ctx context.Context) <-chan int {
		dst := make(chan int)
		n := 1
		go func() {
			for {
				select {
				case <-ctx.Done():
					return // 返回时不泄露goroutine的信息 cancel when we are finished consuming integers
				case dst <- n:
					n++
				}
			}
		}()
		return dst
	}

	ctx, cancel := context.WithCancel(context.Background())
	defer cancel() // 当我们消耗完整数后再取消。

	for n := range gen(ctx) {
		fmt.Println(n)
		if n == 5 {
			break
		}
	}
}
Output:

1
2
3
4
5

1

func WithCancelCause(parent Context) (ctx Context, cancel CancelCauseFunc)

1
2
3
4

ctx, cancel := context.WithCancelCause(parent)
cancel(myError)
ctx.Err() // returns context.Canceled
context.Cause(ctx) // returns myError

1

func WithDeadline(parent Context, d 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
24
25
26
27
28
29
30
31
32
33

package main

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

const shortDuration = 1 * time.Millisecond

func main() {
	d := time.Now().Add(shortDuration)
	ctx, cancel := context.WithDeadline(context.Background(), d)

    // Even though ctx will be expired, it is good practice to call its
	// cancellation function in any case. Failure to do so may keep the
	// context and its parent alive longer than necessary.
	// 尽管ctx会过期，但在任何情况下调用其取消函数都是很好的做法。
    // 如果不这样做，可能会使上下文和它的parent活得比必要的时间更长。
	defer cancel()

	select {
	case <-time.After(1 * time.Second):
		fmt.Println("overslept")
	case <-ctx.Done():
		fmt.Println(ctx.Err())
	}

}

Output:

context deadline exceeded

1

func WithDeadlineCause(parent Context, d time.Time, cause error) (Context, CancelFunc)

1

func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)

1
2
3
4
5

func slowOperationWithTimeout(ctx context.Context) (Result, error) {
	ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)
	defer cancel()  // 如果slowOperation在超时前完成，则释放资源 releases resources if slowOperation completes before timeout elapses
	return slowOperation(ctx)
}

 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

package main

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

const shortDuration = 1 * time.Millisecond

func main() {
    // Pass a context with a timeout to tell a blocking function that it
	// should abandon its work after the timeout elapses.
    //传递一个带有超时的上下文，以告诉阻塞函数在超时过后应该放弃它的工作
	ctx, cancel := context.WithTimeout(context.Background(), shortDuration)
	defer cancel()

	select {
	case <-time.After(1 * time.Second):
		fmt.Println("overslept")
	case <-ctx.Done():
		fmt.Println(ctx.Err()) // prints "context deadline exceeded"
	}

}

Output:

context deadline exceeded

1

func WithTimeoutCause(parent Context, timeout time.Duration, cause error) (Context, CancelFunc)

1

type CancelCauseFunc func(cause error)

1

type CancelFunc func()

  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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

type Context interface {
    // Deadline returns the time when work done on behalf of this context
	// should be canceled. Deadline returns ok==false when no deadline is
	// set. Successive calls to Deadline return the same results.
    // Deadline返回代表该上下文所做的工作应该被取消的时间。
    // 如果没有设置deadline，Deadline方法返回ok==false。
    // 对Deadline的连续调用会返回相同的结果。
	Deadline() (deadline time.Time, ok bool)

    // Done returns a channel that's closed when work done on behalf of this
	// context should be canceled. Done may return nil if this context can
	// never be canceled. Successive calls to Done return the same value.
	// The close of the Done channel may happen asynchronously,
	// after the cancel function returns.
    // Done返回一个通道，该通道在此上下文代表的工作应被取消时关闭。
    // 如果这个上下文永远不能被取消，则Done可能会返回nil。
    // 对Done的连续调用会返回相同的值。
    // Done通道的关闭可以异步发生，在cancel函数返回之后。
	//
    // WithCancel arranges for Done to be closed when cancel is called;
	// WithDeadline arranges for Done to be closed when the deadline
	// expires; WithTimeout arranges for Done to be closed when the timeout
	// elapses.
	// WithCancel安排在调用cancel时关闭Done；
	// WithDeadline安排在截止时间过期时关闭Done；
	// WithTimeout安排在超时时间过去时关闭Done。
	//
    // Done is provided for use in select statements:
    // Done用于在select语句中使用：
	//
    //  // Stream generates values with DoSomething and sends them to out
	//  // until DoSomething returns an error or ctx.Done is closed.
	//	// Stream用DoSomething生成数值，并将其发送到out，
    //  // 直到DoSomething返回错误或ctx.Done被关闭。
	//  func Stream(ctx context.Context, out chan<- Value) error {
	//  	for {
	//  		v, err := DoSomething(ctx)
	//  		if err != nil {
	//  			return err
	//  		}
	//  		select {
	//  		case <-ctx.Done():
	//  			return ctx.Err()
	//  		case out <- v:
	//  		}
	//  	}
	//  }
	//
    // See https://blog.golang.org/pipelines for more examples of how to use
	// a Done channel for cancellation.
    // 参见https://blog.golang.org/pipelines，
    // (2014年的博客：Go Concurrency Patterns: Pipelines and cancellation)
    // 以了解更多关于如何使用Done通道取消的例子。
	Done() <-chan struct{}

    // If Done is not yet closed, Err returns nil.
	// If Done is closed, Err returns a non-nil error explaining why:
	// Canceled if the context was canceled
	// or DeadlineExceeded if the context's deadline passed.
	// After Err returns a non-nil error, successive calls to Err return the same error.
    // 如果Done尚未关闭，则Err返回nil。
	// 如果Done已关闭，则Err返回一个非nil错误，解释原因：
	// 如果上下文被取消，则为Canceled；
	// 如果上下文的截止时间过去，则为DeadlineExceeded。
	// 在Err返回非nil错误之后，连续调用Err将返回相同的错误。
	Err() error

    // Value returns the value associated with this context for key, or nil
	// if no value is associated with key. Successive calls to Value with
	// the same key returns the same result.
    // Value返回与此上下文相关的key的值，
    // 如果没有与key相关的值，则返回nil。
    // 用相同的key连续调用Value会返回相同的结果。
	//
    // Use context values only for request-scoped data that transits
	// processes and API boundaries, not for passing optional parameters to
	// functions.
	// 只有在请求范围内的数据穿越进程和API时才使用上下文值，
    // 而不是将可选参数传递给函数。
	//
    // A key identifies a specific value in a Context. Functions that wish
	// to store values in Context typically allocate a key in a global
	// variable then use that key as the argument to context.WithValue and
	// Context.Value. A key can be any type that supports equality;
	// packages should define keys as an unexported type to avoid
	// collisions.
    // key 标识了一个上下文中的特定值。
    // 希望在Context中存储值的函数通常会在一个全局变量中分配一个key，
    // 然后使用该key作为context.WithValue和Context.Value的实参。
    // key可以是任何支持可比较的类型。
	// 包应该将key定义为一个不可导出的类型，以避免冲突。
	//
    // Packages that define a Context key should provide type-safe accessors
	// for the values stored using that key:
	// 定义Context的key的包应该为使用该key存储的值提供类型安全的访问器：
	//	
    // // Package user defines a User type that's stored in Contexts.
	// // user包定义了一个存储在Contexts中的User类型。
	// 	package user
	//
	// 	import "context"
	//
    // 	// key is an unexported type for keys defined in this package.
	// 	// This prevents collisions with keys defined in other packages.
    // // User is the type of value stored in the Contexts.
	// // User是存储在Contexts中的值的类型。
	// 	type User struct {...}
	//
    // 	// userKey is the key for user.User values in Contexts. It is
	// 	// unexported; clients use user.NewContext and user.FromContext
	// 	// instead of using this key directly.
	//	// key是本包中定义的键的不可导出类型。
	//  //这可以防止与其他包中定义的键发生冲突。
	// 	type key int
	//
	//	// userKey是Contexts中user.User值的key。
    //  // 它是未被导出的；客户端使用user.NewContext和user.FromContext而不是直接使用这个key。
	// 	var userKey key
	//
	//	// NewContext返回一个新的带有u值的Context。
	// 	func NewContext(ctx context.Context, u *User) context.Context {
	// 		return context.WithValue(ctx, userKey, u)
	// 	}
	//
    // 	// FromContext returns the User value stored in ctx, if any.
	//	// FromContext返回存储在ctx中的User值(如果有的话)。
	// 	func FromContext(ctx context.Context) (*User, bool) {
	// 		u, ok := ctx.Value(userKey).(*User)
	// 		return u, ok
	// 	}
	Value(key any) any
}

1

func Background() Context

1

func TODO() Context

1

func WithValue(parent Context, key, val any) 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
27
28
29

package main

import (
	"context"
	"fmt"
)

func main() {
	type favContextKey string

	f := func(ctx context.Context, k favContextKey) {
		if v := ctx.Value(k); v != nil {
			fmt.Println("found value:", v)
			return
		}
		fmt.Println("key not found:", k)
	}

	k := favContextKey("language")
	ctx := context.WithValue(context.Background(), k, "Go")

	f(ctx, k)
	f(ctx, favContextKey("color"))

}
Output:

found value: Go
key not found: color

1

func WithoutCancel(parent Context) Context