原文链接: Go 语言 context 都能做什么?
很多 Go 项目的源码,在读的过程中会发现一个很常见的参数 ctx
,而且基本都是作为函数的第一个参数。
为什么要这么写呢?这个参数到底有什么用呢?带着这样的疑问,我研究了这个参数背后的故事。
开局一张图:
核心是 Context
接口:
// A Context carries a deadline, cancelation signal, and request-scoped values
// across API boundaries. Its methods are safe for simultaneous use by multiple
// goroutines.
type Context interface {
// Done returns a channel that is closed when this Context is canceled
// or times out.
Done() <-chan struct{}
// Err indicates why this context was canceled, after the Done channel
// is closed.
Err() error
// Deadline returns the time when this Context will be canceled, if any.
Deadline() (deadline time.Time, ok bool)
// Value returns the value associated with key or nil if none.
Value(key interface{}) interface{}
}
包含四个方法:
Done()
:返回一个 channel,当 times out 或者调用 cancel 方法时。Err()
:返回一个错误,表示取消 ctx 的原因。Deadline()
:返回截止时间和一个 bool 值。Value()
:返回 key 对应的值。
有四个结构体实现了这个接口,分别是:emptyCtx
, cancelCtx
, timerCtx
和 valueCtx
。
其中 emptyCtx
是空类型,暴露了两个方法:
func Background() Context
func TODO() Context
一般情况下,会使用 Background()
作为根 ctx,然后在其基础上再派生出子 ctx。要是不确定使用哪个 ctx,就使用 TODO()
。
另外三个也分别暴露了对应的方法:
func WithCancel(parent Context) (ctx Context, cancel CancelFunc)
func WithDeadline(parent Context, deadline time.Time) (Context, CancelFunc)
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)
func WithValue(parent Context, key, val interface{}) Context
遵循规则
在使用 Context 时,要遵循以下四点规则:
- 不要将 Context 放入结构体,而是应该作为第一个参数传入,命名为
ctx
。 - 即使函数允许,也不要传入
nil
的 Context。如果不知道用哪种 Context,可以使用context.TODO()
。 - 使用 Context 的 Value 相关方法只应该用于在程序和接口中传递和请求相关的元数据,不要用它来传递一些可选的参数。
- 相同的 Context 可以传递给不同的 goroutine;Context 是并发安全的。
WithCancel
func WithCancel(parent Context) (ctx Context, cancel CancelFunc)
WithCancel
返回带有新 Done
通道的父级副本。当调用返回的 cancel
函数或关闭父上下文的 Done
通道时,返回的 ctx
的 Done
通道将关闭。
取消此上下文会释放与其关联的资源,因此在此上下文中运行的操作完成后,代码应立即调用 cancel
。
举个例子:
这段代码演示了如何使用可取消上下文来防止 goroutine 泄漏。在函数结束时,由 gen
启动的 goroutine 将返回而不会泄漏。
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 := 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
}
}
}
输出:
1
2
3
4
5
WithDeadline
func WithDeadline(parent Context, d time.Time) (Context, CancelFunc)
WithDeadline
返回父上下文的副本,并将截止日期调整为不晚于 d
。如果父级的截止日期已经早于 d
,则 WithDeadline(parent, d)
在语义上等同于 parent
。
当截止时间到期、调用返回的取消函数时或当父上下文的 Done
通道关闭时,返回的上下文的 Done
通道将关闭。
取消此上下文会释放与其关联的资源,因此在此上下文中运行的操作完成后,代码应立即调用取消。
举个例子:
这段代码传递具有截止时间的上下文,来告诉阻塞函数,它应该在到达截止时间时立刻退出。
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