From b3f98d7a42d04f6f173cd61ce3fe2106e4877496 Mon Sep 17 00:00:00 2001 From: Andrew Gerrand Date: Mon, 30 May 2016 15:17:14 +1000 Subject: [PATCH] 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 --- src/sync/rwmutex.go | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/sync/rwmutex.go b/src/sync/rwmutex.go index 455d412330034e..6734360e37a5e5 100644 --- a/src/sync/rwmutex.go +++ b/src/sync/rwmutex.go @@ -11,13 +11,17 @@ import ( ) // 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 @@ func (rw *RWMutex) RUnlock() { // 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