Improve docs around Once::call_once_force and OnceState.
#45429
Conversation
|
r? @BurntSushi (rust_highfive has picked a reviewer for you, use r? to override) |
src/libstd/sync/once.rs
Outdated
There was a problem hiding this comment.
yes. it is a word
frewsxcv
force-pushed
the
frewsxcv-once-docs
branch
from
be053c4 to
3b5d03b
Compare
|
anyone from @rust-lang/docs wanna read this over? |
kennytm
added
the
S-waiting-on-review
QuietMisdreavus
left a comment
QuietMisdreavus
left a comment
There was a problem hiding this comment.
Seems good, but i have a nit and a broader question.
src/libstd/sync/once.rs
Outdated
There was a problem hiding this comment.
Might prefer "poison status" here, since that feels like it would better imply "the status being poisoned" rather than "the status which has been poisoned". Tiniest nit though.
src/libstd/sync/once.rs
Outdated
There was a problem hiding this comment.
"until one of them doesn't panic" feels weird to me. Does call_once_force continuously call its closure until it doesn't panic, or does it just suppress panics? That this paragraph references "initialization functions" also feels weird in isolation, since call_once/call_once_panic only takes one closure at a time.
Looking at the rest of the Once docs, it feels like a better explanation would involve calling out the states where the closure will and will not run: If the Once is uninitialized, then the closure will run regardless. If it's poisoned, then call_once will just panic, and call_once_force will run the closure. If the Once has successfully been initialized, then...? The closure will not run? The use of multiple initializers in the example leads me to the question of what happens when you hand a Once multiple call_once calls, with separate closures, if poisoning doesn't enter the picture.
There was a problem hiding this comment.
Does call_once_force continuously call its closure until it doesn't panic, or does it just suppress panics?
if the Once hasn't been successfully triggered (without panic), then call_once_force will call the closure once. otherwise, it will ignore the closure.
If the Once has successfully been initialized, then...? The closure will not run?
yep, closure won't run
The use of multiple initializers in the example leads me to the question of what happens when you hand a Once multiple call_once calls, with separate closures, if poisoning doesn't enter the picture.
if the first call_once succeeds, all following call_once and call_once_force calls are no-ops
There was a problem hiding this comment.
does d887138 sound any clearer? thoughts?
kennytm
added
S-waiting-on-author
QuietMisdreavus
left a comment
QuietMisdreavus
left a comment
There was a problem hiding this comment.
Much better, thanks! One last nit, then r=me.
src/libstd/sync/once.rs
Outdated
frewsxcv
force-pushed
the
frewsxcv-once-docs
branch
from
d887138 to
aae94c7
Compare
|
@bors r=quietmisdreavus rollup |
|
📌 Commit aae94c7 has been approved by |
Improve docs around `Once::call_once_force` and `OnceState`. Added some examples, clarify behavior, etc etc. Fixes #43472.
|
☀️ Test successful - status-appveyor, status-travis |
6 participants
Added some examples, clarify behavior, etc etc.
Fixes #43472.