[release-branch.go1.18] go/types: clarify that contexts do not guarantee deduplication

Documentation around the use of types.Context is unclear about whether
contexts guarantee deduplication of identical instances. Add explicit
disclaimers that this is not the case.

Fixes golang/go#52028

Change-Id: I6651587315d3cbf9e8d70a69d3e2ec5cedd00da5
Reviewed-on: https://go-review.googlesource.com/c/go/+/396536
Trust: Robert Findley <rfindley@google.com>
Run-TryBot: Robert Findley <rfindley@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Robert Griesemer <gri@golang.org>
(cherry picked from commit 83327b4ae41cf1ef17fb4df4dc395cf17efc6375)
Reviewed-on: https://go-review.googlesource.com/c/go/+/397674
Reviewed-by: Russ Cox <rsc@golang.org>

4 files changed, 12 insertions, 8 deletions

diff --git a/src/cmd/compile/internal/types2/context.go b/src/cmd/compile/internal/types2/context.go
index 7abea6b654..2d790fe5dd 100644
--- a/src/cmd/compile/internal/types2/context.go
+++ b/src/cmd/compile/internal/types2/context.go
@@ -12,11 +12,12 @@ import (
 	"sync"
 )
 
-// An Context is an opaque type checking context. It may be used to share
+// A Context is an opaque type checking context. It may be used to share
 // identical type instances across type-checked packages or calls to
-// Instantiate.
+// Instantiate. Contexts are safe for concurrent use.
 //
-// It is safe for concurrent use.
+// The use of a shared context does not guarantee that identical instances are
+// deduplicated in all cases.
 type Context struct {
 	mu        sync.Mutex
 	typeMap   map[string][]ctxtEntry // type hash -> instances entries
diff --git a/src/cmd/compile/internal/types2/instantiate.go b/src/cmd/compile/internal/types2/instantiate.go
index 9eced489dc..2dc82d852e 100644
--- a/src/cmd/compile/internal/types2/instantiate.go
+++ b/src/cmd/compile/internal/types2/instantiate.go
@@ -24,7 +24,8 @@ import (
 // previous instances with the same identity. As a special case, generic
 // *Signature origin types are only considered identical if they are pointer
 // equivalent, so that instantiating distinct (but possibly identical)
-// signatures will yield different instances.
+// signatures will yield different instances. The use of a shared context does
+// not guarantee that identical instances are deduplicated in all cases.
 //
 // If validate is set, Instantiate verifies that the number of type arguments
 // and parameters match, and that the type arguments satisfy their
diff --git a/src/go/types/context.go b/src/go/types/context.go
index ff4bf89f3c..692b3a6682 100644
--- a/src/go/types/context.go
+++ b/src/go/types/context.go
@@ -12,11 +12,12 @@ import (
 	"sync"
 )
 
-// An Context is an opaque type checking context. It may be used to share
+// A Context is an opaque type checking context. It may be used to share
 // identical type instances across type-checked packages or calls to
-// Instantiate.
+// Instantiate. Contexts are safe for concurrent use.
 //
-// It is safe for concurrent use.
+// The use of a shared context does not guarantee that identical instances are
+// deduplicated in all cases.
 type Context struct {
 	mu        sync.Mutex
 	typeMap   map[string][]ctxtEntry // type hash -> instances entries
diff --git a/src/go/types/instantiate.go b/src/go/types/instantiate.go
index a481746657..8813217eca 100644
--- a/src/go/types/instantiate.go
+++ b/src/go/types/instantiate.go
@@ -24,7 +24,8 @@ import (
 // previous instances with the same identity. As a special case, generic
 // *Signature origin types are only considered identical if they are pointer
 // equivalent, so that instantiating distinct (but possibly identical)
-// signatures will yield different instances.
+// signatures will yield different instances. The use of a shared context does
+// not guarantee that identical instances are deduplicated in all cases.
 //
 // If validate is set, Instantiate verifies that the number of type arguments
 // and parameters match, and that the type arguments satisfy their