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
7package context
8
9import "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.
15type 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.
109type CancelFunc func()