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

package main

import (
	"context"
	"fmt"
)

func main() {
    // 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的信息
				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

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)

	// 尽管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 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在超时前完成，则释放资源
	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

package main

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

const shortDuration = 1 * time.Millisecond

func main() {
    //传递一个带有超时的上下文，以告诉阻塞函数在超时过后应该放弃它的工作
	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

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

type Context interface {
    // Deadline返回代表该上下文所做的工作应该被取消的时间。
    // 如果没有设置deadline，Deadline方法返回ok==false。
    // 对Deadline的连续调用会返回相同的结果。
	Deadline() (deadline time.Time, ok bool)

    // Done返回一个通道，该通道在此上下文代表的工作应被取消时关闭。
    // 如果这个上下文永远不能被取消，则Done可能会返回nil。
    // 对Done的连续调用会返回相同的值。
    // Done通道的关闭可以异步发生，在cancel函数返回之后。
	//
	// WithCancel安排在调用cancel时关闭Done；
	// WithDeadline安排在截止时间过期时关闭Done；
	// WithTimeout安排在超时时间过去时关闭Done。
	//
    // Done用于在select语句中使用：
	//
	//	// 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:
	//  		}
	//  	}
	//  }
	//
    // 参见https://blog.golang.org/pipelines，
    // (2014年的博客：Go Concurrency Patterns: Pipelines and cancellation)
    // 以了解更多关于如何使用Done通道取消的例子。
	Done() <-chan struct{}

    // 如果Done尚未关闭，则Err返回nil。
	// 如果Done已关闭，则Err返回一个非nil错误，解释原因：
// 如果上下文被取消，则为Canceled；
// 如果上下文的截止时间过去，则为DeadlineExceeded。
// 在Err返回非nil错误之后，连续调用Err将返回相同的错误。
	Err() error

    // Value返回与此上下文相关的key的值，
    // 如果没有与key相关的值，则返回nil。
    // 用相同的key连续调用Value会返回相同的结果。
	//
	// 只有在请求范围内的数据穿越进程和API时才使用上下文值，
    // 而不是将可选参数传递给函数。
	//
    // key 标识了一个上下文中的特定值。
    // 希望在Context中存储值的函数通常会在一个全局变量中分配一个key，
    // 然后使用该key作为context.WithValue和Context.Value的实参。
    // key可以是任何支持可比较的类型。
	// 包应该将key定义为一个不可导出的类型，以避免冲突。
	//
	// 定义Context的key的包应该为使用该key存储的值提供类型安全的访问器：
	//	
	// // user包定义了一个存储在Contexts中的User类型。
	// 	package user
	//
	// 	import "context"
	//
	// // User是存储在Contexts中的值的类型。
	// 	type User struct {...}
	//
	//	// 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返回存储在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