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