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"))
}