]>
Commit | Line | Data |
---|---|---|
15c0b25d AP |
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() |