Don Newton | e0d34a8 | 2019-11-14 10:58:06 -0500 | [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 | // +build !go1.9 |
| 6 | |
| 7 | package context |
| 8 | |
| 9 | import "time" |
| 10 | |
| 11 | // A Context carries a deadline, a cancelation signal, and other values across |
| 12 | // API boundaries. |
| 13 | // |
| 14 | // Context's methods may be called by multiple goroutines simultaneously. |
| 15 | type Context interface { |
| 16 | // Deadline returns the time when work done on behalf of this context |
| 17 | // should be canceled. Deadline returns ok==false when no deadline is |
| 18 | // set. Successive calls to Deadline return the same results. |
| 19 | Deadline() (deadline time.Time, ok bool) |
| 20 | |
| 21 | // Done returns a channel that's closed when work done on behalf of this |
| 22 | // context should be canceled. Done may return nil if this context can |
| 23 | // never be canceled. Successive calls to Done return the same value. |
| 24 | // |
| 25 | // WithCancel arranges for Done to be closed when cancel is called; |
| 26 | // WithDeadline arranges for Done to be closed when the deadline |
| 27 | // expires; WithTimeout arranges for Done to be closed when the timeout |
| 28 | // elapses. |
| 29 | // |
| 30 | // Done is provided for use in select statements: |
| 31 | // |
| 32 | // // Stream generates values with DoSomething and sends them to out |
| 33 | // // until DoSomething returns an error or ctx.Done is closed. |
| 34 | // func Stream(ctx context.Context, out chan<- Value) error { |
| 35 | // for { |
| 36 | // v, err := DoSomething(ctx) |
| 37 | // if err != nil { |
| 38 | // return err |
| 39 | // } |
| 40 | // select { |
| 41 | // case <-ctx.Done(): |
| 42 | // return ctx.Err() |
| 43 | // case out <- v: |
| 44 | // } |
| 45 | // } |
| 46 | // } |
| 47 | // |
| 48 | // See http://blog.golang.org/pipelines for more examples of how to use |
| 49 | // a Done channel for cancelation. |
| 50 | Done() <-chan struct{} |
| 51 | |
| 52 | // Err returns a non-nil error value after Done is closed. Err returns |
| 53 | // Canceled if the context was canceled or DeadlineExceeded if the |
| 54 | // context's deadline passed. No other values for Err are defined. |
| 55 | // After Done is closed, successive calls to Err return the same value. |
| 56 | Err() error |
| 57 | |
| 58 | // Value returns the value associated with this context for key, or nil |
| 59 | // if no value is associated with key. Successive calls to Value with |
| 60 | // the same key returns the same result. |
| 61 | // |
| 62 | // Use context values only for request-scoped data that transits |
| 63 | // processes and API boundaries, not for passing optional parameters to |
| 64 | // functions. |
| 65 | // |
| 66 | // A key identifies a specific value in a Context. Functions that wish |
| 67 | // to store values in Context typically allocate a key in a global |
| 68 | // variable then use that key as the argument to context.WithValue and |
| 69 | // Context.Value. A key can be any type that supports equality; |
| 70 | // packages should define keys as an unexported type to avoid |
| 71 | // collisions. |
| 72 | // |
| 73 | // Packages that define a Context key should provide type-safe accessors |
| 74 | // for the values stores using that key: |
| 75 | // |
| 76 | // // Package user defines a User type that's stored in Contexts. |
| 77 | // package user |
| 78 | // |
| 79 | // import "golang.org/x/net/context" |
| 80 | // |
| 81 | // // User is the type of value stored in the Contexts. |
| 82 | // type User struct {...} |
| 83 | // |
| 84 | // // key is an unexported type for keys defined in this package. |
| 85 | // // This prevents collisions with keys defined in other packages. |
| 86 | // type key int |
| 87 | // |
| 88 | // // userKey is the key for user.User values in Contexts. It is |
| 89 | // // unexported; clients use user.NewContext and user.FromContext |
| 90 | // // instead of using this key directly. |
| 91 | // var userKey key = 0 |
| 92 | // |
| 93 | // // NewContext returns a new Context that carries value u. |
| 94 | // func NewContext(ctx context.Context, u *User) context.Context { |
| 95 | // return context.WithValue(ctx, userKey, u) |
| 96 | // } |
| 97 | // |
| 98 | // // FromContext returns the User value stored in ctx, if any. |
| 99 | // func FromContext(ctx context.Context) (*User, bool) { |
| 100 | // u, ok := ctx.Value(userKey).(*User) |
| 101 | // return u, ok |
| 102 | // } |
| 103 | Value(key interface{}) interface{} |
| 104 | } |
| 105 | |
| 106 | // A CancelFunc tells an operation to abandon its work. |
| 107 | // A CancelFunc does not wait for the work to stop. |
| 108 | // After the first call, subsequent calls to a CancelFunc do nothing. |
| 109 | type CancelFunc func() |