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. 37package context // import "golang.org/x/net/context" 38 39import "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. 45type 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. 140func 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. 149func 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. 156type CancelFunc func() 157