Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations
## Motivation
The existing documentation for atomic `fetch_update` (and other similar methods) has a section that reads like so:
> ### Considerations
> This method is not magic; it is not provided by the hardware. It is implemented in
> terms of `AtomicBlah::compare_exchange_weak`, and suffers from the same drawbacks.
> In particular, this method will not circumvent the [ABA Problem].
>
> [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
The wording here seems to imply that the drawbacks being discusses are caused by the *`weak` version* of `compare_exchange`, and that one may avoid those drawbacks by using `compare_exchange` instead. Indeed, a conversation in the `#dark-arts` channel on the Rust community discord based on this interpretation led to this PR.
In reality, the drawbacks are inherent to implementing such an operation based on *any* compare-and-swap style operation, as opposed to an [LL,SC](https://en.wikipedia.org/wiki/Load-link/store-conditional) operation, and they apply equally to `compare_exchange` and `compare_exchange_weak` as well.
## Changes
- Rewords existing Considerations section on `fetch_update` and friends to make clear that the limitations are inherent to an implementation based on any CAS operation, rather than the weak version of `compare_exchange` in particular. New version:
> ### Considerations
>
> This method is not magic; it is not provided by the hardware, and does not act like a
> critical section or mutex.
>
> It is implemented on top of an atomic [compare-and-swap operation], and thus is subject to
> the usual drawbacks of CAS operations. In particular, be careful of the [ABA problem]
> if this atomic integer is an index or more generally if knowledge of only the *bitwise value*
> of the atomic is not in and of itself sufficient to ensure any required preconditions.
>
> [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
> [compare-and-swap operation]: https://en.wikipedia.org/wiki/Compare-and-swap
- Add Considerations to `compare_exchange` and `compare_exchange_weak` which details similar considerations and when they may be relevant. New version:
> ### Considerations
>
> `compare_exchange` is a [compare-and-swap operation] and thus exhibits the usual downsides
> of CAS operations. In particular, a load of the value followed by a successful
> `compare_exchange` with the previous load *does not ensure* that other threads have not
> changed the value in the interim. This is usually important when the *equality* check in
> the `compare_exchange` is being used to check the *identity* of a value, but equality
> does not necessarily imply identity. In this case, `compare_exchange` can lead to the
> [ABA problem].
>
> [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
> [compare-and-swap operation]: https://en.wikipedia.org/wiki/Compare-and-swap
Specify that "option-like" enums must be `#[repr(Rust)]` to be ABI-compatible with their non-1ZST field.
Add that the enum must be `#[repr(Rust)]` and not `#[repr(packed)]` or `#[repr(align)]` in order to be ABI-compatible with its null-pointer-optimized field.
The specific rules here were decided on here: https://github.com/rust-lang/rust/pull/130628#issuecomment-2402761599 but `repr` was not mentioned. In practice, only `#[repr(Rust)]` (or no `repr` attribute, which is equivalent) works for this, so add that to the docs.
-----
Restrict to `#[repr(Rust)]` only, since:
* `#[repr(C)]` and the primitive representations (`#[repr(u8)]` etc) definitely disqualify the enum from NPO, since they have defined layouts that store the tag separately to the payload.
* `#[repr(transparent)]` enums are covered two bullet points above this (line 1830), and cannot have multiple variants, so would fail the "The enum has exactly two variants" requirement anyway.
As for `#[repr(align)]`: my current wording that it is completely disallowed may be too strong: it seems like `#[repr(align(<= alignment of T))] enum Foo { X, Y(T) }` currently does still have the same ABI as `T` in practice, though this may not be something we want to promise. (`#[repr(align(> alignment of T))]` definitely disqualifies the enum from being ABI-compatible with T currently).
I added the note about `packed` to match `align`, but `#[repr(packed)]` currently can't be applied to `enum`s at all anyway, so might be unnecessary.
-----
I think this needs T-lang approval?
cc ``````@workingjubilee``````
Faster fmt::Display of 128-bit integers, without unsafe pointer
In followup of #135265, hereby the 128-bit part.
* Batches per 16 instead of 19 digits
* Buffer access as array insteaf of unsafe pointer
* Added test coverage for i128 and u128
r? tgross35 ChrisDenton
Implements `trim_prefix` and `trim_suffix` methods for both `slice` and
`str` types which remove at most one occurrence of a prefix/suffix while
always returning a string/slice (rather than Option), enabling easy
method chaining.
- Rewords existing Considerations section on `fetch_update` and friends
to make clear that the limitations are inherent to an implementation based on any
CAS operation, rather than the weak version of `compare_exchange` in particular
- Add Considerations to `compare_exchange` and `compare_exchange_weak`
which details similar considerations and when they may be relevant.
Mark `core::slice::memchr` as `#[doc(hidden)]`
It's purely internal, and not intended to be a public API, even on nightly. This stops it showing up and being misleading in rustdoc search.
It also mirrors the (also internal) `core::slice::sort` module.
core::ptr: deduplicate more method docs
used `rg -Fxf library/core/src/ptr/{const,mut}_ptr.rs` to find duplicated doc comments, and `diff -u` after copying them to files to ensure they are actually identical.
`sed 's| */// *||'` was then used to translate the doc comments to plain markdown.
part of https://github.com/rust-lang/rust/issues/139190
Stabilize keylocker
This PR stabilizes the feature flag `keylocker_x86` (tracking issue rust-lang/rust#134813).
# Public API
The 2 `x86` target features `kl` and `widekl`, and the associated intrinsics in stdarch.
These target features are very specialized, and are only used to signal the presence of the corresponding CPU instruction. They don't have any nontrivial interaction with the ABI (contrary to something like AVX), and serve the only purpose of enabling 11 stdarch intrinsics, all of which have been implemented and propagated to rustc via a stdarch submodule update.
Also, these were added way back in LLVM12, and as the minimum LLVM required for rustc is LLVM19, we are safe in that front too!
# Associated PRs
- rust-lang/rust#134814
- rust-lang/stdarch#1706
- rust-lang/rust#136831 (stdarch submodule update)
- rust-lang/stdarch#1795 (stabilizing the runtime detection and intrinsics)
- rust-lang/rust#141964 (stdarch submodule update for the stabilization of the runtime detection and intrinsics)
As all of the required tasks have been done (adding the target features to rustc, implementing their runtime detection in std_detect and implementing the associated intrinsics in core_arch), these target features can be stabilized now.
cc ````@rust-lang/lang````
cc ````@rust-lang/libs-api```` for the intrinsics and runtime detection
I don't think anyone else worked on this feature, so no one else to ping, maybe cc ````@Amanieu.```` I will send the reference pr soon.
Specify the behavior of `file!`
This takes the current behavior of `file!` and documents it so it is safe to make assumptions about.
For example, Cargo could provide a `CARGO_RUSTC_CURRENT_DIR` as a base path for `file!`.
Example use cases
- Being able to look up test assets relative to the current file ([example](b9026bf654/tests/testsuite/cargo_add/add_basic/mod.rs (L34)))
- Inline snapshotting libraries being able to update Rust source code ([example](b9026bf654/tests/testsuite/alt_registry.rs (L36-L45)))
See rust-lang/cargo#3946 for more context.
T-libs-api discussed two solutions in rust-lang/libs-team#478
- `file_absolute!`:
- Has less meaning in other build tools like buck2
- Bakes in the assumption that a full path is available (e.g. with trim-paths)
- Specifying `file!`s behavior (this PR):
- Leaves it to the user to deal with trim-paths
- Even though `file!` is currently unspecified, changing it would likely have too large of an impact on the ecosystem at this time.
A future possibility is that rustc could have a flag that controls modifies the base path used for `file!`.
That seems purely additive with specifying the behavior and we do not want to block on it.
It would also likely be too disruptive for Cargo users (as mentioned). However, we tried to keep this in mind when specifying the behavior.
Enable Non-determinism of float operations in Miri and change std tests
Links to [#4208](https://github.com/rust-lang/miri/issues/4208) and [#3555](https://github.com/rust-lang/miri/issues/3555) in Miri.
Non-determinism of floating point operations was disabled in rust-lang/rust#137594 because it breaks the tests and doc-tests in core/coretests and std. This PR enables some of them.
This pr includes the following changes:
- Enables the float non-determinism but with a lower relative error of 4ULP instead of 16ULP
- These operations now have a fixed output based on the C23 standard, except the pow operations, this is tracked in [#4286](https://github.com/rust-lang/miri/issues/4286#issue-3010677983)
- Changes tests that made incorrect assumptions about the operations, not to make that assumption anymore (from `assert_eq!` to `assert_approx_eq!`.
- Changed the doctests of the stdlib of these operations to compare against fixed constants instead of `f*::EPSILON`, which now succeed with Miri and `-Zmiri-many-seeds`
- Added a constant `APPROX_DELTA` in `std/tests/floats/f32.rs` which is used for approximation tests, but with a different value when run in Miri. This is to make these tests succeed.
- Added tests in the float tests of Miri to test the C23 behaviour.
Fixes https://github.com/rust-lang/miri/issues/4208
This takes the current behavior of `file!` and documents it so it is
safe to make assumptions about.
For example, Cargo could provide a `CARGO_RUSTC_CURRENT_DIR` as a base
path for `file!`.
Example use cases
- Being able to look up test assets relative to the current file
([example](b9026bf654/tests/testsuite/cargo_add/add_basic/mod.rs (L34)))
- Inline snapshotting libraries being able to update Rust source code
([example](b9026bf654/tests/testsuite/alt_registry.rs (L36-L45)))
T-libs-api discussed two solutions
- `file_absolute!`:
- Has less meaning in other build tools like buck2
- Bakes in the assumption that a full path is available (e.g. with
trim-paths)
- Specifying `file!`s behavior (this PR):
- Leaves it to the user to deal with trim-paths
- Even though `file!` is currently unspecified, changing it would
likely have too large of an impact on the ecosystem at this time.
A future possibility is that rustc could have a flag that controls
modifies the base path used for `file!`.
That seems purely additive with specifying the behavior and we do not
want to block on it.
It would also likely be too disruptive for Cargo users (as mentioned).
However, we tried to keep this in mind when specifying the behavior.
It's purely internal, and not intended to be a public API, even on
nightly. This stops it showing up and being misleading in rustdoc
search.
It also mirrors the (also internal) `core::slice::sort` module.
Stabilize `sha512`, `sm3` and `sm4` for x86
This PR stabilizes the feature flag `sha512_sm_x86` (tracking issue rust-lang/rust#126624).
# Public API
The 3 `x86` target features `sha512`, `sm3` and `sm4`, and the associated intrinsics in stdarch.
These target features are very specialized, and are only used to signal the presence of the corresponding CPU instruction. They don't have any nontrivial interaction with the ABI (contrary to something like AVX), and serve the only purpose of enabling 10 stdarch intrinsics, all of which have been implemented and propagated to rustc via a stdarch submodule update.
Also, these were added in LLVM17, and as the minimum LLVM required for rustc is LLVM19, we are safe in that front too!
# Associated PRs
- rust-lang/rust#126704
- rust-lang/stdarch#1592
- rust-lang/stdarch#1790
- rust-lang/rust#140389 (stdarch submodule update)
- rust-lang/stdarch#1796 (stabilizing the runtime detection and intrinsics)
- rust-lang/rust#141964 (stdarch submodule update for the stabilization of the runtime detection and intrinsics)
As all of the required tasks have been done (adding the target features to rustc, implementing their runtime detection in std_detect and implementing the associated intrinsics in core_arch), these target features can be stabilized now.
cc `@rust-lang/lang`
cc `@rust-lang/libs-api` for the intrinsics and runtime detection
I don't think anyone else worked on this feature, so no one else to ping, maybe cc `@Amanieu.` I will send the reference pr soon.
De-duplicate f16 & f128 doctest attributes
Now that rustdoc supports `#[doc(test(attr(...)))]` at every level, thanks to https://github.com/rust-lang/rust/pull/140560, we can de-duplicate the f16 & f128 doctest attributes.
Unfortunately we can de-duplicate the `cfg`s attribute as rustdoc would complain about missing `main`, but it's already much better than before.
Addresses https://github.com/rust-lang/rust/pull/140323/files#r2062702761
r? `@tgross35`
In PR 90877 T-lang decided not to remove `intrinsics::pref_align_of`.
However, the intrinsic and its supporting code
1. is a nightly feature, so can be removed at compiler/libs discretion
2. requires considerable effort in the compiler to support, as it
necessarily complicates every single site reasoning about alignment
3. has been justified based on relevance to codegen, but it is only a
requirement for C++ (not C, not Rust) stack frame layout for AIX,
in ways Rust would not consider even with increased C++ interop
4. is only used by rustc to overalign some globals, not correctness
5. can be adequately replaced by other rules for globals, as it mostly
affects alignments for a few types under 16 bytes of alignment
6. has only one clear benefactor: automating C -> Rust translation
for GNU extensions like `__alignof`
7. such code was likely intended to be `alignof` or `_Alignof`,
because the GNU extension is a "false friend" of the C keyword,
which makes the choice to support such a mapping very questionable
8. makes it easy to do incorrect codegen in the compiler by its mere
presence as usual Rust rules of alignment (e.g. `size == align * N`)
do not hold with preferred alignment
The implementation is clearly damaging the code quality of the compiler.
Thus it is within the compiler team's purview to simply rip it out.
If T-lang wishes to have this intrinsic restored for c2rust's benefit,
it would have to use a radically different implementation that somehow
does not cause internal incorrectness.
Until then, remove the intrinsic and its supporting code, as one tool
and an ill-considered GCC extension cannot justify risking correctness.
Because we touch a fair amount of the compiler to change this at all,
and unfortunately the duplication of AbiAndPrefAlign is deep-rooted,
we keep an "AbiAlign" type which we can wean code off later.
Compute number of digits instead of relying on constant value for u128 display code
As discussed in https://github.com/rust-lang/rust/pull/142098/files#r2132084991, the code should reuse the same logic as the rest of file instead of using a constant value.
r? `@tamird`
