diff options
| author | Sameer Ajmani <sameer@golang.org> | 2016-06-14 16:48:42 -0400 |
|---|---|---|
| committer | Sameer Ajmani <sameer@golang.org> | 2016-06-15 00:30:46 +0000 |
| commit | c4692da9231c244a1275d42055e703b3f1dac25b (patch) | |
| tree | bc81de8b63e2e3156da4698223f7b09d6e12dfb3 | |
| parent | 68697a3e82e19fef04c6af4a02340a1aa6e3bcf2 (diff) | |
| download | go-c4692da9231c244a1275d42055e703b3f1dac25b.tar.gz go-c4692da9231c244a1275d42055e703b3f1dac25b.zip | |
context: document how to release resources associated with Contexts.
Some users don't realize that creating a Context with a CancelFunc
attaches a subtree to the parent, and that that subtree is not released
until the CancelFunc is called or the parent is canceled. Make this
clear early in the package docs, so that people learning about this
package have the right conceptual model.
Change-Id: I7c77a546c19c3751dd1f3a5bc827ad106dd1afbf
Reviewed-on: https://go-review.googlesource.com/24090
Reviewed-by: Alan Donovan <adonovan@google.com>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
| -rw-r--r-- | src/context/context.go | 14 |
1 files changed, 11 insertions, 3 deletions
diff --git a/src/context/context.go b/src/context/context.go index fc2a56ebff..91972cc66a 100644 --- a/src/context/context.go +++ b/src/context/context.go @@ -7,9 +7,17 @@ // 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 must -// propagate the Context, optionally replacing it with a modified copy created -// using WithDeadline, WithTimeout, WithCancel, or WithValue. +// 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. These +// Context values form a tree: when a Context is canceled, all Contexts derived +// from it are also canceled. +// +// The WithCancel, WithDeadline, and WithTimeout functions return a derived +// Context and a CancelFunc. Calling the CancelFunc cancels the new Context and +// any Contexts derived from it, removes the Context from the parent's tree, and +// stops any associated timers. Failing to call the CancelFunc leaks the +// associated resources until the parent Context is canceled or the timer fires. // // Programs that use Contexts should follow these rules to keep interfaces // consistent across packages and enable static analysis tools to check context |