Golang语言情怀-第54期 Go 语言标准库翻译 context

import "context"

包上下文定义了上下文类型，它携带跨越API边界和进程之间的最后期限、取消信号和其他请求范围的值。对服务器的传入请求应该创建上下文，对服务器的传出调用应该接受上下文。它们之间的函数调用链必须传播上下文，可以选择用使用WithCancel、WithDeadline、WithTimeout或WithValue创建的派生上下文替换它。当一个上下文被取消时，所有从它派生的上下文也被取消。WithCancel、WithDeadline和WithTimeout函数接受上下文(父类)，并返回派生的上下文(子类)和CancelFunc。调用CancelFunc会取消子进程及其子进程，删除父进程对子进程的引用，并停止任何相关的计时器。没有调用CancelFunc会泄露子进程及其子进程，直到父进程被取消或者定时器被触发。go vet工具检查取消函数是否在所有控制流路径上使用。使用上下文的程序应该遵循以下规则，以保持跨包的接口一致，并允许静态分析工具检查上下文传播:不要在结构类型中存储上下文;相反，将上下文显式地传递给每个需要它的函数。Context应该是第一个参数，通常命名为ctx:

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

不要传递nil上下文，即使函数允许这样做。通过上下文。如果您不确定使用哪个上下文，则使用TODO。上下文值仅用于传递流程和api的请求范围的数据，而不用于向函数传递可选参数。相同的上下文可以传递给运行在不同goroutines中的函数;上下文对于多个goroutines同时使用是安全的。有关使用上下文的服务器的示例代码，请参见https://blog.golang.org/context。

Variables
type CancelFunc
type Context
func Background() Context
func TODO() Context
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

Package Files

context.go

Variables

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

cancelled是由上下文返回的错误。当上下文被取消时Err。

var DeadlineExceeded error = deadlineExceededError{}

DeadlineExceeded是上下文返回的错误。当上下文的截止日期过了时出错。

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

上下文跨API边界携带截止日期、取消信号和其他值。多个goroutine可以同时调用Context的方法。

func Background

func Background() Context

Background返回非nil的空上下文。它从不取消，没有值，也没有截止日期。它通常由主函数、初始化和测试使用，并作为传入请求的顶级上下文。

func TODO

func TODO() Context

TODO返回一个非零的空上下文。代码应使用上下文.TODO当不清楚要使用哪个上下文或者它还不可用时（因为周围的函数还没有扩展到接受上下文参数）。TODO由静态分析工具识别，这些工具确定上下文是否在程序中正确传播。

func WithCancel

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

WithCancel返回具有新完成通道的父级的副本。当调用返回的cancel函数或父上下文的Done通道关闭时（以先发生的为准），返回的上下文的Done通道关闭。

取消此上下文将释放与其关联的资源，因此代码应该在该上下文中运行的操作完成后立即调用cancel。

func WithDeadline

func WithDeadline(parent Context, deadline time.Time) (Context, CancelFunc)

WithDeadline返回父上下文的副本，并将截止日期调整为不晚于d。如果父上下文的截止日期早于d，则WithDeadline（parent，d）在语义上等同于parent。当截止日期过期、调用返回的cancel函数或父上下文的Done通道关闭时（以先发生的为准），返回的上下文的Done通道将关闭。

取消此上下文将释放与其关联的资源，因此代码应该在该上下文中运行的操作完成后立即调用cancel。

func WithTimeout

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

WithTimeout返回WithDeadline（父，时间到了。现在（）.添加（超时）。

取消此上下文将释放与其关联的资源，因此代码应在此上下文中运行的操作完成后立即调用cancel：

func slowOperationWithTimeout(ctx context.Context) (Result, error) {
    ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)
    defer cancel()  // releases resources if slowOperation completes before timeout elapses
    return slowOperation(ctx)
}

func WithValue

func WithValue(parent Context, key, val interface{}) Context

WithValue返回父级的副本，其中与键关联的值是val。

仅对传输进程和API的请求范围内的数据使用上下文值，而不是将可选参数传递给函数。

提供的键必须是可比较的，并且不应是string类型或任何其他内置类型，以避免使用context的包之间发生冲突。WithValue的用户应该为键定义自己的类型。为了避免在分配给接口{}时进行分配，上下文键通常具有具体的类型struct{}。或者，导出的上下文键变量的静态类型应该是指针或接口。

参考资料：

Go语言中文文档

http://www.golang.ltd/

Go语言官方文档

https://golang.google.cn/