sync/atomic: document that atomic types should not be copied

Change-Id: I3c557d02cd676a389b5c5ea70ed92c8959041e3b
GitHub-Last-Rev: 8732da19a64853834ca155cafc1d7b2967290c31
GitHub-Pull-Request: golang/go#63256
Reviewed-on: https://go-review.googlesource.com/c/go/+/531375
Reviewed-by: Junyang Shao <shaojunyang@google.com>
Reviewed-by: David Chase <drchase@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Sean Liao <sean@liao.dev>
Reviewed-by: Sean Liao <sean@liao.dev>

diff --git a/src/sync/atomic/type.go b/src/sync/atomic/type.go
index f487cb9c5f7eaaf35ee0b5b6d02636f2b9831779..40a29fed8ce3bb7150a24b2f9106441ef6af35ce 100644 (file)
--- a/src/sync/atomic/type.go
+++ b/src/sync/atomic/type.go
@@ -8,6 +8,8 @@ import "unsafe"
 
 // A Bool is an atomic boolean value.
 // The zero value is false.
+//
+// Bool must not be copied after first use.
 type Bool struct {
        _ noCopy
        v uint32
@@ -40,6 +42,8 @@ func b32(b bool) uint32 {
 var _ = &Pointer[int]{}
 
 // A Pointer is an atomic pointer of type *T. The zero value is a nil *T.
+//
+// Pointer must not be copied after first use.
 type Pointer[T any] struct {
        // Mention *T in a field to disallow conversion between Pointer types.
        // See go.dev/issue/56603 for more details.
@@ -65,6 +69,8 @@ func (x *Pointer[T]) CompareAndSwap(old, new *T) (swapped bool) {
 }
 
 // An Int32 is an atomic int32. The zero value is zero.
+//
+// Int32 must not be copied after first use.
 type Int32 struct {
        _ noCopy
        v int32
@@ -96,6 +102,8 @@ func (x *Int32) And(mask int32) (old int32) { return AndInt32(&x.v, mask) }
 func (x *Int32) Or(mask int32) (old int32) { return OrInt32(&x.v, mask) }
 
 // An Int64 is an atomic int64. The zero value is zero.
+//
+// Int64 must not be copied after first use.
 type Int64 struct {
        _ noCopy
        _ align64
@@ -128,6 +136,8 @@ func (x *Int64) And(mask int64) (old int64) { return AndInt64(&x.v, mask) }
 func (x *Int64) Or(mask int64) (old int64) { return OrInt64(&x.v, mask) }
 
 // A Uint32 is an atomic uint32. The zero value is zero.
+//
+// Uint32 must not be copied after first use.
 type Uint32 struct {
        _ noCopy
        v uint32
@@ -159,6 +169,8 @@ func (x *Uint32) And(mask uint32) (old uint32) { return AndUint32(&x.v, mask) }
 func (x *Uint32) Or(mask uint32) (old uint32) { return OrUint32(&x.v, mask) }
 
 // A Uint64 is an atomic uint64. The zero value is zero.
+//
+// Uint64 must not be copied after first use.
 type Uint64 struct {
        _ noCopy
        _ align64
@@ -191,6 +203,8 @@ func (x *Uint64) And(mask uint64) (old uint64) { return AndUint64(&x.v, mask) }
 func (x *Uint64) Or(mask uint64) (old uint64) { return OrUint64(&x.v, mask) }
 
 // A Uintptr is an atomic uintptr. The zero value is zero.
+//
+// Uintptr must not be copied after first use.
 type Uintptr struct {
        _ noCopy
        v uintptr