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()
110