From d805c22e75cd4007a029f17a735e5992c741da16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=AD?= Date: Thu, 16 Nov 2023 22:06:58 +0000 Subject: [PATCH] cue: explicitly document values are not safe for concurrent use MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Users are regularly confused by data races or other panics caused by the concurrent use of the API in this package, particularly when making concurrent use of values. Even though Go APIs are generally not safe for concurrent use unless documented otherwise, per https://go.dev/issue/30632, it can be easy to forget that since concurrency is so common in Go. Add an explicit reminder about it, following our reasoning from the last time we discussed the current state of concurrency in the API. While here, make a few godoc link tweaks. Signed-off-by: Daniel Martí Change-Id: I8a7d3a5855e41781fb188adf79fd0bb4171d01e9 Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1172256 Reviewed-by: Roger Peppe TryBot-Result: CUEcueckoo Reviewed-by: Marcel van Lohuizen Unity-Result: CUE porcuepine --- cue/build.go | 2 +- cue/cue.go | 16 +++++++++------- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/cue/build.go b/cue/build.go index 6dea7a78fe0..287a4d0d596 100644 --- a/cue/build.go +++ b/cue/build.go @@ -117,7 +117,7 @@ func (r *hiddenRuntime) Build(p *build.Instance) (*Instance, error) { return r.complete(p, v) } -// Deprecated: [Context.BuildInstances]. The use of [Instance] is being phased out. +// Deprecated: use [Context.BuildInstances]. The use of [Instance] is being phased out. func Build(instances []*build.Instance) []*Instance { if len(instances) == 0 { panic("cue: list of instances must not be empty") diff --git a/cue/cue.go b/cue/cue.go index 0dbac258a6e..ac689175174 100644 --- a/cue/cue.go +++ b/cue/cue.go @@ -14,9 +14,11 @@ // Package cue is the main API for CUE evaluation. // -// Value is the main type that represents CUE evaluations. Values are created -// with a cue.Context. Only values created from the same Context can be -// involved in the same operation. +// [Value] is the main type that represents CUE evaluations. +// Values are created with a [cuecontext.Context]. +// Only values created from the same Context can be involved in the same operation. +// Values created from the same Context are not safe for concurrent use, +// which we intend to change in the future. // // A Context defines the set of active packages, the translations of field // names to unique codes, as well as the set of builtins. Use @@ -30,10 +32,10 @@ // Note that the following types are DEPRECATED and their usage should be // avoided if possible: // -// FieldInfo -// Instance -// Runtime -// Struct +// [FieldInfo] +// [Instance] +// [Runtime] +// [Struct] // // Many types also have deprecated methods. Code that already uses deprecated // methods can keep using them for at least some time. We aim to provide a