github.com/blockchain-foundry/go-ethereum@v1.5.9/build/_vendor/src/golang.org/x/net/context/context.go (about) 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()