OnceCell & OnceLock docs: Using (un)initialized consistently

[Pyr0de]

Changed

• set / initialize / full to initialized state
• uninitialize / empty to uninitialized state
• f to f()
• Added explaination of uninitialized state & initialized state

OnceCell Docs
OnceLock Docs

Fixes #85716
@rustbot label +A-docs

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @ChrisDenton (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[tgross35]

Fwiw I think "initialized" and "uninitialized" is the better terminology here. "Initialized" makes it clear that it is a one-time occurrence, where as set/empty sounds more like Option where you can go back and forth.

[hkBst]

@tgross35 Funny that you should mention Option. It really is like Option in that respect and can go back to being unset (to use the proposed new term).

[tgross35]

There is API to unset these types, but the main problem they solve is initialization behind a shared &T reference with get_or_init (which has "initialize" in the name), rather than &mut T (if you always have &mut T, you could just use an Option). The changes "full" -> "set" seem reasonable here, but I am unconvinced that "initialize" -> "set" is an improvement.

[hkBst]

There is API to unset these types, but the main problem they solve is initialization behind a shared &T reference with get_or_init (which has "initialize" in the name), rather than &mut T (if you always have &mut T, you could just use an Option). The changes "full" -> "set" seem reasonable here, but I am unconvinced that "initialize" -> "set" is an improvement.

You do have a point there! Fundamentally there are 3 things which need a name that can be used consistently. There is the empty/unset/uninitialized state, the full/set/initialized state, and the transition set/initialize:

• Originally I liked empty ---initialize---> initialized
• @Pyr0de's PR does empty ---set---> set
• you seem to like uninitialized ---initialize---> initialized
• another option is unset ---initialize---> initialized(or set)

[ChrisDenton]

r? tgross35

Since tgross35 has started but feel free to flip it back to me if you'd prefer.

Edit: I used the wrong command initially, sorry! Corrected now.

[Pyr0de]

I agree with @hkBst's idea of empty-initialize-initialized

but empty-set-initialized could be used to include set

I think both are good options

[hkBst]

Actually, I think @tgross35 has convinced me that uninitialized ---initialize---> initialized is the way to go, and it goes with most of the methods that end in init. To solve the issue of confusion with uninitialized memory, we could explicitly state near the beginning what the two states are called...

[Pyr0de]

To solve the issue of confusion with uninitialized memory, we could explicitly state near the beginning what the two states are called...

Could you suggest some way to show this information?

[hkBst]

Could you suggest some way to show this information?

Maybe something like: A OnceCell conceptually has two states, called the uninitialized state and the initialized state. Like an enum {Uninitialized, Initialized(T)}, except that it has invariants to uphold, so the enum is hidden.

That would do the trick I think.

[Pyr0de]

@hkBst @tgross35
I have made some changes and edited the original description to reflect the changes

@rustbot review

[tgross35]

There are a handful of places where the wording can be simplified, plus a slight terminology adjustment to be more consistent with the other cell types. But the rest of the wording looks better to me.

[tgross35]

Two nits then r=me

[tgross35]

Thanks for all the work getting this through!

@bors r+ rollup

[bors]

📌 Commit f8b01b3 has been approved by tgross35

It is now in the queue for this repository.