utils: Fix ShardedLock::write documentation copied from read#1292
Open
teddytennant wants to merge 1 commit into
Open
utils: Fix ShardedLock::write documentation copied from read#1292teddytennant wants to merge 1 commit into
teddytennant wants to merge 1 commit into
Conversation
The paragraph was copied verbatim from ShardedLock::read: it claimed write blocks only until there are no more writers and that other readers may be inside the lock when it returns. write acquires every shard exclusively, so it blocks while any readers or writers hold the lock, and no readers can be inside once it returns (as the method's own example demonstrates with try_read failing). Reword to match std::sync::RwLock::write.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Rewords the blocking-behavior paragraph in
ShardedLock::write's doc comment, which was copied verbatim fromreadand describes the wrong semantics.Why
The current text says
writeblocks "until there are no more writers which hold the lock" and that "there may be other readers currently inside the lock when this method returns". Both statements are true forreadbut wrong forwrite: it acquires every shard exclusively, so it also blocks while readers hold the lock, and no readers can be inside once it returns — the method's own example demonstrates this withtry_readfailing while the write guard is held. The new wording matchesstd::sync::RwLock::write, keeping the existing sentence about no ordering guarantees between contentious readers and writers.Testing
Doc-only, no behavior change.
cargo test --test sharded_lockincrossbeam-utils— 15 passedcargo test --doc sharded_lock— 9 passedrustfmt --check— clean