Skip to content

Clarify &mut-methods' docs on sync::OnceLock #140715

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

lukaslueg
Copy link
Contributor

@lukaslueg lukaslueg commented May 6, 2025

Three small changes to the docs of sync::OnceLock:

  • The docs for OnceLock::take() used to say "Safety is guaranteed by requiring a mutable reference." (emphasis mine). While technically correct, imho its not necessary to even mention safety - as opposed to unsafety - here: Safety never comes up wrt OnceLock, as there is (currently) no way to interact with a OnceLock in an unsafe way; there are no unsafe methods on OnceLock, so there is "safety" guarantee required anywhere. What we simply meant to say is "Synchronization is guaranteed...".
  • I've add that phrase to the other methods of OnceLock which take a &mut self, to highlight the fact that having a &mut OnceLock guarantees that synchronization with other threads is not required. This is the same as with Mutex::get_mut(), Cell::get_mut(), and others.
  • In that spirit, the half-sentence "or being initialized" was removed from get_mut(), as there is no way that the OnceLock is being initialized while we are holding &mut to it. Probably a copy&paste from .get()

@rustbot
Copy link
Collaborator

rustbot commented May 6, 2025

r? @tgross35

rustbot has assigned @tgross35.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels May 6, 2025
@mejrs
Copy link
Contributor

mejrs commented May 6, 2025

I like how Mutex and RefCell phrase this: "since this method borrows the $thing mutably, ..". What about something similar like "since this method borrows the OnceLock mutably, no synchronization is necessary"?

@lukaslueg lukaslueg force-pushed the oncecellsyncdocs branch from 031b2b8 to 767083a Compare May 8, 2025 18:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants