context
context包定义了上下文类型，该类型在API边界之间以及进程之间传递截止日期，取消信号和其他请求范围的值。
对服务器的传入请求应创建一个Context，而对服务器的传出调用应接受一个Context。它们之间的函数调用链必须传播Context，可以选择将其替换为使用WithCancel，WithDeadline，WithTimeout或WithValue创建的派生Context。取消context后，从该Context派生的所有Context也会被取消。
WithCancel，WithDeadline和WithTimeout函数采用Context（父级）并返回派生的Context（子级）和CancelFunc。调用CancelFunc会取消该子代及其子代，删除父代对该子代的引用，并停止所有关联的计时器。未能调用CancelFunc会使子代及其子代泄漏，直到父代被取消或计时器触发。审核工具检查所有控制流路径上是否都使用了CancelFuncs。
使用Context的程序应遵循以下规则，以使各个包之间的接口保持一致，并启用静态分析工具来检查上下文传播：
- 不要将Context存储在结构类型中；
- 将Context明确传递给需要它的每个函数；
- Context应该是第一个参数，通常命名为ctx：
func DoSomething(ctx context.Context, arg Arg) error { // ... use ctx ... }
即使函数允许，也不要传递nil Context。如果不确定使用哪个上下文，请传递context.TODO。
仅将Context值用于传递流程和API的请求范围的数据，而不用于将可选参数传递给函数。
可以将相同的Context传递给在不同goroutine中运行的函数。Context对于由多个goroutine同时使用是安全的。
Variables
var Canceled = errors.New("context canceled")
var DeadlineExceeded error = deadlineExceededError{}
Canceled是Context.Err类型，取消Context时返回的错误。
DeadlineExceeded是上下文的最后期限过去时Context.Err返回的错误。
type CancelFunc
type CancelFunc func()
CancelFunc告诉操作停止工作。 CancelFunc不等待工作停止。 在第一个调用之后，随后对CancelFunc的调用什么都不做。
type Context
type Context interface {
Deadline() (deadline time.Time, ok bool)
Done() <-chan struct{}
Err() error
Value(key interface{}) interface{}
}
其中
Deadline方法需要返回当前Context被取消的时间，也就是完成工作的截止时间（deadline）；Done方法需要返回一个Channel，这个Channel会在当前工作完成或者上下文被取消之后关闭，多次调用Done方法会返回同一个Channel；Err方法会返回当前Context结束的原因，它只会在Done返回的Channel被关闭时才会返回非空的值；
- 如果当前
Context被取消就会返回Canceled错误；- 如果当前
Context超时就会返回DeadlineExceeded错误；Value方法会从Context中返回键对应的值，对于同一个上下文来说，多次调用Value并传入相同的Key会返回相同的结果，该方法仅用于传递跨API和进程间跟请求域的数据；
func Background
func Background() Context
Background返回一个非空的Context。 它永远不会被取消，没有值，也没有期限。 它通常由主要功能，初始化和测试使用，并用作传入请求的顶级Context。
func TODO
func TODO() Context
TODO返回一个非空的Context。 当不清楚要使用哪个上下文或尚不可用时（因为尚未扩展周围的功能以接受Context参数），代码应使用context.TODO。 静态分析工具可识别TODO，该工具可确定上下文是否在程序中正确传播。
func WithCancel
func WithCancel(parent Context) (ctx Context, cancel CancelFunc)
WithCancel返回具有新的“完成”通道的父级副本。 当调用返回的cancel函数或关闭父上下文的Done通道时（以先发生的为准），关闭返回的上下文的Done通道。
取消此上下文将释放与其关联的资源，因此在此上下文中运行的操作完成后，代码应立即调用cancel。
func main() { gen := func(ctx context.Context) <-chan int { dst := make(chan int) n := 1 go func() { for { select { case <-ctx.Done(): return // returning not to leak the goroutine case dst <- n: n++ } } }() return dst } ctx, cancel := context.WithCancel(context.Background()) defer cancel() // cancel when we are finished consuming integers for n := range gen(ctx) { fmt.Println(n) if n == 5 { break } } }
上面的示例代码中，gen函数在单独的goroutine中生成整数并将它们发送到返回的通道。 gen的调用者在使用生成的整数之后需要取消上下文，以免gen启动的内部goroutine发生泄漏。
func WithDeadline
func WithDeadline(parent Context, deadline time.Time) (Context, CancelFunc)
WithDeadline返回父上下文的副本，并将截止日期调整为不迟于d。 如果父母的截止日期早于d，则WithDeadline（parent，d）在语义上等同于父母。 当截止日期到期，调用返回的cancel函数或关闭父上下文的Done通道（以先到者为准）时，将关闭返回的上下文的Done通道。
取消此上下文将释放与其关联的资源，因此在此上下文中运行的操作完成后，代码应立即调用cancel。
func main() {
d := time.Now().Add(50 * time.Millisecond)
ctx, cancel := context.WithDeadline(context.Background(), d)
// Even though ctx will be expired, it is good practice to call its
// cancelation function in any case. Failure to do so may keep the
// context and its parent alive longer than necessary.
defer cancel()
select {
case <-time.After(1 * time.Second):
fmt.Println("overslept")
case <-ctx.Done():
fmt.Println(ctx.Err())
}
}
上面的代码中，定义了一个50毫秒之后过期的deadline，然后我们调用context.WithDeadline(context.Background(), d)得到一个上下文（ctx）和一个取消函数（cancel），然后使用一个select让主程序陷入等待：等待1秒后打印overslept退出或者等待ctx过期后退出。 因为ctx50毫秒后就过期，所以ctx.Done()会先接收到值，上面的代码会打印ctx.Err()取消原因。
func WithTimeout
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)
WithTimeout返回WithDeadline(parent, time.Now().Add(timeout))方法。
取消此Context 将释放与之关联的资源，因此在此Context 中运行的操作完成后，代码应立即调用cancel：
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
defer cancel()
select {
case <-time.After(1 * time.Second):
fmt.Println("overslept")
case <-ctx.Done():
fmt.Println(ctx.Err()) // prints "context deadline exceeded"
}
}
func WithValue
func WithValue(parent Context, key, val interface{}) Context
WithValue返回父项的副本，其中与key关联的值为val。
仅将Context值用于传递流程和API的请求范围的数据，而不用于将可选参数传递给函数。
提供的密钥必须具有可比性，并且不能为字符串类型或任何其他内置类型，以避免使用上下文在程序包之间发生冲突。 WithValue的用户应定义自己的密钥类型。 为了避免在分配给接口{}时进行分配，上下文键通常具有具体的类型struct {}。 另外，导出的上下文键变量的静态类型应该是指针或接口。
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"))
}
网友评论