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