sync: document that RWMutex read locks may not be held recursively
Fixes #15418
Change-Id: Ibc51d602eb28819d0e44e5ca13a5c61573e4111c
Reviewed-on: https://go-review.googlesource.com/23570
Reviewed-by: Dmitry Vyukov <dvyukov@google.com>
diff --git a/src/sync/rwmutex.go b/src/sync/rwmutex.go
index 455d412..6734360 100644
--- a/src/sync/rwmutex.go
+++ b/src/sync/rwmutex.go
@@ -11,13 +11,17 @@
)
// An RWMutex is a reader/writer mutual exclusion lock.
-// The lock can be held by an arbitrary number of readers
-// or a single writer.
-// RWMutexes can be created as part of other
-// structures; the zero value for a RWMutex is
-// an unlocked mutex.
+// The lock can be held by an arbitrary number of readers or a single writer.
+// RWMutexes can be created as part of other structures;
+// the zero value for a RWMutex is an unlocked mutex.
//
// 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.
type RWMutex struct {
w Mutex // held if there are pending writers
writerSem uint32 // semaphore for writers to wait for completing readers
@@ -73,9 +77,6 @@
// Lock locks rw for writing.
// If the lock is already locked for reading or writing,
// Lock blocks until the lock is available.
-// To ensure that the lock eventually becomes available,
-// a blocked Lock call excludes new readers from acquiring
-// the lock.
func (rw *RWMutex) Lock() {
if race.Enabled {
_ = rw.w.state
