Skip to content
Snippets Groups Projects
context.go 2.4 KiB
Newer Older
  • Learn to ignore specific revisions
  • // Copyright 2014 The Go Authors. All rights reserved.
    // Use of this source code is governed by a BSD-style
    // license that can be found in the LICENSE file.
    
    // Package context defines the Context type, which carries deadlines,
    // cancelation signals, and other request-scoped values across API boundaries
    // and between processes.
    // As of Go 1.7 this package is available in the standard library under the
    // name context.  https://golang.org/pkg/context.
    //
    // Incoming requests to a server should create a Context, and outgoing calls to
    // servers should accept a Context. The chain of function calls between must
    // propagate the Context, optionally replacing it with a modified copy created
    // using WithDeadline, WithTimeout, WithCancel, or WithValue.
    //
    // Programs that use Contexts should follow these rules to keep interfaces
    // consistent across packages and enable static analysis tools to check context
    // propagation:
    //
    // Do not store Contexts inside a struct type; instead, pass a Context
    // explicitly to each function that needs it. The Context should be the first
    // parameter, typically named ctx:
    //
    //	func DoSomething(ctx context.Context, arg Arg) error {
    //		// ... use ctx ...
    //	}
    //
    // Do not pass a nil Context, even if a function permits it. Pass context.TODO
    // if you are unsure about which Context to use.
    //
    // Use context Values only for request-scoped data that transits processes and
    // APIs, not for passing optional parameters to functions.
    //
    // The same Context may be passed to functions running in different goroutines;
    // Contexts are safe for simultaneous use by multiple goroutines.
    //
    // See http://blog.golang.org/context for example code for a server that uses
    // Contexts.
    package context // import "golang.org/x/net/context"
    
    // Background returns a non-nil, empty Context. It is never canceled, has no
    // values, and has no deadline. It is typically used by the main function,
    // initialization, and tests, and as the top-level Context for incoming
    // requests.
    func Background() Context {
    	return background
    }
    
    // TODO returns a non-nil, empty Context. Code should use context.TODO when
    // it's unclear which Context to use or it is not yet available (because the
    // surrounding function has not yet been extended to accept a Context
    // parameter).  TODO is recognized by static analysis tools that determine
    // whether Contexts are propagated correctly in a program.
    func TODO() Context {
    	return todo
    }