go/types, types2: add commentary on (non-)guarantees when using contexts

Change-Id: I29347e340725fa2892eb115b530de82969835412
Reviewed-on: https://go-review.googlesource.com/c/go/+/396776
Trust: Robert Findley <rfindley@google.com>
Run-TryBot: Robert Findley <rfindley@google.com>
Reviewed-by: Robert Griesemer <gri@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>

diff --git a/src/cmd/compile/internal/types2/context.go b/src/cmd/compile/internal/types2/context.go
index 2d790fe5dddbbf30aa025241daeadfb3a7c2c595..ae39c7b83097a9339c8e6cc120ca26e2eca5c843 100644 (file)
--- a/src/cmd/compile/internal/types2/context.go
+++ b/src/cmd/compile/internal/types2/context.go
@@ -12,6 +12,26 @@ import (
        "sync"
 )
 
+// This file contains a definition of the type-checking context; an opaque type
+// that may be supplied by users during instantiation.
+//
+// Contexts serve two purposes:
+//  - reduce the duplication of identical instances
+//  - short-circuit instantiation cycles
+//
+// For the latter purpose, we must always have a context during instantiation,
+// whether or not it is supplied by the user. For both purposes, it must be the
+// case that hashing a pointer-identical type produces consistent results
+// (somewhat obviously).
+//
+// However, neither of these purposes require that our hash is perfect, and so
+// this was not an explicit design goal of the context type. In fact, due to
+// concurrent use it is convenient not to guarantee de-duplication.
+//
+// Nevertheless, in the future it could be helpful to allow users to leverage
+// contexts to canonicalize instances, and it would probably be possible to
+// achieve such a guarantee.
+
 // 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. Contexts are safe for concurrent use.

diff --git a/src/go/types/context.go b/src/go/types/context.go
index 692b3a66828a9c593432c1a8a4ad92fc9be0f626..15756b062d97664e9bdeae9ac5e930e7cefa9568 100644 (file)
--- a/src/go/types/context.go
+++ b/src/go/types/context.go
@@ -12,6 +12,26 @@ import (
        "sync"
 )
 
+// This file contains a definition of the type-checking context; an opaque type
+// that may be supplied by users during instantiation.
+//
+// Contexts serve two purposes:
+//  - reduce the duplication of identical instances
+//  - short-circuit instantiation cycles
+//
+// For the latter purpose, we must always have a context during instantiation,
+// whether or not it is supplied by the user. For both purposes, it must be the
+// case that hashing a pointer-identical type produces consistent results
+// (somewhat obviously).
+//
+// However, neither of these purposes require that our hash is perfect, and so
+// this was not an explicit design goal of the context type. In fact, due to
+// concurrent use it is convenient not to guarantee de-duplication.
+//
+// Nevertheless, in the future it could be helpful to allow users to leverage
+// contexts to canonicalize instances, and it would probably be possible to
+// achieve such a guarantee.
+
 // 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. Contexts are safe for concurrent use.