sync: make another attempt at clarifying RWMutex double RLock rules

Updates #15418 (the original bug, fixed by https://golang.org/cl/23570)
Fixes #19460 (round two)

Change-Id: Iac4447daabb56e3b470046c489c22d588c20163e
Reviewed-on: https://go-review.googlesource.com/45697
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/sync/rwmutex.go b/src/sync/rwmutex.go
index a8607d91674a38901c026dfa033610f49db15804..94889149a1bc1151bcdc09820c5b2cd0999efbd7 100644 (file)
--- a/src/sync/rwmutex.go
+++ b/src/sync/rwmutex.go
@@ -16,11 +16,12 @@ import (
 //
 // An RWMutex must not be copied after first use.
 //
-// If a goroutine holds a RWMutex for reading, it must not expect this or any
-// other goroutine to be able to also take the read lock until the first read
-// lock is released. In particular, this prohibits recursive read locking.
-// This is to ensure that the lock eventually becomes available;
-// a blocked Lock call excludes new readers from acquiring the lock.
+// If a goroutine holds a RWMutex for reading and another goroutine might
+// call Lock, no goroutine should expect to be able to acquire a read lock
+// until the initial read lock is released. In particular, this prohibits
+// recursive read locking. This is to ensure that the lock eventually becomes
+// available; a blocked Lock call excludes new readers from acquiring the
+// lock.
 type RWMutex struct {
        w           Mutex  // held if there are pending writers
        writerSem   uint32 // semaphore for writers to wait for completing readers
@@ -32,6 +33,10 @@ type RWMutex struct {
 const rwmutexMaxReaders = 1 << 30
 
 // RLock locks rw for reading.
+//
+// It should not be used for recursive read locking; a blocked Lock
+// call excludes new readers from acquiring the lock. See the
+// documentation on the RWMutex type.
 func (rw *RWMutex) RLock() {
        if race.Enabled {
                _ = rw.w.state