From c4692da9231c244a1275d42055e703b3f1dac25b Mon Sep 17 00:00:00 2001 From: Sameer Ajmani Date: Tue, 14 Jun 2016 16:48:42 -0400 Subject: [PATCH] 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 Reviewed-by: Ian Lance Taylor --- src/context/context.go | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/src/context/context.go b/src/context/context.go index fc2a56ebffc20..91972cc66a8cb 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