sync: deemphasize goroutines in RWMutex documentation

[bcmills]

sync.RWMutex performs no goroutine-specific accounting (see also #9201) and cannot be locked reentrantly.

Despite the fact that a sync.RWMutex is not held by a specific goroutine, the documentation for the RWMutex type is currently phrased in terms of goroutines holding the lock (emphasis mine):

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.

This stands in contrast to the documentation for the Unlock method, which states more clearly:

As with Mutexes, a locked RWMutex is not associated with a particular goroutine. One goroutine may RLock (Lock) a RWMutex and then arrange for another goroutine to RUnlock (Unlock) it.

The type-level documentation should be rewritten so that it does not imply that the existing holder of the RWMutex is “a goroutine”.

[bcmills]

Also, the documentation for the RLock method currently states (emphasis mine):

It should not be used for recursive read locking; a blocked Lock call excludes new readers from acquiring the lock.

The use of “should” implies that the RLock method potentially could be used for recursive read-locking, which is not actually the case.

[gopherbot]

Change https://golang.org/cl/256737 mentions this issue: sync: deemphasize goroutines in RWMutex documentation