David K. Bainbridge | 215e024 | 2017-09-05 23:18:24 -0700 | [diff] [blame^] | 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 | import "time" |
| 40 | |
| 41 | // A Context carries a deadline, a cancelation signal, and other values across |
| 42 | // API boundaries. |
| 43 | // |
| 44 | // Context's methods may be called by multiple goroutines simultaneously. |
| 45 | type Context interface { |
| 46 | // Deadline returns the time when work done on behalf of this context |
| 47 | // should be canceled. Deadline returns ok==false when no deadline is |
| 48 | // set. Successive calls to Deadline return the same results. |
| 49 | Deadline() (deadline time.Time, ok bool) |
| 50 | |
| 51 | // Done returns a channel that's closed when work done on behalf of this |
| 52 | // context should be canceled. Done may return nil if this context can |
| 53 | // never be canceled. Successive calls to Done return the same value. |
| 54 | // |
| 55 | // WithCancel arranges for Done to be closed when cancel is called; |
| 56 | // WithDeadline arranges for Done to be closed when the deadline |
| 57 | // expires; WithTimeout arranges for Done to be closed when the timeout |
| 58 | // elapses. |
| 59 | // |
| 60 | // Done is provided for use in select statements: |
| 61 | // |
| 62 | // // Stream generates values with DoSomething and sends them to out |
| 63 | // // until DoSomething returns an error or ctx.Done is closed. |
| 64 | // func Stream(ctx context.Context, out chan<- Value) error { |
| 65 | // for { |
| 66 | // v, err := DoSomething(ctx) |
| 67 | // if err != nil { |
| 68 | // return err |
| 69 | // } |
| 70 | // select { |
| 71 | // case <-ctx.Done(): |
| 72 | // return ctx.Err() |
| 73 | // case out <- v: |
| 74 | // } |
| 75 | // } |
| 76 | // } |
| 77 | // |
| 78 | // See http://blog.golang.org/pipelines for more examples of how to use |
| 79 | // a Done channel for cancelation. |
| 80 | Done() <-chan struct{} |
| 81 | |
| 82 | // Err returns a non-nil error value after Done is closed. Err returns |
| 83 | // Canceled if the context was canceled or DeadlineExceeded if the |
| 84 | // context's deadline passed. No other values for Err are defined. |
| 85 | // After Done is closed, successive calls to Err return the same value. |
| 86 | Err() error |
| 87 | |
| 88 | // Value returns the value associated with this context for key, or nil |
| 89 | // if no value is associated with key. Successive calls to Value with |
| 90 | // the same key returns the same result. |
| 91 | // |
| 92 | // Use context values only for request-scoped data that transits |
| 93 | // processes and API boundaries, not for passing optional parameters to |
| 94 | // functions. |
| 95 | // |
| 96 | // A key identifies a specific value in a Context. Functions that wish |
| 97 | // to store values in Context typically allocate a key in a global |
| 98 | // variable then use that key as the argument to context.WithValue and |
| 99 | // Context.Value. A key can be any type that supports equality; |
| 100 | // packages should define keys as an unexported type to avoid |
| 101 | // collisions. |
| 102 | // |
| 103 | // Packages that define a Context key should provide type-safe accessors |
| 104 | // for the values stores using that key: |
| 105 | // |
| 106 | // // Package user defines a User type that's stored in Contexts. |
| 107 | // package user |
| 108 | // |
| 109 | // import "golang.org/x/net/context" |
| 110 | // |
| 111 | // // User is the type of value stored in the Contexts. |
| 112 | // type User struct {...} |
| 113 | // |
| 114 | // // key is an unexported type for keys defined in this package. |
| 115 | // // This prevents collisions with keys defined in other packages. |
| 116 | // type key int |
| 117 | // |
| 118 | // // userKey is the key for user.User values in Contexts. It is |
| 119 | // // unexported; clients use user.NewContext and user.FromContext |
| 120 | // // instead of using this key directly. |
| 121 | // var userKey key = 0 |
| 122 | // |
| 123 | // // NewContext returns a new Context that carries value u. |
| 124 | // func NewContext(ctx context.Context, u *User) context.Context { |
| 125 | // return context.WithValue(ctx, userKey, u) |
| 126 | // } |
| 127 | // |
| 128 | // // FromContext returns the User value stored in ctx, if any. |
| 129 | // func FromContext(ctx context.Context) (*User, bool) { |
| 130 | // u, ok := ctx.Value(userKey).(*User) |
| 131 | // return u, ok |
| 132 | // } |
| 133 | Value(key interface{}) interface{} |
| 134 | } |
| 135 | |
| 136 | // Background returns a non-nil, empty Context. It is never canceled, has no |
| 137 | // values, and has no deadline. It is typically used by the main function, |
| 138 | // initialization, and tests, and as the top-level Context for incoming |
| 139 | // requests. |
| 140 | func Background() Context { |
| 141 | return background |
| 142 | } |
| 143 | |
| 144 | // TODO returns a non-nil, empty Context. Code should use context.TODO when |
| 145 | // it's unclear which Context to use or it is not yet available (because the |
| 146 | // surrounding function has not yet been extended to accept a Context |
| 147 | // parameter). TODO is recognized by static analysis tools that determine |
| 148 | // whether Contexts are propagated correctly in a program. |
| 149 | func TODO() Context { |
| 150 | return todo |
| 151 | } |
| 152 | |
| 153 | // A CancelFunc tells an operation to abandon its work. |
| 154 | // A CancelFunc does not wait for the work to stop. |
| 155 | // After the first call, subsequent calls to a CancelFunc do nothing. |
| 156 | type CancelFunc func() |