// 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.

//go:build !go1.9

// +build !go1.9

package context

import "time"

// A Context carries a deadline, a cancelation 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.

	//

	// 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 http://blog.golang.org/pipelines for more examples of how to use

	// a Done channel for cancelation.

	Done() <-chan struct{}

	// Err returns a non-nil error value after Done is closed. Err returns

	// Canceled if the context was canceled or DeadlineExceeded if the

	// context's deadline passed. No other values for Err are defined.

	// After Done is closed, successive calls to Err return the same value.

	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 stores using that key:

	//

	// 	// Package user defines a User type that's stored in Contexts.

	// 	package user

	//

	// 	import "golang.org/x/net/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 = 0

	//

	// 	// 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{}

}

// A CancelFunc tells an operation to abandon its work.

// A CancelFunc does not wait for the work to stop.

// After the first call, subsequent calls to a CancelFunc do nothing.

type CancelFunc func()