From: Brad Fitzpatrick <bradfitz@golang.org>
Date: Fri, 11 Nov 2016 23:40:25 +0000 (+0000)
Subject: context: document appropriate WithValue key type more
X-Git-Tag: go1.8beta1~182
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=c921d8f39d6da1afd1550787464d27f015412194;p=gostls13.git

context: document appropriate WithValue key type more

Fixes #17826
Updates #17302

Change-Id: I7c1ebd965e679e7169a97e62d27ae3ede2473aa1
Reviewed-on: https://go-review.googlesource.com/33152
Reviewed-by: Ian Lance Taylor <iant@golang.org>
---

diff --git a/src/context/context.go b/src/context/context.go
index 54ad49a721..0aa7c24df9 100644
--- a/src/context/context.go
+++ b/src/context/context.go
@@ -443,9 +443,13 @@ func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
 // Use context Values only for request-scoped data that transits processes and
 // APIs, not for passing optional parameters to functions.
 //
-// The provided key must be comparable and should not be
-// of type string or any other built-in type.
-// Users of WithValue should define their own types for keys.
+// The provided key must be comparable and should not be of type
+// string or any other built-in type to avoid collisions between
+// packages using context. Users of WithValue should define their own
+// types for keys. To avoid allocating when assigning to an
+// interface{}, context keys often have concrete type
+// struct{}. Alternatively, exported context key variables' static
+// type should be a pointer or interface.
 func WithValue(parent Context, key, val interface{}) Context {
 	if key == nil {
 		panic("nil key")