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// Package context has been superseded by the standard library [context] package.
  6//
  7// Deprecated: Use the standard library context package instead.
  8package context
  9
 10import (
 11	"context" // standard library's context, as of Go 1.7
 12	"time"
 13)
 14
 15// A Context carries a deadline, a cancellation signal, and other values across
 16// API boundaries.
 17//
 18// Context's methods may be called by multiple goroutines simultaneously.
 19//
 20//go:fix inline
 21type Context = context.Context
 22
 23// Canceled is the error returned by [Context.Err] when the context is canceled
 24// for some reason other than its deadline passing.
 25//
 26//go:fix inline
 27var Canceled = context.Canceled
 28
 29// DeadlineExceeded is the error returned by [Context.Err] when the context is canceled
 30// due to its deadline passing.
 31//
 32//go:fix inline
 33var DeadlineExceeded = context.DeadlineExceeded
 34
 35// Background returns a non-nil, empty Context. It is never canceled, has no
 36// values, and has no deadline. It is typically used by the main function,
 37// initialization, and tests, and as the top-level Context for incoming
 38// requests.
 39//
 40//go:fix inline
 41func Background() Context { return context.Background() }
 42
 43// TODO returns a non-nil, empty Context. Code should use context.TODO when
 44// it's unclear which Context to use or it is not yet available (because the
 45// surrounding function has not yet been extended to accept a Context
 46// parameter).
 47//
 48//go:fix inline
 49func TODO() Context { return context.TODO() }
 50
 51// A CancelFunc tells an operation to abandon its work.
 52// A CancelFunc does not wait for the work to stop.
 53// A CancelFunc may be called by multiple goroutines simultaneously.
 54// After the first call, subsequent calls to a CancelFunc do nothing.
 55type CancelFunc = context.CancelFunc
 56
 57// WithCancel returns a derived context that points to the parent context
 58// but has a new Done channel. The returned context's Done channel is closed
 59// when the returned cancel function is called or when the parent context's
 60// Done channel is closed, whichever happens first.
 61//
 62// Canceling this context releases resources associated with it, so code should
 63// call cancel as soon as the operations running in this [Context] complete.
 64//
 65//go:fix inline
 66func WithCancel(parent Context) (ctx Context, cancel CancelFunc) {
 67	return context.WithCancel(parent)
 68}
 69
 70// WithDeadline returns a derived context that points to the parent context
 71// but has the deadline adjusted to be no later than d. If the parent's
 72// deadline is already earlier than d, WithDeadline(parent, d) is semantically
 73// equivalent to parent. The returned [Context.Done] channel is closed when
 74// the deadline expires, when the returned cancel function is called,
 75// or when the parent context's Done channel is closed, whichever happens first.
 76//
 77// Canceling this context releases resources associated with it, so code should
 78// call cancel as soon as the operations running in this [Context] complete.
 79//
 80//go:fix inline
 81func WithDeadline(parent Context, d time.Time) (Context, CancelFunc) {
 82	return context.WithDeadline(parent, d)
 83}
 84
 85// WithTimeout returns WithDeadline(parent, time.Now().Add(timeout)).
 86//
 87// Canceling this context releases resources associated with it, so code should
 88// call cancel as soon as the operations running in this [Context] complete:
 89//
 90//	func slowOperationWithTimeout(ctx context.Context) (Result, error) {
 91//		ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)
 92//		defer cancel()  // releases resources if slowOperation completes before timeout elapses
 93//		return slowOperation(ctx)
 94//	}
 95//
 96//go:fix inline
 97func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
 98	return context.WithTimeout(parent, timeout)
 99}
100
101// WithValue returns a derived context that points to the parent Context.
102// In the derived context, the value associated with key is val.
103//
104// Use context Values only for request-scoped data that transits processes and
105// APIs, not for passing optional parameters to functions.
106//
107// The provided key must be comparable and should not be of type
108// string or any other built-in type to avoid collisions between
109// packages using context. Users of WithValue should define their own
110// types for keys. To avoid allocating when assigning to an
111// interface{}, context keys often have concrete type
112// struct{}. Alternatively, exported context key variables' static
113// type should be a pointer or interface.
114//
115//go:fix inline
116func WithValue(parent Context, key, val interface{}) Context {
117	return context.WithValue(parent, key, val)
118}