blob: a3c021d3f88e98457163fd084ac9b49e1ddf5931 [file] [log] [blame]
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -07001// 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// As of Go 1.7 this package is available in the standard library under the
9// name context. https://golang.org/pkg/context.
10//
11// Incoming requests to a server should create a Context, and outgoing calls to
12// servers should accept a Context. The chain of function calls between must
13// propagate the Context, optionally replacing it with a modified copy created
14// using WithDeadline, WithTimeout, WithCancel, or WithValue.
15//
16// Programs that use Contexts should follow these rules to keep interfaces
17// consistent across packages and enable static analysis tools to check context
18// propagation:
19//
20// Do not store Contexts inside a struct type; instead, pass a Context
21// explicitly to each function that needs it. The Context should be the first
22// parameter, typically named ctx:
23//
24// func DoSomething(ctx context.Context, arg Arg) error {
25// // ... use ctx ...
26// }
27//
28// Do not pass a nil Context, even if a function permits it. Pass context.TODO
29// if you are unsure about which Context to use.
30//
31// Use context Values only for request-scoped data that transits processes and
32// APIs, not for passing optional parameters to functions.
33//
34// The same Context may be passed to functions running in different goroutines;
35// Contexts are safe for simultaneous use by multiple goroutines.
36//
37// See http://blog.golang.org/context for example code for a server that uses
38// Contexts.
39package context // import "golang.org/x/net/context"
40
41// Background returns a non-nil, empty Context. It is never canceled, has no
42// values, and has no deadline. It is typically used by the main function,
43// initialization, and tests, and as the top-level Context for incoming
44// requests.
45func Background() Context {
46 return background
47}
48
49// TODO returns a non-nil, empty Context. Code should use context.TODO when
50// it's unclear which Context to use or it is not yet available (because the
51// surrounding function has not yet been extended to accept a Context
52// parameter). TODO is recognized by static analysis tools that determine
53// whether Contexts are propagated correctly in a program.
54func TODO() Context {
55 return todo
56}