context.go 6.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156
  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. // Package context defines the Context type, which carries deadlines,
  5. // cancelation signals, and other request-scoped values across API boundaries
  6. // and between processes.
  7. //
  8. // Incoming requests to a server should create a Context, and outgoing calls to
  9. // servers should accept a Context. The chain of function calls between must
  10. // propagate the Context, optionally replacing it with a modified copy created
  11. // using WithDeadline, WithTimeout, WithCancel, or WithValue.
  12. //
  13. // Programs that use Contexts should follow these rules to keep interfaces
  14. // consistent across packages and enable static analysis tools to check context
  15. // propagation:
  16. //
  17. // Do not store Contexts inside a struct type; instead, pass a Context
  18. // explicitly to each function that needs it. The Context should be the first
  19. // parameter, typically named ctx:
  20. //
  21. // func DoSomething(ctx context.Context, arg Arg) error {
  22. // // ... use ctx ...
  23. // }
  24. //
  25. // Do not pass a nil Context, even if a function permits it. Pass context.TODO
  26. // if you are unsure about which Context to use.
  27. //
  28. // Use context Values only for request-scoped data that transits processes and
  29. // APIs, not for passing optional parameters to functions.
  30. //
  31. // The same Context may be passed to functions running in different goroutines;
  32. // Contexts are safe for simultaneous use by multiple goroutines.
  33. //
  34. // See http://blog.golang.org/context for example code for a server that uses
  35. // Contexts.
  36. package context // import "golang.org/x/net/context"
  37. import "time"
  38. // A Context carries a deadline, a cancelation signal, and other values across
  39. // API boundaries.
  40. //
  41. // Context's methods may be called by multiple goroutines simultaneously.
  42. type Context interface {
  43. // Deadline returns the time when work done on behalf of this context
  44. // should be canceled. Deadline returns ok==false when no deadline is
  45. // set. Successive calls to Deadline return the same results.
  46. Deadline() (deadline time.Time, ok bool)
  47. // Done returns a channel that's closed when work done on behalf of this
  48. // context should be canceled. Done may return nil if this context can
  49. // never be canceled. Successive calls to Done return the same value.
  50. //
  51. // WithCancel arranges for Done to be closed when cancel is called;
  52. // WithDeadline arranges for Done to be closed when the deadline
  53. // expires; WithTimeout arranges for Done to be closed when the timeout
  54. // elapses.
  55. //
  56. // Done is provided for use in select statements:
  57. //
  58. // // Stream generates values with DoSomething and sends them to out
  59. // // until DoSomething returns an error or ctx.Done is closed.
  60. // func Stream(ctx context.Context, out chan<- Value) error {
  61. // for {
  62. // v, err := DoSomething(ctx)
  63. // if err != nil {
  64. // return err
  65. // }
  66. // select {
  67. // case <-ctx.Done():
  68. // return ctx.Err()
  69. // case out <- v:
  70. // }
  71. // }
  72. // }
  73. //
  74. // See http://blog.golang.org/pipelines for more examples of how to use
  75. // a Done channel for cancelation.
  76. Done() <-chan struct{}
  77. // Err returns a non-nil error value after Done is closed. Err returns
  78. // Canceled if the context was canceled or DeadlineExceeded if the
  79. // context's deadline passed. No other values for Err are defined.
  80. // After Done is closed, successive calls to Err return the same value.
  81. Err() error
  82. // Value returns the value associated with this context for key, or nil
  83. // if no value is associated with key. Successive calls to Value with
  84. // the same key returns the same result.
  85. //
  86. // Use context values only for request-scoped data that transits
  87. // processes and API boundaries, not for passing optional parameters to
  88. // functions.
  89. //
  90. // A key identifies a specific value in a Context. Functions that wish
  91. // to store values in Context typically allocate a key in a global
  92. // variable then use that key as the argument to context.WithValue and
  93. // Context.Value. A key can be any type that supports equality;
  94. // packages should define keys as an unexported type to avoid
  95. // collisions.
  96. //
  97. // Packages that define a Context key should provide type-safe accessors
  98. // for the values stores using that key:
  99. //
  100. // // Package user defines a User type that's stored in Contexts.
  101. // package user
  102. //
  103. // import "golang.org/x/net/context"
  104. //
  105. // // User is the type of value stored in the Contexts.
  106. // type User struct {...}
  107. //
  108. // // key is an unexported type for keys defined in this package.
  109. // // This prevents collisions with keys defined in other packages.
  110. // type key int
  111. //
  112. // // userKey is the key for user.User values in Contexts. It is
  113. // // unexported; clients use user.NewContext and user.FromContext
  114. // // instead of using this key directly.
  115. // var userKey key = 0
  116. //
  117. // // NewContext returns a new Context that carries value u.
  118. // func NewContext(ctx context.Context, u *User) context.Context {
  119. // return context.WithValue(ctx, userKey, u)
  120. // }
  121. //
  122. // // FromContext returns the User value stored in ctx, if any.
  123. // func FromContext(ctx context.Context) (*User, bool) {
  124. // u, ok := ctx.Value(userKey).(*User)
  125. // return u, ok
  126. // }
  127. Value(key interface{}) interface{}
  128. }
  129. // Background returns a non-nil, empty Context. It is never canceled, has no
  130. // values, and has no deadline. It is typically used by the main function,
  131. // initialization, and tests, and as the top-level Context for incoming
  132. // requests.
  133. func Background() Context {
  134. return background
  135. }
  136. // TODO returns a non-nil, empty Context. Code should use context.TODO when
  137. // it's unclear which Context to use or it is not yet available (because the
  138. // surrounding function has not yet been extended to accept a Context
  139. // parameter). TODO is recognized by static analysis tools that determine
  140. // whether Contexts are propagated correctly in a program.
  141. func TODO() Context {
  142. return todo
  143. }
  144. // A CancelFunc tells an operation to abandon its work.
  145. // A CancelFunc does not wait for the work to stop.
  146. // After the first call, subsequent calls to a CancelFunc do nothing.
  147. type CancelFunc func()