context.go (2461B)
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. 39 package 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. 45 func 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. 54 func TODO() Context { 55 return todo 56 }