src/context/context.go - go - Git at Google

 // 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,
 // cancellation signals, and other request-scoped values across API boundaries
 // and between processes.
 //
 // Incoming requests to a server should create a Context, and outgoing
 // calls to servers should accept a Context. The chain of function
 // calls between them must propagate the Context, optionally replacing
 // it with a derived Context created using WithCancel, WithDeadline,
 // WithTimeout, or WithValue. When a Context is canceled, all
 // Contexts derived from it are also canceled.
 //
 // The WithCancel, WithDeadline, and WithTimeout functions take a
 // Context (the parent) and return a derived Context (the child) and a
 // CancelFunc. Calling the CancelFunc cancels the child and its
 // children, removes the parent's reference to the child, and stops
 // any associated timers. Failing to call the CancelFunc leaks the
 // child and its children until the parent is canceled or the timer
 // fires. The go vet tool checks that CancelFuncs are used on all
 // control-flow paths.
 //
 // 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 https://blog.golang.org/context for example code for a server that uses
 // Contexts.
 package context

 import (
 	"errors"
 	"internal/reflectlite"
 	"sync"
 	"sync/atomic"
 	"time"
 )

 // A Context carries a deadline, a cancellation signal, and other values across
 // API boundaries.
 //
 // Context's methods may be called by multiple goroutines simultaneously.
 type Context interface {
 	// Deadline returns the time when work done on behalf of this context
 	// should be canceled. Deadline returns ok==false when no deadline is
 	// set. Successive calls to Deadline return the same results.
 	Deadline() (deadline time.Time, ok bool)

 	// Done returns a channel that's closed when work done on behalf of this
 	// context should be canceled. Done may return nil if this context can
 	// never be canceled. Successive calls to Done return the same value.
 	// The close of the Done channel may happen asynchronously,
 	// after the cancel function returns.
 	//
 	// WithCancel arranges for Done to be closed when cancel is called;
 	// WithDeadline arranges for Done to be closed when the deadline
 	// expires; WithTimeout arranges for Done to be closed when the timeout
 	// elapses.
 	//
 	// Done is provided for use in select statements:
 	//
 	//  // Stream generates values with DoSomething and sends them to out
 	//  // until DoSomething returns an error or ctx.Done is closed.
 	//  func Stream(ctx context.Context, out chan<- Value) error {
 	//  	for {
 	//  		v, err := DoSomething(ctx)
 	//  		if err != nil {
 	//  			return err
 	//  		}
 	//  		select {
 	//  		case <-ctx.Done():
 	//  			return ctx.Err()
 	//  		case out <- v:
 	//  		}
 	//  	}
 	//  }
 	//
 	// See https://blog.golang.org/pipelines for more examples of how to use
 	// a Done channel for cancellation.
 	Done() <-chan struct{}

 	// If Done is not yet closed, Err returns nil.
 	// If Done is closed, Err returns a non-nil error explaining why:
 	// Canceled if the context was canceled
 	// or DeadlineExceeded if the context's deadline passed.
 	// After Err returns a non-nil error, successive calls to Err return the same error.
 	Err() error

 	// Value returns the value associated with this context for key, or nil
 	// if no value is associated with key. Successive calls to Value with
 	// the same key returns the same result.
 	//
 	// Use context values only for request-scoped data that transits
 	// processes and API boundaries, not for passing optional parameters to
 	// functions.
 	//
 	// A key identifies a specific value in a Context. Functions that wish
 	// to store values in Context typically allocate a key in a global
 	// variable then use that key as the argument to context.WithValue and
 	// Context.Value. A key can be any type that supports equality;
 	// packages should define keys as an unexported type to avoid
 	// collisions.
 	//
 	// Packages that define a Context key should provide type-safe accessors
 	// for the values stored using that key:
 	//
 	// 	// Package user defines a User type that's stored in Contexts.
 	// 	package user
 	//
 	// 	import "context"
 	//
 	// 	// User is the type of value stored in the Contexts.
 	// 	type User struct {...}
 	//
 	// 	// key is an unexported type for keys defined in this package.
 	// 	// This prevents collisions with keys defined in other packages.
 	// 	type key int
 	//
 	// 	// userKey is the key for user.User values in Contexts. It is
 	// 	// unexported; clients use user.NewContext and user.FromContext
 	// 	// instead of using this key directly.
 	// 	var userKey key
 	//
 	// 	// NewContext returns a new Context that carries value u.
 	// 	func NewContext(ctx context.Context, u *User) context.Context {
 	// 		return context.WithValue(ctx, userKey, u)
 	// 	}
 	//
 	// 	// FromContext returns the User value stored in ctx, if any.
 	// 	func FromContext(ctx context.Context) (*User, bool) {
 	// 		u, ok := ctx.Value(userKey).(*User)
 	// 		return u, ok
 	// 	}
 	Value(key interface{}) interface{}
 }

 // Canceled is the error returned by Context.Err when the context is canceled.
 var Canceled = errors.New("context canceled")

 // DeadlineExceeded is the error returned by Context.Err when the context's
 // deadline passes.
 var DeadlineExceeded error = deadlineExceededError{}

 type deadlineExceededError struct{}

 func (deadlineExceededError) Error() string   { return "context deadline exceeded" }
 func (deadlineExceededError) Timeout() bool   { return true }
 func (deadlineExceededError) Temporary() bool { return true }

 // An emptyCtx is never canceled, has no values, and has no deadline. It is not
 // struct{}, since vars of this type must have distinct addresses.
 type emptyCtx int

 func (*emptyCtx) Deadline() (deadline time.Time, ok bool) {
 	return
 }

 func (*emptyCtx) Done() <-chan struct{} {
 	return nil
 }

 func (*emptyCtx) Err() error {
 	return nil
 }

 func (*emptyCtx) Value(key interface{}) interface{} {
 	return nil
 }

 func (e *emptyCtx) String() string {
 	switch e {
 	case background:
 		return "context.Background"
 	case todo:
 		return "context.TODO"
 	}
 	return "unknown empty Context"
 }

 var (
 	background = new(emptyCtx)
 	todo       = new(emptyCtx)
 )

 // 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).
 func TODO() Context {
 	return todo
 }

 // A CancelFunc tells an operation to abandon its work.
 // A CancelFunc does not wait for the work to stop.
 // A CancelFunc may be called by multiple goroutines simultaneously.
 // After the first call, subsequent calls to a CancelFunc do nothing.
 type CancelFunc func()

 // WithCancel returns a copy of parent with a new Done channel. The returned
 // context's Done channel is closed when the returned cancel function is called
 // or when the parent context's Done channel is closed, whichever happens first.
 //
 // Canceling this context releases resources associated with it, so code should
 // call cancel as soon as the operations running in this Context complete.
 func WithCancel(parent Context) (ctx Context, cancel CancelFunc) {
 	if parent == nil {
 		panic("cannot create context from nil parent")
 	}
 	c := newCancelCtx(parent)
 	propagateCancel(parent, &c)
 	return &c, func() { c.cancel(true, Canceled) }
 }

 // newCancelCtx returns an initialized cancelCtx.
 func newCancelCtx(parent Context) cancelCtx {
 	return cancelCtx{Context: parent}
 }

 // goroutines counts the number of goroutines ever created; for testing.
 var goroutines int32

 // propagateCancel arranges for child to be canceled when parent is.
 func propagateCancel(parent Context, child canceler) {
 	done := parent.Done()
 	if done == nil {
 		return // parent is never canceled
 	}

 	select {
 	case <-done:
 		// parent is already canceled
 		child.cancel(false, parent.Err())
 		return
 	default:
 	}

 	if p, ok := parentCancelCtx(parent); ok {
 		p.mu.Lock()
 		if p.err != nil {
 			// parent has already been canceled
 			child.cancel(false, p.err)
 		} else {
 			if p.children == nil {
 				p.children = make(map[canceler]struct{})
 			}
 			p.children[child] = struct{}{}
 		}
 		p.mu.Unlock()
 	} else {
 		atomic.AddInt32(&goroutines, +1)
 		go func() {
 			select {
 			case <-parent.Done():
 				child.cancel(false, parent.Err())
 			case <-child.Done():
 			}
 		}()
 	}
 }

 // &cancelCtxKey is the key that a cancelCtx returns itself for.
 var cancelCtxKey int

 // parentCancelCtx returns the underlying *cancelCtx for parent.
 // It does this by looking up parent.Value(&cancelCtxKey) to find
 // the innermost enclosing *cancelCtx and then checking whether
 // parent.Done() matches that *cancelCtx. (If not, the *cancelCtx
 // has been wrapped in a custom implementation providing a
 // different done channel, in which case we should not bypass it.)
 func parentCancelCtx(parent Context) (*cancelCtx, bool) {
 	done := parent.Done()
 	if done == closedchan || done == nil {
 		return nil, false
 	}
 	p, ok := parent.Value(&cancelCtxKey).(*cancelCtx)
 	if !ok {
 		return nil, false
 	}
 	pdone, _ := p.done.Load().(chan struct{})
 	if pdone != done {
 		return nil, false
 	}
 	return p, true
 }

 // removeChild removes a context from its parent.
 func removeChild(parent Context, child canceler) {
 	p, ok := parentCancelCtx(parent)
 	if !ok {
 		return
 	}
 	p.mu.Lock()
 	if p.children != nil {
 		delete(p.children, child)
 	}
 	p.mu.Unlock()
 }

 // A canceler is a context type that can be canceled directly. The
 // implementations are *cancelCtx and *timerCtx.
 type canceler interface {
 	cancel(removeFromParent bool, err error)
 	Done() <-chan struct{}
 }

 // closedchan is a reusable closed channel.
 var closedchan = make(chan struct{})

 func init() {
 	close(closedchan)
 }

 // A cancelCtx can be canceled. When canceled, it also cancels any children
 // that implement canceler.
 type cancelCtx struct {
 	Context

 	mu       sync.Mutex            // protects following fields
 	done     atomic.Value          // of chan struct{}, created lazily, closed by first cancel call
 	children map[canceler]struct{} // set to nil by the first cancel call
 	err      error                 // set to non-nil by the first cancel call
 }

 func (c *cancelCtx) Value(key interface{}) interface{} {
 	if key == &cancelCtxKey {
 		return c
 	}
 	return c.Context.Value(key)
 }

 func (c *cancelCtx) Done() <-chan struct{} {
 	d := c.done.Load()
 	if d != nil {
 		return d.(chan struct{})
 	}
 	c.mu.Lock()
 	defer c.mu.Unlock()
 	d = c.done.Load()
 	if d == nil {
 		d = make(chan struct{})
 		c.done.Store(d)
 	}
 	return d.(chan struct{})
 }

 func (c *cancelCtx) Err() error {
 	c.mu.Lock()
 	err := c.err
 	c.mu.Unlock()
 	return err
 }

 type stringer interface {
 	String() string
 }

 func contextName(c Context) string {
 	if s, ok := c.(stringer); ok {
 		return s.String()
 	}
 	return reflectlite.TypeOf(c).String()
 }

 func (c *cancelCtx) String() string {
 	return contextName(c.Context) + ".WithCancel"
 }

 // cancel closes c.done, cancels each of c's children, and, if
 // removeFromParent is true, removes c from its parent's children.
 func (c *cancelCtx) cancel(removeFromParent bool, err error) {
 	if err == nil {
 		panic("context: internal error: missing cancel error")
 	}
 	c.mu.Lock()
 	if c.err != nil {
 		c.mu.Unlock()
 		return // already canceled
 	}
 	c.err = err
 	d, _ := c.done.Load().(chan struct{})
 	if d == nil {
 		c.done.Store(closedchan)
 	} else {
 		close(d)
 	}
 	for child := range c.children {
 		// NOTE: acquiring the child's lock while holding parent's lock.
 		child.cancel(false, err)
 	}
 	c.children = nil
 	c.mu.Unlock()

 	if removeFromParent {
 		removeChild(c.Context, c)
 	}
 }

 // WithDeadline returns a copy of the parent context with the deadline adjusted
 // to be no later than d. If the parent's deadline is already earlier than d,
 // WithDeadline(parent, d) is semantically equivalent to parent. The returned
 // context's Done channel is closed when the deadline expires, when the returned
 // cancel function is called, or when the parent context's Done channel is
 // closed, whichever happens first.
 //
 // Canceling this context releases resources associated with it, so code should
 // call cancel as soon as the operations running in this Context complete.
 func WithDeadline(parent Context, d time.Time) (Context, CancelFunc) {
 	if parent == nil {
 		panic("cannot create context from nil parent")
 	}
 	if cur, ok := parent.Deadline(); ok && cur.Before(d) {
 		// The current deadline is already sooner than the new one.
 		return WithCancel(parent)
 	}
 	c := &timerCtx{
 		cancelCtx: newCancelCtx(parent),
 		deadline:  d,
 	}
 	propagateCancel(parent, c)
 	dur := time.Until(d)
 	if dur <= 0 {
 		c.cancel(true, DeadlineExceeded) // deadline has already passed
 		return c, func() { c.cancel(false, Canceled) }
 	}
 	c.mu.Lock()
 	defer c.mu.Unlock()
 	if c.err == nil {
 		c.timer = time.AfterFunc(dur, func() {
 			c.cancel(true, DeadlineExceeded)
 		})
 	}
 	return c, func() { c.cancel(true, Canceled) }
 }

 // A timerCtx carries a timer and a deadline. It embeds a cancelCtx to
 // implement Done and Err. It implements cancel by stopping its timer then
 // delegating to cancelCtx.cancel.
 type timerCtx struct {
 	cancelCtx
 	timer *time.Timer // Under cancelCtx.mu.

 	deadline time.Time
 }

 func (c *timerCtx) Deadline() (deadline time.Time, ok bool) {
 	return c.deadline, true
 }

 func (c *timerCtx) String() string {
 	return contextName(c.cancelCtx.Context) + ".WithDeadline(" +
 		c.deadline.String() + " [" +
 		time.Until(c.deadline).String() + "])"
 }

 func (c *timerCtx) cancel(removeFromParent bool, err error) {
 	c.cancelCtx.cancel(false, err)
 	if removeFromParent {
 		// Remove this timerCtx from its parent cancelCtx's children.
 		removeChild(c.cancelCtx.Context, c)
 	}
 	c.mu.Lock()
 	if c.timer != nil {
 		c.timer.Stop()
 		c.timer = nil
 	}
 	c.mu.Unlock()
 }

 // WithTimeout returns WithDeadline(parent, time.Now().Add(timeout)).
 //
 // Canceling this context releases resources associated with it, so code should
 // call cancel as soon as the operations running in this Context complete:
 //
 // 	func slowOperationWithTimeout(ctx context.Context) (Result, error) {
 // 		ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)
 // 		defer cancel()  // releases resources if slowOperation completes before timeout elapses
 // 		return slowOperation(ctx)
 // 	}
 func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
 	return WithDeadline(parent, time.Now().Add(timeout))
 }

 // WithValue returns a copy of parent in which the value associated with key is
 // val.
 //
 // Use context Values only for request-scoped data that transits processes and
 // APIs, not for passing optional parameters to functions.
 //
 // The provided key must be comparable and should not be of type
 // string or any other built-in type to avoid collisions between
 // packages using context. Users of WithValue should define their own
 // types for keys. To avoid allocating when assigning to an
 // interface{}, context keys often have concrete type
 // struct{}. Alternatively, exported context key variables' static
 // type should be a pointer or interface.
 func WithValue(parent Context, key, val interface{}) Context {
 	if parent == nil {
 		panic("cannot create context from nil parent")
 	}
 	if key == nil {
 		panic("nil key")
 	}
 	if !reflectlite.TypeOf(key).Comparable() {
 		panic("key is not comparable")
 	}
 	return &valueCtx{parent, key, val}
 }

 // A valueCtx carries a key-value pair. It implements Value for that key and
 // delegates all other calls to the embedded Context.
 type valueCtx struct {
 	Context
 	key, val interface{}
 }

 // stringify tries a bit to stringify v, without using fmt, since we don't
 // want context depending on the unicode tables. This is only used by
 // *valueCtx.String().
 func stringify(v interface{}) string {
 	switch s := v.(type) {
 	case stringer:
 		return s.String()
 	case string:
 		return s
 	}
 	return "<not Stringer>"
 }

 func (c *valueCtx) String() string {
 	return contextName(c.Context) + ".WithValue(type " +
 		reflectlite.TypeOf(c.key).String() +
 		", val " + stringify(c.val) + ")"
 }

 func (c *valueCtx) Value(key interface{}) interface{} {
 	if c.key == key {
 		return c.val
 	}
 	return c.Context.Value(key)
 }
	// 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,
	// cancellation signals, and other request-scoped values across API boundaries
	// and between processes.
	//
	// Incoming requests to a server should create a Context, and outgoing
	// calls to servers should accept a Context. The chain of function
	// calls between them must propagate the Context, optionally replacing
	// it with a derived Context created using WithCancel, WithDeadline,
	// WithTimeout, or WithValue. When a Context is canceled, all
	// Contexts derived from it are also canceled.
	//
	// The WithCancel, WithDeadline, and WithTimeout functions take a
	// Context (the parent) and return a derived Context (the child) and a
	// CancelFunc. Calling the CancelFunc cancels the child and its
	// children, removes the parent's reference to the child, and stops
	// any associated timers. Failing to call the CancelFunc leaks the
	// child and its children until the parent is canceled or the timer
	// fires. The go vet tool checks that CancelFuncs are used on all
	// control-flow paths.
	//
	// 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 https://blog.golang.org/context for example code for a server that uses
	// Contexts.
	package context

	import (
	"errors"
	"internal/reflectlite"
	"sync"
	"sync/atomic"
	"time"
	)

	// A Context carries a deadline, a cancellation signal, and other values across
	// API boundaries.
	//
	// Context's methods may be called by multiple goroutines simultaneously.
	type Context interface {
	// Deadline returns the time when work done on behalf of this context
	// should be canceled. Deadline returns ok==false when no deadline is
	// set. Successive calls to Deadline return the same results.
	Deadline() (deadline time.Time, ok bool)

	// Done returns a channel that's closed when work done on behalf of this
	// context should be canceled. Done may return nil if this context can
	// never be canceled. Successive calls to Done return the same value.
	// The close of the Done channel may happen asynchronously,
	// after the cancel function returns.
	//
	// WithCancel arranges for Done to be closed when cancel is called;
	// WithDeadline arranges for Done to be closed when the deadline
	// expires; WithTimeout arranges for Done to be closed when the timeout
	// elapses.
	//
	// Done is provided for use in select statements:
	//
	// // Stream generates values with DoSomething and sends them to out
	// // until DoSomething returns an error or ctx.Done is closed.
	// func Stream(ctx context.Context, out chan<- Value) error {
	// for {
	// v, err := DoSomething(ctx)
	// if err != nil {
	// return err
	// }
	// select {
	// case <-ctx.Done():
	// return ctx.Err()
	// case out <- v:
	// }
	// }
	// }
	//
	// See https://blog.golang.org/pipelines for more examples of how to use
	// a Done channel for cancellation.
	Done() <-chan struct{}

	// If Done is not yet closed, Err returns nil.
	// If Done is closed, Err returns a non-nil error explaining why:
	// Canceled if the context was canceled
	// or DeadlineExceeded if the context's deadline passed.
	// After Err returns a non-nil error, successive calls to Err return the same error.
	Err() error

	// Value returns the value associated with this context for key, or nil
	// if no value is associated with key. Successive calls to Value with
	// the same key returns the same result.
	//
	// Use context values only for request-scoped data that transits
	// processes and API boundaries, not for passing optional parameters to
	// functions.
	//
	// A key identifies a specific value in a Context. Functions that wish
	// to store values in Context typically allocate a key in a global
	// variable then use that key as the argument to context.WithValue and
	// Context.Value. A key can be any type that supports equality;
	// packages should define keys as an unexported type to avoid
	// collisions.
	//
	// Packages that define a Context key should provide type-safe accessors
	// for the values stored using that key:
	//
	// // Package user defines a User type that's stored in Contexts.
	// package user
	//
	// import "context"
	//
	// // User is the type of value stored in the Contexts.
	// type User struct {...}
	//
	// // key is an unexported type for keys defined in this package.
	// // This prevents collisions with keys defined in other packages.
	// type key int
	//
	// // userKey is the key for user.User values in Contexts. It is
	// // unexported; clients use user.NewContext and user.FromContext
	// // instead of using this key directly.
	// var userKey key
	//
	// // NewContext returns a new Context that carries value u.
	// func NewContext(ctx context.Context, u *User) context.Context {
	// return context.WithValue(ctx, userKey, u)
	// }
	//
	// // FromContext returns the User value stored in ctx, if any.
	// func FromContext(ctx context.Context) (*User, bool) {
	// u, ok := ctx.Value(userKey).(*User)
	// return u, ok
	// }
	Value(key interface{}) interface{}
	}

	// Canceled is the error returned by Context.Err when the context is canceled.
	var Canceled = errors.New("context canceled")

	// DeadlineExceeded is the error returned by Context.Err when the context's
	// deadline passes.
	var DeadlineExceeded error = deadlineExceededError{}

	type deadlineExceededError struct{}

	func (deadlineExceededError) Error() string { return "context deadline exceeded" }
	func (deadlineExceededError) Timeout() bool { return true }
	func (deadlineExceededError) Temporary() bool { return true }

	// An emptyCtx is never canceled, has no values, and has no deadline. It is not
	// struct{}, since vars of this type must have distinct addresses.
	type emptyCtx int

	func (*emptyCtx) Deadline() (deadline time.Time, ok bool) {
	return
	}

	func (*emptyCtx) Done() <-chan struct{} {
	return nil
	}

	func (*emptyCtx) Err() error {
	return nil
	}

	func (*emptyCtx) Value(key interface{}) interface{} {
	return nil
	}

	func (e *emptyCtx) String() string {
	switch e {
	case background:
	return "context.Background"
	case todo:
	return "context.TODO"
	}
	return "unknown empty Context"
	}

	var (
	background = new(emptyCtx)
	todo = new(emptyCtx)
	)

	// 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).
	func TODO() Context {
	return todo
	}

	// A CancelFunc tells an operation to abandon its work.
	// A CancelFunc does not wait for the work to stop.
	// A CancelFunc may be called by multiple goroutines simultaneously.
	// After the first call, subsequent calls to a CancelFunc do nothing.
	type CancelFunc func()

	// WithCancel returns a copy of parent with a new Done channel. The returned
	// context's Done channel is closed when the returned cancel function is called
	// or when the parent context's Done channel is closed, whichever happens first.
	//
	// Canceling this context releases resources associated with it, so code should
	// call cancel as soon as the operations running in this Context complete.
	func WithCancel(parent Context) (ctx Context, cancel CancelFunc) {
	if parent == nil {
	panic("cannot create context from nil parent")
	}
	c := newCancelCtx(parent)
	propagateCancel(parent, &c)
	return &c, func() { c.cancel(true, Canceled) }
	}

	// newCancelCtx returns an initialized cancelCtx.
	func newCancelCtx(parent Context) cancelCtx {
	return cancelCtx{Context: parent}
	}

	// goroutines counts the number of goroutines ever created; for testing.
	var goroutines int32

	// propagateCancel arranges for child to be canceled when parent is.
	func propagateCancel(parent Context, child canceler) {
	done := parent.Done()
	if done == nil {
	return // parent is never canceled
	}

	select {
	case <-done:
	// parent is already canceled
	child.cancel(false, parent.Err())
	return
	default:
	}

	if p, ok := parentCancelCtx(parent); ok {
	p.mu.Lock()
	if p.err != nil {
	// parent has already been canceled
	child.cancel(false, p.err)
	} else {
	if p.children == nil {
	p.children = make(map[canceler]struct{})
	}
	p.children[child] = struct{}{}
	}
	p.mu.Unlock()
	} else {
	atomic.AddInt32(&goroutines, +1)
	go func() {
	select {
	case <-parent.Done():
	child.cancel(false, parent.Err())
	case <-child.Done():
	}
	}()
	}
	}

	// &cancelCtxKey is the key that a cancelCtx returns itself for.
	var cancelCtxKey int

	// parentCancelCtx returns the underlying *cancelCtx for parent.
	// It does this by looking up parent.Value(&cancelCtxKey) to find
	// the innermost enclosing *cancelCtx and then checking whether
	// parent.Done() matches that cancelCtx. (If not, the cancelCtx
	// has been wrapped in a custom implementation providing a
	// different done channel, in which case we should not bypass it.)
	func parentCancelCtx(parent Context) (*cancelCtx, bool) {
	done := parent.Done()
	if done == closedchan \|\| done == nil {
	return nil, false
	}
	p, ok := parent.Value(&cancelCtxKey).(*cancelCtx)
	if !ok {
	return nil, false
	}
	pdone, _ := p.done.Load().(chan struct{})
	if pdone != done {
	return nil, false
	}
	return p, true
	}

	// removeChild removes a context from its parent.
	func removeChild(parent Context, child canceler) {
	p, ok := parentCancelCtx(parent)
	if !ok {
	return
	}
	p.mu.Lock()
	if p.children != nil {
	delete(p.children, child)
	}
	p.mu.Unlock()
	}

	// A canceler is a context type that can be canceled directly. The
	// implementations are cancelCtx and timerCtx.
	type canceler interface {
	cancel(removeFromParent bool, err error)
	Done() <-chan struct{}
	}

	// closedchan is a reusable closed channel.
	var closedchan = make(chan struct{})

	func init() {
	close(closedchan)
	}

	// A cancelCtx can be canceled. When canceled, it also cancels any children
	// that implement canceler.
	type cancelCtx struct {
	Context

	mu sync.Mutex // protects following fields
	done atomic.Value // of chan struct{}, created lazily, closed by first cancel call
	children map[canceler]struct{} // set to nil by the first cancel call
	err error // set to non-nil by the first cancel call
	}

	func (c *cancelCtx) Value(key interface{}) interface{} {
	if key == &cancelCtxKey {
	return c
	}
	return c.Context.Value(key)
	}

	func (c *cancelCtx) Done() <-chan struct{} {
	d := c.done.Load()
	if d != nil {
	return d.(chan struct{})
	}
	c.mu.Lock()
	defer c.mu.Unlock()
	d = c.done.Load()
	if d == nil {
	d = make(chan struct{})
	c.done.Store(d)
	}
	return d.(chan struct{})
	}

	func (c *cancelCtx) Err() error {
	c.mu.Lock()
	err := c.err
	c.mu.Unlock()
	return err
	}

	type stringer interface {
	String() string
	}

	func contextName(c Context) string {
	if s, ok := c.(stringer); ok {
	return s.String()
	}
	return reflectlite.TypeOf(c).String()
	}

	func (c *cancelCtx) String() string {
	return contextName(c.Context) + ".WithCancel"
	}

	// cancel closes c.done, cancels each of c's children, and, if
	// removeFromParent is true, removes c from its parent's children.
	func (c *cancelCtx) cancel(removeFromParent bool, err error) {
	if err == nil {
	panic("context: internal error: missing cancel error")
	}
	c.mu.Lock()
	if c.err != nil {
	c.mu.Unlock()
	return // already canceled
	}
	c.err = err
	d, _ := c.done.Load().(chan struct{})
	if d == nil {
	c.done.Store(closedchan)
	} else {
	close(d)
	}
	for child := range c.children {
	// NOTE: acquiring the child's lock while holding parent's lock.
	child.cancel(false, err)
	}
	c.children = nil
	c.mu.Unlock()

	if removeFromParent {
	removeChild(c.Context, c)
	}
	}

	// WithDeadline returns a copy of the parent context with the deadline adjusted
	// to be no later than d. If the parent's deadline is already earlier than d,
	// WithDeadline(parent, d) is semantically equivalent to parent. The returned
	// context's Done channel is closed when the deadline expires, when the returned
	// cancel function is called, or when the parent context's Done channel is
	// closed, whichever happens first.
	//
	// Canceling this context releases resources associated with it, so code should
	// call cancel as soon as the operations running in this Context complete.
	func WithDeadline(parent Context, d time.Time) (Context, CancelFunc) {
	if parent == nil {
	panic("cannot create context from nil parent")
	}
	if cur, ok := parent.Deadline(); ok && cur.Before(d) {
	// The current deadline is already sooner than the new one.
	return WithCancel(parent)
	}
	c := &timerCtx{
	cancelCtx: newCancelCtx(parent),
	deadline: d,
	}
	propagateCancel(parent, c)
	dur := time.Until(d)
	if dur <= 0 {
	c.cancel(true, DeadlineExceeded) // deadline has already passed
	return c, func() { c.cancel(false, Canceled) }
	}
	c.mu.Lock()
	defer c.mu.Unlock()
	if c.err == nil {
	c.timer = time.AfterFunc(dur, func() {
	c.cancel(true, DeadlineExceeded)
	})
	}
	return c, func() { c.cancel(true, Canceled) }
	}

	// A timerCtx carries a timer and a deadline. It embeds a cancelCtx to
	// implement Done and Err. It implements cancel by stopping its timer then
	// delegating to cancelCtx.cancel.
	type timerCtx struct {
	cancelCtx
	timer *time.Timer // Under cancelCtx.mu.

	deadline time.Time
	}

	func (c *timerCtx) Deadline() (deadline time.Time, ok bool) {
	return c.deadline, true
	}

	func (c *timerCtx) String() string {
	return contextName(c.cancelCtx.Context) + ".WithDeadline(" +
	c.deadline.String() + " [" +
	time.Until(c.deadline).String() + "])"
	}

	func (c *timerCtx) cancel(removeFromParent bool, err error) {
	c.cancelCtx.cancel(false, err)
	if removeFromParent {
	// Remove this timerCtx from its parent cancelCtx's children.
	removeChild(c.cancelCtx.Context, c)
	}
	c.mu.Lock()
	if c.timer != nil {
	c.timer.Stop()
	c.timer = nil
	}
	c.mu.Unlock()
	}

	// WithTimeout returns WithDeadline(parent, time.Now().Add(timeout)).
	//
	// Canceling this context releases resources associated with it, so code should
	// call cancel as soon as the operations running in this Context complete:
	//
	// func slowOperationWithTimeout(ctx context.Context) (Result, error) {
	// ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)
	// defer cancel() // releases resources if slowOperation completes before timeout elapses
	// return slowOperation(ctx)
	// }
	func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
	return WithDeadline(parent, time.Now().Add(timeout))
	}

	// WithValue returns a copy of parent in which the value associated with key is
	// val.
	//
	// Use context Values only for request-scoped data that transits processes and
	// APIs, not for passing optional parameters to functions.
	//
	// The provided key must be comparable and should not be of type
	// string or any other built-in type to avoid collisions between
	// packages using context. Users of WithValue should define their own
	// types for keys. To avoid allocating when assigning to an
	// interface{}, context keys often have concrete type
	// struct{}. Alternatively, exported context key variables' static
	// type should be a pointer or interface.
	func WithValue(parent Context, key, val interface{}) Context {
	if parent == nil {
	panic("cannot create context from nil parent")
	}
	if key == nil {
	panic("nil key")
	}
	if !reflectlite.TypeOf(key).Comparable() {
	panic("key is not comparable")
	}
	return &valueCtx{parent, key, val}
	}

	// A valueCtx carries a key-value pair. It implements Value for that key and
	// delegates all other calls to the embedded Context.
	type valueCtx struct {
	Context
	key, val interface{}
	}

	// stringify tries a bit to stringify v, without using fmt, since we don't
	// want context depending on the unicode tables. This is only used by
	// *valueCtx.String().
	func stringify(v interface{}) string {
	switch s := v.(type) {
	case stringer:
	return s.String()
	case string:
	return s
	}
	return "<not Stringer>"
	}

	func (c *valueCtx) String() string {
	return contextName(c.Context) + ".WithValue(type " +
	reflectlite.TypeOf(c.key).String() +
	", val " + stringify(c.val) + ")"
	}

	func (c *valueCtx) Value(key interface{}) interface{} {
	if c.key == key {
	return c.val
	}
	return c.Context.Value(key)
	}