Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

sync: deemphasize goroutines in RWMutex documentation #41555

Open
bcmills opened this issue Sep 22, 2020 · 2 comments
Open

sync: deemphasize goroutines in RWMutex documentation #41555

bcmills opened this issue Sep 22, 2020 · 2 comments

Comments

@bcmills
Copy link
Member

@bcmills bcmills commented Sep 22, 2020

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
Copy link
Member Author

@bcmills bcmills commented Sep 22, 2020

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
Copy link

@gopherbot gopherbot commented Sep 23, 2020

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants