LazyCell, LazyLock are missing some big-picture documentation #125615
Labels
A-docs
Area: documentation for any part of the project, including the compiler, standard library, and tools
C-enhancement
Category: An issue proposing an enhancement or a PR with one.
T-libs
Relevant to the library team, which will review and decide on the PR/issue.
T-libs-api
Relevant to the library API team, which will review and decide on the PR/issue.
Comments
rustbot
added
the
needs-triage
fmease
added
C-enhancement
rust-timer
added a commit
to rust-lang-ci/rust
that referenced
this issue
Jun 4, 2024
Rollup merge of rust-lang#125696 - workingjubilee:please-dont-say-you-are-lazy, r=Nilstrieb Explain differences between `{Once,Lazy}{Cell,Lock}` types The question of "which once-ish cell-ish type should I use?" has been raised multiple times, and is especially important now that we have stabilized the `LazyCell` and `LazyLock` types. The answer for the `Lazy*` types is that you would be better off using them if you want to use what is by far the most common pattern: initialize it with a single nullary function that you would call at every `get_or_init` site. For everything else there's the `Once*` types. "For everything else" is a somewhat weak motivation, as it only describes by negation. While contrasting them is inevitable, I feel positive motivations are more understandable. For this, I now offer a distinct example that helps explain why `OnceLock` can be useful, despite `LazyLock` existing: you can do some cool stuff with it that `LazyLock` simply can't support due to its mere definition. The pair of `std::sync::*Lock`s are usable inside a `static`, and can serve roles in async or multithreaded (or asynchronously multithreaded) programs that `*Cell`s cannot. Because of this, they received most of my attention. Fixes rust-lang#124696 Fixes rust-lang#125615
|
@workingjubilee thatnks for the PR! |
|
Yeah, I do indeed have nothing useful to say about Once, basically, because it doesn't seem very useful except as a raw implementation primitive of OnceLock. I suppose we could add a comment that soft-discourages it? |
|
Yeah I think that would be useful.
|
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this issue
Jun 15, 2024
…oing-things-once, r=jhpratt std: suggest OnceLock over Once It was noted in rust-lang#125615 (comment) that Once is not necessary in most cases and should be discouraged. Once is really just an implementation detail of OnceLock that others can use if they want. Suggest they use OnceLock instead.
rust-timer
added a commit
to rust-lang-ci/rust
that referenced
this issue
Jun 15, 2024
Rollup merge of rust-lang#126509 - workingjubilee:gently-discourage-doing-things-once, r=jhpratt std: suggest OnceLock over Once It was noted in rust-lang#125615 (comment) that Once is not necessary in most cases and should be discouraged. Once is really just an implementation detail of OnceLock that others can use if they want. Suggest they use OnceLock instead.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
These types are stable now, however, the docs don't properly mention them everywhere yet:
Onceis basically the same asOnceLock<()>, but I am not sure.)Cc @rust-lang/libs-api
The text was updated successfully, but these errors were encountered: