1// Copyright 2014 The Go Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style 3// license that can be found in the LICENSE file. 4 5// Package context defines the Context type, which carries deadlines, 6// cancelation signals, and other request-scoped values across API boundaries 7// and between processes. 8// As of Go 1.7 this package is available in the standard library under the 9// name context. https://golang.org/pkg/context. 10// 11// Incoming requests to a server should create a Context, and outgoing calls to 12// servers should accept a Context. The chain of function calls between must 13// propagate the Context, optionally replacing it with a modified copy created 14// using WithDeadline, WithTimeout, WithCancel, or WithValue. 15// 16// Programs that use Contexts should follow these rules to keep interfaces 17// consistent across packages and enable static analysis tools to check context 18// propagation: 19// 20// Do not store Contexts inside a struct type; instead, pass a Context 21// explicitly to each function that needs it. The Context should be the first 22// parameter, typically named ctx: 23// 24// func DoSomething(ctx context.Context, arg Arg) error { 25// // ... use ctx ... 26// } 27// 28// Do not pass a nil Context, even if a function permits it. Pass context.TODO 29// if you are unsure about which Context to use. 30// 31// Use context Values only for request-scoped data that transits processes and 32// APIs, not for passing optional parameters to functions. 33// 34// The same Context may be passed to functions running in different goroutines; 35// Contexts are safe for simultaneous use by multiple goroutines. 36// 37// See http://blog.golang.org/context for example code for a server that uses 38// Contexts. 39package context // import "golang.org/x/net/context" 40 41// Background returns a non-nil, empty Context. It is never canceled, has no 42// values, and has no deadline. It is typically used by the main function, 43// initialization, and tests, and as the top-level Context for incoming 44// requests. 45func Background() Context { 46 return background 47} 48 49// TODO returns a non-nil, empty Context. Code should use context.TODO when 50// it's unclear which Context to use or it is not yet available (because the 51// surrounding function has not yet been extended to accept a Context 52// parameter). TODO is recognized by static analysis tools that determine 53// whether Contexts are propagated correctly in a program. 54func TODO() Context { 55 return todo 56} 57