strings,bytes: add internal docs about perennial noCopy questions

Updates #26462
Updates #25907
Updates #47276
Updates #48398

Change-Id: Ic64fc8d0c284f6e5aa383a8d417fa5768dcd7925
Reviewed-on: https://go-review.googlesource.com/c/go/+/674096
Auto-Submit: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Michael Knyszek <mknyszek@google.com>

diff --git a/src/bytes/buffer.go b/src/bytes/buffer.go
index f90d9eca0fe49611766d016f817237504da670b9..9684513942da88a3295765668bcef83a4807d5e2 100644 (file)
--- a/src/bytes/buffer.go
+++ b/src/bytes/buffer.go
@@ -21,6 +21,12 @@ type Buffer struct {
        buf      []byte // contents are the bytes buf[off : len(buf)]
        off      int    // read at &buf[off], write at &buf[len(buf)]
        lastRead readOp // last read operation, so that Unread* can work correctly.
+
+       // Copying and modifying a non-zero Buffer is prone to error,
+       // but we cannot employ the noCopy trick used by WaitGroup and Mutex,
+       // which causes vet's copylocks checker to report misuse, as vet
+       // cannot reliably distinguish the zero and non-zero cases.
+       // See #26462, #25907, #47276, #48398 for history.
 }
 
 // The readOp constants describe the last action performed on

diff --git a/src/strings/builder.go b/src/strings/builder.go
index e6df08c6f479ad5c13efec91c3646b49335b48f4..7ecef3176b2ce5755d63460001aac6ab9b583c4d 100644 (file)
--- a/src/strings/builder.go
+++ b/src/strings/builder.go
@@ -23,6 +23,12 @@ type Builder struct {
        buf []byte
 }
 
+// copyCheck implements a dynamic check to prevent modification after
+// copying a non-zero Builder, which would be unsafe (see #25907, #47276).
+//
+// We cannot add a noCopy field to Builder, to cause vet's copylocks
+// check to report copying, because copylocks cannot reliably
+// discriminate the zero and nonzero cases.
 func (b *Builder) copyCheck() {
        if b.addr == nil {
                // This hack works around a failing of Go's escape analysis