sync: document RWMutex locks cannot be upgraded / downgraded

Fixes #38859

Change-Id: I9f4f6fa4cb529aaadfb3812e3a5c0da982a95f68
Reviewed-on: https://go-review.googlesource.com/c/go/+/633415
Auto-Submit: Ian Lance Taylor <iant@google.com>
Reviewed-by: Michael Knyszek <mknyszek@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>

diff --git a/src/sync/rwmutex.go b/src/sync/rwmutex.go
index 7fe096dbd892da10b1df4cf3d490d1a2d80eb765..3fbfd28d7f128a1742bec45c80ec2c1cd15a0820 100644 (file)
--- a/src/sync/rwmutex.go
+++ b/src/sync/rwmutex.go
@@ -24,6 +24,8 @@ import (
 // the writer has acquired (and released) the lock, to ensure that
 // the lock eventually becomes available to the writer.
 // Note that this prohibits recursive read-locking.
+// A [RWMutex.RLock] cannot be upgraded into a [RWMutex.Lock],
+// nor can a [RWMutex.Lock] be downgraded into a [RWMutex.RLock].
 //
 // In the terminology of [the Go memory model],
 // the n'th call to [RWMutex.Unlock] “synchronizes before” the m'th call to Lock