Document Poisoning in `LazyCell` and `LazyLock`
Currently, there is no documentation of poisoning behavior in either `LazyCell` or `LazyLock`, even though both of them can be observed as poisoned by users.
`LazyCell` [plagyround example](https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=9cf38b8dc56db100848f54085c2c697d)
`LazyLock` [playground example](https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=f1cd6f9fe16636e347ebb695a0ce30c0)
# Open Questions
- [x] Is it worth making the implementation of `LazyLock` more complicated to ensure that the the panic message is `"LazyLock instance has previously been poisoned"` instead of `"Once instance has previously been poisoned"`? See the `LazyLock` playground link above for more context.
- [x] Does it make sense to move `LazyLock` into the `poison` module? It is certainly a poison-able type, but at the same time it is slightly different from the 4 other types currently in the `poison` module in that it is unrecoverable. I think this is more of a libs-api question.
``@rustbot`` label +T-libs-api
Please let me know if these open questions deserve a separate issue / PR!
Remove unnecessary `rust_` prefixes
part of https://github.com/rust-lang/rust/issues/116005
Honestly, not sure if this can affect linking somehow, also I didn't touched things like `__rust_panic_cleanup` and `__rust_start_panic` which very likely will break something, so just small cleanup here
also didn't changed `rust_panic_without_hook` because it was renamed here https://github.com/rust-lang/rust/pull/144852
r? libs
Improve formatting of doc code blocks
We don't currently apply automatic formatting to doc comment code blocks. As a
result, it has built up various idiosyncracies, which make such automatic
formatting difficult. Some of those idiosyncracies also make things harder for
human readers or other tools.
This PR makes a few improvements to doc code formatting, in the hopes of making
future automatic formatting easier, as well as in many cases providing net
readability improvements.
I would suggest reading each commit separately, as each commit contains one
class of changes.
Document guarantees of poisoning
This mostly documents the current behavior of `Mutex` and `RwLock` (rust-lang/rust#143471) as imperfect. It's unlikely that the situation improves significantly in the future, and even if it does, the rules will probably be more complicated than "poisoning is completely reliable", so this is a conservative guarantee.
We also explicitly specify that `OnceLock` never poisons, even though it has an API similar to mutexes.
Fixesrust-lang/rust#143471 by improving documentation.
r? ``@Amanieu``
`compiler-builtins` is already in the crate graph via `alloc`, and all
features related to `compiler-builtins` goes through `alloc`. There
isn't any reason that `std` needs this direct dependency, so remove it.
`compiler_builtins` shouldn't be called directly. Change the `PartialEq`
implementation for `DevicePathNode` to use slice equality instead, which
will call `memcmp`/`bcmp` via the intrinsic.
thread name in stack overflow message
Fixesrust-lang/rust#144481, which is caused by the thread name not being initialised yet when setting up the stack overflow information. Unfortunately, the stack overflow UI test did not test for the correct thread name being present, and testing this separately didn't occur to me when writing https://github.com/rust-lang/rust/pull/140628.
This PR contains the smallest possible fix I could think of: passing the thread name explicitly to the platform thread creation function. In the future I'd very much like to explore some possibilities around merging the thread packet and thread handle into one structure and using that in the platform code instead – but that's best left for another PR.
This PR also amends the stack overflow test to check for thread names, so we don't run into this again.
``@rustbot`` label +beta-nominated
Implementation: `#[feature(sync_nonpoison)]`, `#[feature(nonpoison_mutex)]`
Continuation of https://github.com/rust-lang/rust/pull/134663
Tracking Issue: https://github.com/rust-lang/rust/issues/134645
This PR implements a new `sync/nonpoison` module, as well as the `nonpoison` variant of the `Mutex` lock.
There are 2 main changes here, the first is the new `nonpoison::mutex` module, and the second is the `mutex` integration tests.
For the `nonpoison::mutex` module, I did my best to align it with the current state of the `poison::mutex` module. This means that several unstable features (`mapped_lock_guards`, `lock_value_accessors`, and `mutex_data_ptr`) are also in the new `nonpoison::mutex` module, under their respective feature gates. Everything else in that file is under the correct feature gate (`#[unstable(feature = "nonpoison_mutex", issue = "134645")]`).
Everything in the `nonpoison::mutex` file is essentially identical in spirit, as we are simply removing the error case from the original `poison::mutex`.
The second big change is in the integration tests. I created a macro called that allows us to duplicate tests that are "generic" over the different mutex types, in that the poison mutex is always `unwrap`ped.
~~I think that there is an argument against doing this, as it can make the tests a bit harder to understand (and language server capabilities are weaker within macros), but I think the benefit of code deduplication here is worth it. Note that it is definitely possible to generalize this (with a few tweaks) to testing the other `nonpoison` locks when they eventually get implemented, but I'll leave that for a later discussion.~~
Adds tests for the `nonpoison::Mutex` variant by using a macro to
duplicate the existing `poison` tests.
Note that all of the tests here are adapted from the existing `poison`
tests.
Adds the equivalent `nonpoison` types to the `poison::mutex` module.
These types and implementations are gated under the `nonpoison_mutex`
feature gate.
Also blesses the ui tests that now have a name conflicts (because these
types no longer have unique names). The full path distinguishes the
different types.
Co-authored-by: Aandreba <aandreba@gmail.com>
Co-authored-by: Trevor Gross <tmgross@umich.edu>
Add `core::mem::DropGuard`
## 1.0 Summary
This PR introduces a new type `core::mem::DropGuard` which wraps a value and runs a closure when the value is dropped.
```rust
use core::mem::DropGuard;
// Create a new guard around a string that will
// print its value when dropped.
let s = String::from("Chashu likes tuna");
let mut s = DropGuard::new(s, |s| println!("{s}"));
// Modify the string contained in the guard.
s.push_str("!!!");
// The guard will be dropped here, printing:
// "Chashu likes tuna!!!"
```
## 2.0 Motivation
A number of programming languages include constructs like `try..finally` or `defer` to run code as the last piece of a particular sequence, regardless of whether an error occurred. This is typically used to clean up resources, like closing files, freeing memory, or unlocking resources. In Rust we use the `Drop` trait instead, allowing us to [never having to manually close sockets](https://blog.skylight.io/rust-means-never-having-to-close-a-socket/).
While `Drop` (and RAII in general) has been working incredibly well for Rust in general, sometimes it can be a little verbose to setup. In particular when upholding invariants are local to functions, having a quick inline way to setup an `impl Drop` can be incredibly convenient. We can see this in use in the Rust stdlib, which has a number of private `DropGuard` impls used internally:
- [library/alloc/src/vec/drain.rs](9982d6462b/library/alloc/src/vec/drain.rs (L177))
- [library/alloc/src/boxed/thin.rs](9982d6462b/library/alloc/src/boxed/thin.rs (L362))
- [library/alloc/src/slice.rs](9982d6462b/library/alloc/src/slice.rs (L413))
- [library/alloc/src/collections/linked_list.rs](9982d6462b/library/alloc/src/collections/linked_list.rs (L1135))
- [library/alloc/src/collections/binary_heap/mod.rs](9982d6462b/library/alloc/src/collections/binary_heap/mod.rs (L1816))
- [library/alloc/src/collections/btree/map.rs](9982d6462b/library/alloc/src/collections/btree/map.rs (L1715))
- [library/alloc/src/collections/vec_deque/drain.rs](9982d6462b/library/alloc/src/collections/vec_deque/drain.rs (L95))
- [library/alloc/src/vec/into_iter.rs](9982d6462b/library/alloc/src/vec/into_iter.rs (L488))
- [library/std/src/os/windows/process.rs](9982d6462b/library/std/src/os/windows/process.rs (L320))
- [tests/ui/process/win-proc-thread-attributes.rs](9982d6462b/tests/ui/process/win-proc-thread-attributes.rs (L17))
## 3.0 Design
This PR implements what can be considered about the simplest possible design:
1. A single type `DropGuard` which takes both a generic type `T` and a closure `F`.
2. `Deref` + `DerefMut` impls to make it easy to work with the `T` in the guard.
3. An `impl Drop` on the guard which calls the closure `F` on drop.
4. An inherent `fn into_inner` which takes the type `T` out of the guard without calling the closure `F`.
Notably this design does not allow divergent behavior based on the type of drop that has occurred. The [`scopeguard` crate](https://docs.rs/scopeguard/latest/scopeguard/index.html) includes additional `on_success` and `on_onwind` variants which can be used to branch on unwind behavior instead. However [in a lot of cases](https://github.com/rust-lang/rust/issues/143612#issuecomment-3053928328) this doesn’t seem necessary, and using the arm/disarm pattern seems to provide much the same functionality:
```rust
let guard = DropGuard::new((), |s| ...); // 1. Arm the guard
other_function(); // 2. Perform operations
guard.into_inner(); // 3. Disarm the guard
```
`DropGuard` combined with this pattern seems like it should cover the vast majority of use cases for quick, inline destructors. It certainly seems like it should cover all existing uses in the stdlib, as well as all existing uses in crates like [hashbrown](https://github.com/search?q=repo%3Arust-lang%2Fhashbrown%20guard&type=code).
## 4.0 Acknowledgements
This implementation is based on the [mini-scopeguard crate](https://github.com/yoshuawuyts/mini-scopeguard) which in turn is based on the [scopeguard crate](https://docs.rs/scopeguard). The implementations only differ superficially; because of the nature of the problem there is only really one obvious way to structure the solution. And the scopeguard crate got that right!
## 5.0 Conclusion
This PR adds a new type `core::mem::DropGuard` to the stdlib which adds a small convenience helper to create inline destructors with. This would bring the majority of the functionality of the `scopeguard` crate into the stdlib, which is the [49th most downloaded crate](https://crates.io/crates?sort=downloads) on crates.io (387 million downloads).
Given the actual implementation of `DropGuard` is only around 60 lines, it seems to hit that sweet spot of low-complexity / high-impact that makes for a particularly efficient stdlib addition. Which is why I’m putting this forward for consideration; thanks!
Fix CI for drop_guard
fix CI
fix all tidy lints
fix tidy link
add first batch of feedback from review
Add second batch of feedback from review
add third batch of feedback from review
fix failing test
Update library/core/src/mem/drop_guard.rs
Co-authored-by: Ruby Lazuli <general@patchmixolydic.com>
fix doctests
Implement changes from T-Libs-API review
And start tracking based on the tracking issue.
fix tidy lint
Remove `compiler-builtins-{no-asm,mangled-names}`
Remove `compiler-builtins-no-asm`
This feature used to be for when Cranelift didn't support inline
assembly, but its last uses were removed in 52933e0bd200 ("Don't disable
inline asm usage in compiler-builtins when the cranelift backend is
enabled"). and cba05a7a14b3 ("Support naked functions").
This doesn't remove the feature from the `compiler-builtins` crate, that
will be done separately in the subtree repo.
---
Remove `compiler-builtins-mangled-names`
This config was added in 207de019dc67 ("libary: Forward
compiler-builtins "asm" and "mangled-names" feature") but it does not
appear this has ever been used. The PR adding it (rust-lang/rust#78472) says that
this was exposed to help with configuration and points at the [Hermit
Cargo config], but as far as I can tell, this feature name has never
been mentioned in that repository's git history.
Thus, clean up a seemingly unneeded feature.
[Hermit Cargo config]: ab2b830930/.cargo/config
If `HOME` is empty, use the fallback instead
This is a minor change in the `home_dir` api. An empty path is never (or should never be) valid so if the `HOME` environment variable is empty then let's use the fallback instead.
r? libs-api
Guarantee 8 bytes of alignment in Thread::into_raw
When using `AtomicPtr` for synchronization it's incredibly useful when you've got a couple bits you can stuff metadata in. By guaranteeing that `Thread`'s `Inner` struct is aligned to 8 bytes everyone can use the bottom 3 bits to signal other things, such as a critical section, etc.
This guarantee is thus very useful and costs us nothing.
Upgrade the `fortanix-sgx-abi` dependency
0.6.1 removes the `compiler-builtins` dependency, part of RUST-142265. The breaking change from 0.5 to 0.6 is for an update to the `insecure_time` API [1].
I validated that `./x c library --target x86_64-fortanix-unknown-sgx` completes successfully with this change.
Link: a34e9767f3 [1]
Update `dlmalloc` dependency of libstd
This primarily pulls in alexcrichton/dlmalloc-rs#55 and alexcrichton/dlmalloc-rs#54 to address rust-lang/rust#144199. Notably the highest byte in the wasm address space is no longer allocatable and additionally the allocator internally uses `wrapping_add` instead of `add` on pointers since on 32-bit platforms offsets might be larger than half the address space.
Closesrust-lang/rust#144199
Placing the opening triple-backquote inside a `cfg_attr` makes many
tools confused, including syntax highlighters (e.g. vim's) and rustfmt.
Instead, use a `cfg` inside the doc code block.
This config was added in 207de019dc67 ("libary: Forward
compiler-builtins "asm" and "mangled-names" feature") but it does not
appear this has ever been used. The PR adding it (RUST-78472) says that
this was exposed to help with configuration and points at the [Hermit
Cargo config], but as far as I can tell, this feature name has never
been mentioned in that repository's git history.
Thus, clean up a seemingly unneeded feature.
[Hermit Cargo config]: ab2b830930/.cargo/config
This feature used to be for when Cranelift didn't support inline
assembly, but its last uses were removed in 52933e0bd200 ("Don't disable
inline asm usage in compiler-builtins when the cranelift backend is
enabled"). and cba05a7a14b3 ("Support naked functions").
This doesn't remove the feature from the `compiler-builtins` crate, that
will be done separately in the subtree repo.
This primarily pulls in alexcrichton/dlmalloc-rs/55 and
alexcrichton/dlmalloc-rs/54 to address 144199. Notably the highest byte
in the wasm address space is no longer allocatable and additionally the
allocator internally uses `wrapping_add` instead of `add` on pointers
since on 32-bit platforms offsets might be larger than half the address
space.
Fix broken TLS destructors on 32-bit win7
Fixesrust-lang/rust#141300
On the 32-bit win7 target, we use OS TLS instead of native TLS, due to issues with how the OS handles alignment. Unfortunately, this caused issues due to the TLS destructors not running, causing memory leaks among other problems.
On Windows, to support OS TLS, the TlsAlloc family of function is used by Rust. This function does not support TLS destructors at all. However, rust has some code to emulate those destructors, by leveraging the TLS support functionality found in the MSVC CRT (specifically, in tlssup.c of the CRT).
To use this functionality, the user must do two things:
1. They must put the address to their callback in a section between `.CRT$XLB` and `.CRT$XLY`.
2. They must add a reference to `_tls_used` (or `__tls_used` on x86) to make sure the TLS support code in tlssup.c isn't garbage collected by the linker.
Prior to this commit, this second bit wasn't being done properly by the Rust TLS support code. Instead of adding a reference to _tls_used, it instead had a reference to its own callback to prevent it from getting GC'd by the linker. While this is _also_ necessary, not having a reference on _tls_used made the entire support non-functional.
This commit reworks the code to:
1. Add an unconditional `#[used]` attribute on the CALLBACK, which should be enough to prevent it from getting GC'd by the linker.
2. Add a reference to `_tls_used`, which should pull the TLS support code into the Rust programs and not let it be GC'd by the linker.
- Use EFI_TCP4_GET_MODE_DATA to be able to query for ttl, nodelay,
peer_addr and socket_addr.
- peer_addr is needed for implementation of `accept`.
Signed-off-by: Ayush Singh <ayush@beagleboard.org>
On the 32-bit win7 target, we use OS TLS instead of native TLS, due to
issues with how the OS handles alignment. Unfortunately, this caused
issues due to the TLS destructors not running, causing memory leaks
among other problems.
On Windows, to support OS TLS, the TlsAlloc family of function is used
by Rust. This function does not support TLS destructors at all. However,
rust has some code to emulate those destructors, by leveraging the TLS
support functionality found in the MSVC CRT (specifically, in tlssup.c
of the CRT). Specifically, the CRT provides the ability to register
callbacks that are called (among other things) on thread destruction. By
registering our own callback, we can run through a list of registered
destructors functions to execute.
To use this functionality, the user must do two things:
1. They must put the address to their callback in a section between
`.CRT$XLB` and `.CRT$XLY`.
2. They must add a reference to `_tls_used` (or `__tls_used` on x86) to
make sure the TLS support code in tlssup.c isn't garbage collected by
the linker.
Prior to this commit, this second bit wasn't being done properly by the
Rust TLS support code. Instead of adding a reference to _tls_used, it
instead had a reference to its own callback to prevent it from getting
GC'd by the linker. While this is _also_ necessary, not having a
reference on _tls_used made the entire support non-functional.
This commit reworks the code to:
1. Add an unconditional `#[used]` attribute on the CALLBACK, which
should be enough to prevent it from getting GC'd by the linker.
2. Add a reference to `_tls_used`, which should pull the TLS support
code into the Rust programs and not let it be GC'd by the linker.
This mostly documents the current behavior of `Mutex` and `RwLock` as
imperfect. It's unlikely that the situation improves significantly in
the future, and even if it does, the rules will probably be more
complicated than "poisoning is completely reliable", so this is a
conservative guarantee.
We also explicitly specify that `OnceLock` never poisons, even though it
has an API similar to mutexes.
Make slice comparisons const
This needed a fix for `derive_const`, too, as it wasn't usable in libcore anymore as trait impls need const stability attributes. I think we can't use the same system as normal trait impls while `const_trait_impl` is still unstable.
r? ```@fee1-dead```
cc rust-lang/rust#143800
Linting public reexport of private dependencies
Part of public/private dependencies rust-lang/rust#44663
Partially addresses rust-lang/rust#71043
I'm adding a warning for reexports of private dependencies into `rustc_resolve`. I get that this should not be a warning, but should instead be a lint to be controlled by the feature gate, but I did not figure out how exactly to do that at that point. I tried doing the same thing as is done in `rustc_privacy`, but the linting system is not ready yet as far as I understand the error I got, so I made a warning for now instead. Some guidance on how to emit lints with `dcx` would be appreciated.
This also sets the `std_detect` crate as a public dependency of `std` because some macros are reexported from there. I did not check closer, but the other option may be to allow the specific reexports instead.
