Expand the documentation for the `std::sync` module
I've tried to expand the documentation for Rust's synchronization primitives. The module level documentation explains why synchronization is required when working with a multiprocessor system,
and then links to the appropiate structure in this module.
Fixes#29377, since this should be the last item on the checklist (documentation for `Atomic*` was fixed in #44854, but not ticked off the checklist).
Because `call_once` is generic, but `is_completed` is not, we need
`#[inline]` annotation to allow LLVM to inline `is_completed` into
`call_once` in downstream crates.
Update Cargo.lock
This also includes major version bumps for the rand crate used by core, std, and alloc tests, among other crates (regex, etc.) used elsewhere. Since these are all internal there should be no user-visible changes.
r? @alexcrichton
Allow to check if sync::Once is already initialized
Hi!
I propose to expose a way to check if a `Once` instance is initialized.
I need it in `once_cell`. `OnceCell` is effetively a pair of `(Once, UnsafeCell<Option<T>>)`, which can set the `T` only once. Because I can't check if `Once` is initialized, I am forced to add an indirection and check the value of ptr instead:
8127a81976/src/lib.rs (L423-L429)8127a81976/src/lib.rs (L457-L461)
The `parking_lot`'s version of `Once` exposes the state as an enum: https://docs.rs/parking_lot/0.6.3/parking_lot/struct.Once.html#method.state.
I suggest, for now, just to add a simple `bool` function: this fits my use-case perfectly, exposes less implementation details, and is forward-compatible with more fine-grained state checking.
- [std: Rewrite the `sync` module71d4e77db8) (Nov 2014)
```diff
- pub fn doit(&self, f: ||) {
+ pub fn doit(&'static self, f: ||) {
```
> ```text
> The second layer is the layer provided by `std::sync` which is intended to be
> the thinnest possible layer on top of `sys_common` which is entirely safe to
> use. There are a few concerns which need to be addressed when making these
> system primitives safe:
>
> * Once used, the OS primitives can never be **moved**. This means that they
> essentially need to have a stable address. The static primitives use
> `&'static self` to enforce this, and the non-static primitives all use a
> `Box` to provide this guarantee.
> ```
The author of this diff is @alexcrichton. `sync::Once` contains only a pointer to (privately hidden) `Waiter`s, which are all stack-allocated. The `'static` bound to `sync::Once` is thus unnecessary to guarantee that any OS primitives are non-relocatable.
See https://internals.rust-lang.org/t/sync-once-per-instance/7918 for more context.
Add Condvar APIs not susceptible to spurious wake
Provide wait_until and wait_timeout_until helper wrappers that aren't susceptible to spurious wake.
Additionally wait_timeout_until makes it possible to more easily write code that waits for a fixed amount of time in face of spurious wakes since otherwise each user would have to do math on adjusting the duration.
Implements #47960.
