vendor/golang.org/x/net/context/pre_go19.go

   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 // +build !go1.9
   6
   7 package context
   8
   9 import "time"
  10
  11 // A Context carries a deadline, a cancelation signal, and other values across
  12 // API boundaries.
  13 //
  14 // Context's methods may be called by multiple goroutines simultaneously.
  15 type Context interface {
  16         // Deadline returns the time when work done on behalf of this context
  17         // should be canceled. Deadline returns ok==false when no deadline is
  18         // set. Successive calls to Deadline return the same results.
  19         Deadline() (deadline time.Time, ok bool)
  20
  21         // Done returns a channel that's closed when work done on behalf of this
  22         // context should be canceled. Done may return nil if this context can
  23         // never be canceled. Successive calls to Done return the same value.
  24         //
  25         // WithCancel arranges for Done to be closed when cancel is called;
  26         // WithDeadline arranges for Done to be closed when the deadline
  27         // expires; WithTimeout arranges for Done to be closed when the timeout
  28         // elapses.
  29         //
  30         // Done is provided for use in select statements:
  31         //
  32         //  // Stream generates values with DoSomething and sends them to out
  33         //  // until DoSomething returns an error or ctx.Done is closed.
  34         //  func Stream(ctx context.Context, out chan<- Value) error {
  35         //      for {
  36         //              v, err := DoSomething(ctx)
  37         //              if err != nil {
  38         //                      return err
  39         //              }
  40         //              select {
  41         //              case <-ctx.Done():
  42         //                      return ctx.Err()
  43         //              case out <- v:
  44         //              }
  45         //      }
  46         //  }
  47         //
  48         // See http://blog.golang.org/pipelines for more examples of how to use
  49         // a Done channel for cancelation.
  50         Done() <-chan struct{}
  51
  52         // Err returns a non-nil error value after Done is closed. Err returns
  53         // Canceled if the context was canceled or DeadlineExceeded if the
  54         // context's deadline passed. No other values for Err are defined.
  55         // After Done is closed, successive calls to Err return the same value.
  56         Err() error
  57
  58         // Value returns the value associated with this context for key, or nil
  59         // if no value is associated with key. Successive calls to Value with
  60         // the same key returns the same result.
  61         //
  62         // Use context values only for request-scoped data that transits
  63         // processes and API boundaries, not for passing optional parameters to
  64         // functions.
  65         //
  66         // A key identifies a specific value in a Context. Functions that wish
  67         // to store values in Context typically allocate a key in a global
  68         // variable then use that key as the argument to context.WithValue and
  69         // Context.Value. A key can be any type that supports equality;
  70         // packages should define keys as an unexported type to avoid
  71         // collisions.
  72         //
  73         // Packages that define a Context key should provide type-safe accessors
  74         // for the values stores using that key:
  75         //
  76         //      // Package user defines a User type that's stored in Contexts.
  77         //      package user
  78         //
  79         //      import "golang.org/x/net/context"
  80         //
  81         //      // User is the type of value stored in the Contexts.
  82         //      type User struct {...}
  83         //
  84         //      // key is an unexported type for keys defined in this package.
  85         //      // This prevents collisions with keys defined in other packages.
  86         //      type key int
  87         //
  88         //      // userKey is the key for user.User values in Contexts. It is
  89         //      // unexported; clients use user.NewContext and user.FromContext
  90         //      // instead of using this key directly.
  91         //      var userKey key = 0
  92         //
  93         //      // NewContext returns a new Context that carries value u.
  94         //      func NewContext(ctx context.Context, u *User) context.Context {
  95         //              return context.WithValue(ctx, userKey, u)
  96         //      }
  97         //
  98         //      // FromContext returns the User value stored in ctx, if any.
  99         //      func FromContext(ctx context.Context) (*User, bool) {
 100         //              u, ok := ctx.Value(userKey).(*User)
 101         //              return u, ok
 102         //      }
 103         Value(key interface{}) interface{}
 104 }
 105
 106 // A CancelFunc tells an operation to abandon its work.
 107 // A CancelFunc does not wait for the work to stop.
 108 // After the first call, subsequent calls to a CancelFunc do nothing.
 109 type CancelFunc func()