| Age | Commit message (Collapse) | Author | Lines |
|---|
|
This leads tools like rustfmt to get confused, because the doc code
block effectively spans two doc comments. As a result, the tools think
the first code block is unclosed, and the subsequent terminator opens a
new block.
Move the FIXME comments outside the doc code blocks, instead.
|
|
address clippy formatting nits
- int_log10.rs: change top level doc comments to outer
- collect.rs: remove empty line after doc comment
- clippy fix: markdown indentation for indented items after line break: a markdown list item continued over multiples lines, but those following lines which are part of the same item are not indented
- clippy fix: bound in one place: when there is a bound in angle brackets and another bound on the same variable in a where clause
|
|
This will let people make calls like random(1..=6), and allows for
future expansion to non-uniform distributions, as well as
floating-point.
For now, this is only implemented for `RangeFull`, to get the interface
in place. Subsequent commits will implement it for other range types.
|
|
|
|
|
|
Implement `Random` for tuple
Implement `Random` for tuples of arity 12 or less. Each element is expected to implement `Random`.
I think it's OK to implement this trait for the following types:
- Primitive integer types and `bool`
- Arrays and tuples of the above values
- ~~`NonZero<T>`~~, `Saturating<T>` and `Wrapping<T>`
The necessity of this trait is debated (<https://github.com/rust-lang/rust/issues/130703#issuecomment-2508889577>), but if we decide to keep it in the future when the `random` module is stabilized, I think it would be useful to have this trait implemented for tuples.
Tracking issue: #130703
r? `@joboet`
|
|
Add an empty `impl ! {}` so `rustdoc` generates auto trait impls and blanket impls on `!`'s documentation page.
|
|
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``````
|
|
r=traviscross,workingjubilee
Remove `i128` and `u128` from `improper_ctypes_definitions`
Rust's 128-bit integers have historically been incompatible with C [1]. However, there have been a number of changes in Rust and LLVM that mean this is no longer the case:
* Incorrect alignment of `i128` on x86 [1]: adjusting Rust's alignment proposed at https://github.com/rust-lang/compiler-team/issues/683, implemented at https://github.com/rust-lang/rust/pull/116672.
* LLVM version of the above: resolved in LLVM, including ABI fix. Present in LLVM18 (our minimum supported version).
* Incorrect alignment of `i128` on 64-bit PowerPC, SPARC, and MIPS [2]: Rust's data layouts adjusted at https://github.com/rust-lang/rust/pull/132422, https://github.com/rust-lang/rust/pull/132741, https://github.com/rust-lang/rust/pull/134115.
* LLVM version of the above: done in LLVM 20 https://github.com/llvm/llvm-project/issues/102783.
* Incorrect return convention of `i128` on Windows: adjusted to match GCC and Clang at https://github.com/rust-lang/rust/pull/134290.
At https://github.com/rust-lang/lang-team/issues/255#issuecomment-2088855084, the lang team considered it acceptable to remove `i128` from `improper_ctypes_definitions` if the LLVM version is known to be compatible. Time has elapsed since then and we have dropped support for LLVM versions that do not have the x86 fixes, meaning a per-llvm-version lint should no longer be necessary. The PowerPC, SPARC, and MIPS changes only came in LLVM 20 but since Rust's datalayouts have also been updated to match, we will be using the correct alignment regardless of LLVM version.
`repr(i128)` was added to this lint in https://github.com/rust-lang/rust/pull/138282, but is also removed here.
Part of the decision is that `i128` should match `__int128` in C on platforms that provide it, which documentation is updated to indicate. We will not guarantee that `i128` matches `_BitInt(128)` since that can be different from `__int128`. Some platforms (usually 32-bit) do not provide `__int128`; if any ABIs are extended in the future to define it, we will need to make sure that our ABI matches.
Closes: https://github.com/rust-lang/rust/issues/134288
[1]: https://github.com/rust-lang/rust/issues/54341
[2]: https://github.com/rust-lang/rust/issues/128950
|
|
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.
|
|
|
|
Rust's 128-bit integers have historically been incompatible with C [1].
However, there have been a number of changes in Rust and LLVM that
mean this is no longer the case:
* Incorrect alignment of `i128` on x86 [1]: adjusting Rust's alignment
proposed at https://github.com/rust-lang/compiler-team/issues/683,
implemented at https://github.com/rust-lang/rust/pull/116672.
* LLVM version of the above: resolved in LLVM, including ABI fix.
Present in LLVM18 (our minimum supported version).
* Incorrect alignment of `i128` on 64-bit PowerPC, SPARC, and MIPS [2]:
Rust's data layouts adjusted at
https://github.com/rust-lang/rust/pull/132422,
https://github.com/rust-lang/rust/pull/132741,
https://github.com/rust-lang/rust/pull/134115.
* LLVM version of the above: done in LLVM 20
https://github.com/llvm/llvm-project/issues/102783.
* Incorrect return convention of `i128` on Windows: adjusted to match
GCC and Clang at https://github.com/rust-lang/rust/pull/134290.
At [3], the lang team considered it acceptable to remove `i128` from
`improper_ctypes_definitions` if the LLVM version is known to be
compatible. Time has elapsed since then and we have dropped support for
LLVM versions that do not have the x86 fixes, meaning a per-llvm-version
lint should no longer be necessary. The PowerPC, SPARC, and MIPS changes
only came in LLVM 20 but since Rust's datalayouts have also been updated
to match, we will be using the correct alignment regardless of LLVM
version.
`repr(i128)` was added to this lint in [4], but is also removed here.
Part of the decision is that `i128` should match `__int128` in C on
platforms that provide it, which documentation is updated to indicate.
We will not guarantee that `i128` matches `_BitInt(128)` since that can
be different from `__int128`. Some platforms (usually 32-bit) do not
provide `__int128`; if any ABIs are extended in the future to define it,
we will need to make sure that our ABI matches.
Closes: https://github.com/rust-lang/rust/issues/134288
Closes: https://github.com/rust-lang/rust/issues/128950
[1]: https://github.com/rust-lang/rust/issues/54341
[2]: https://github.com/rust-lang/rust/issues/128950
[3]: https://github.com/rust-lang/lang-team/issues/255#issuecomment-2088855084
[4]: https://github.com/rust-lang/rust/pull/138282
|
|
Add target-specific NaN payloads for the missing tier 2 targets
This PR adds target-specific NaN payloads for the remaining tier 2 targets:
- `arm64ec`: This target is a mix of `x86_64` and `aarch64`, meaning as they both have no extra payloads `arm64ec` also has no extra payloads.
- `loongarch64`: Per [LoongArch Reference Manual - Volume 1: Basic Architecture](https://github.com/loongson/LoongArch-Documentation/releases/download/2023.04.20/LoongArch-Vol1-v1.10-EN.pdf) section 3.1.1.3, LoongArch does quieting NaN propagation with the Rust preferred NaN as its default NaN, meaning it has no extra payloads.
- `nvptx64`: Per [PTX ISA documentation](https://docs.nvidia.com/cuda/parallel-thread-execution/index.html#floating-point-instructions) section 9.7.3 (and section 9.7.4 for `f16`), all payloads are possible. The documentation explicitly states that `f16` and `f32` operations result in an unspecified NaN payload, while for `f64` it states "NaN payloads are supported" without specifying how or what payload will be generated if there are no input NaNs.
- `powerpc` and `powerpc64`: Per [Power Instruction Set Architecture](https://files.openpower.foundation/s/9izgC5Rogi5Ywmm/download/OPF_PowerISA_v3.1C.pdf) Book I section 4.3.2, PowerPC does quieting NaN propagation with the Rust preferred NaN being generated if no there are no input NaNs, meaning it has no extra payloads.
- `s390x`: Per [IBM z/Architecture Principles of Operation](https://www.vm.ibm.com/library/other/22783213.pdf#page=965) page 9-3, s390x does quieting NaN propagation with the Rust's preferred NaN as its default NaN, meaning it has no extra payloads.
Tracking issue: #128288
cc ``@RalfJung``
``@rustbot`` label +T-lang
Also cc relevant target maintainers of tier 2 targets:
- `arm64ec`: ``@dpaoliello``
- `loongarch64`: ``@heiher`` ``@xiangzhai`` ``@zhaixiaojuan`` ``@xen0n``
- `nvptx64`: ``@RDambrosio016`` ``@kjetilkjeka``
- `powerpc`: the only documented maintainer is ``@BKPepe`` for the tier 3 `powerpc-unknown-linux-muslspe`.
- `powerpc64`: ``@daltenty`` ``@gilamn5tr`` ``@Gelbpunkt`` ``@famfo`` ``@neuschaefer``
- `s390x`: ``@uweigand`` ``@cuviper``
|
|
Implement `Random` for tuples of arity 12 or less. Each element is
expected to implement `Random`.
|
|
Expose algebraic floating point intrinsics
# Problem
A stable Rust implementation of a simple dot product is 8x slower than C++ on modern x86-64 CPUs. The root cause is an inability to let the compiler reorder floating point operations for better vectorization.
See https://github.com/calder/dot-bench for benchmarks. Measurements below were performed on a i7-10875H.
### C++: 10us ✅
With Clang 18.1.3 and `-O2 -march=haswell`:
<table>
<tr>
<th>C++</th>
<th>Assembly</th>
</tr>
<tr>
<td>
<pre lang="cc">
float dot(float *a, float *b, size_t len) {
#pragma clang fp reassociate(on)
float sum = 0.0;
for (size_t i = 0; i < len; ++i) {
sum += a[i] * b[i];
}
return sum;
}
</pre>
</td>
<td>
<img src="https://github.com/user-attachments/assets/739573c0-380a-4d84-9fd9-141343ce7e68" />
</td>
</tr>
</table>
### Nightly Rust: 10us ✅
With rustc 1.86.0-nightly (8239a37f9) and `-C opt-level=3 -C target-feature=+avx2,+fma`:
<table>
<tr>
<th>Rust</th>
<th>Assembly</th>
</tr>
<tr>
<td>
<pre lang="rust">
fn dot(a: &[f32], b: &[f32]) -> f32 {
let mut sum = 0.0;
for i in 0..a.len() {
sum = fadd_algebraic(sum, fmul_algebraic(a[i], b[i]));
}
sum
}
</pre>
</td>
<td>
<img src="https://github.com/user-attachments/assets/9dcf953a-2cd7-42f3-bc34-7117de4c5fb9" />
</td>
</tr>
</table>
### Stable Rust: 84us ❌
With rustc 1.84.1 (e71f9a9a9) and `-C opt-level=3 -C target-feature=+avx2,+fma`:
<table>
<tr>
<th>Rust</th>
<th>Assembly</th>
</tr>
<tr>
<td>
<pre lang="rust">
fn dot(a: &[f32], b: &[f32]) -> f32 {
let mut sum = 0.0;
for i in 0..a.len() {
sum += a[i] * b[i];
}
sum
}
</pre>
</td>
<td>
<img src="https://github.com/user-attachments/assets/936a1f7e-33e4-4ff8-a732-c3cdfe068dca" />
</td>
</tr>
</table>
# Proposed Change
Add `core::intrinsics::f*_algebraic` wrappers to `f16`, `f32`, `f64`, and `f128` gated on a new `float_algebraic` feature.
# Alternatives Considered
https://github.com/rust-lang/rust/issues/21690 has a lot of good discussion of various options for supporting fast math in Rust, but is still open a decade later because any choice that opts in more than individual operations is ultimately contrary to Rust's design principles.
In the mean time, processors have evolved and we're leaving major performance on the table by not supporting vectorization. We shouldn't make users choose between an unstable compiler and an 8x performance hit.
# References
* https://github.com/rust-lang/rust/issues/21690
* https://github.com/rust-lang/libs-team/issues/532
* https://github.com/rust-lang/rust/issues/136469
* https://github.com/calder/dot-bench
* https://www.felixcloutier.com/x86/vfmadd132ps:vfmadd213ps:vfmadd231ps
try-job: x86_64-gnu-nopt
try-job: x86_64-gnu-aux
|
|
|
|
|
|
|
|
Use `std::mem::{size_of, size_of_val, align_of, align_of_val}` from the
prelude instead of importing or qualifying them.
These functions were added to all preludes in Rust 1.80.
|
|
|
|
|
|
ABI compatibility: remove section on target features
Once https://github.com/rust-lang/rust/pull/127731 lands, we will properly diagnose ABI issues caused by target feature mismatch (at least on tier 1 targets). So I'd say we can remove the corresponding part of the docs here -- this is now something the compiler can take care of, so programmers don't need to be concerned. For now this is just a lint, but that's just a transition period, like in prior cases where we fix I-unsound bugs by adding a new check that goes through the "future incompatibility" stages. We have decided that it's actually a bug that we have ABI risks around target features, and we shouldn't document that bug as-if it was intended behavior.
Cc `@rust-lang/opsem` `@chorman0773` `@veluca93`
|
|
|
|
|
|
|
|
|
|
|
|
Closes https://github.com/rust-lang/rust/issues/60783
|
|
|
|
|
|
add extra linebreaks so rustdoc can identify the first sentence
there should probably be a lint against this in rustdoc, it causes too many lines to be shown in the short documentation overviews
expecially noticable for the slice primative type: https://doc.rust-lang.org/std/index.html
|
|
there should probably be a lint against this in rustdoc, it causes
too many lines to be shown in the short documentation overviews
expecially noticable for the slice primative type:
https://doc.rust-lang.org/std/index.html
|
|
|
|
|
|
|
|
Fix typos in floating-point primitive type docs
Fixes a few typos. Also reflows the text of a couple of paragraphs in the source code to the standard line width to make the source easier to read (will have no effect on the rendered documentation).
|
|
|
|
|
|
|
|
|
|
Due to a LLVM bug, `f128` math functions link successfully but LLVM
chooses the wrong symbols (`long double` symbols rather than those for
binary128).
Since this is a notable problem that may surprise a number of users, add
a note about it.
Link: https://github.com/llvm/llvm-project/issues/44744
|
|
reference type safety invariant docs: clarification
The old text could have been read as saying that you can call a function if these requirements are upheld, which is definitely not true as they are an underapproximation of the actual safety invariant.
I removed the part about functions relaxing the requirements via their documentation... this seems incoherent with saying that it may actually be unsound to ever temporarily violate the requirement. Furthermore, a function *cannot* just relax this for its return value, that would in general be unsound. And the part about "unsafe code in a safe function may assume these invariants are ensured of arguments passed by the caller" also interacts with relaxing things: clearly, if the invariant has been relaxed, unsafe code cannot rely on it any more. There may be a place to give general guidance on what kinds of function contracts can exist, but the reference type is definitely not the right place to write that down.
I also took a clarification from https://github.com/rust-lang/rust/pull/121965 that is orthogonal to the rest of that PR.
Cc ```@joshlf``` ```@scottmcm```
|
|
|
|
|
|
Per https://github.com/rust-lang/rust/pull/116677#issuecomment-1945495786, the language as written promises too much. This PR relaxes the language to be consistent with current semantics. If and when #117945 is implemented, we can revert to the old language.
|
|
Document That `f16` And `f128` Hardware Support is Limited (v2)
This PR is identical to #123892, which was approved and merged but then removed from master by a force-push due to a [CI bug](https://rust-lang.zulipchat.com/#narrow/stream/242791-t-infra/topic/ci.20broken.3F).
r? ghost
Original PR description:
---
This adds a small paragraph to the recently added f16 and f128 types explaining that hardware support may be limited, and that performance may suffer as a result of that.
I mainly wrote this because I felt it may be useful to express in some form; as a launchpoint for readers of the documentation if they have issues with performance.
I tried to word the documentation in a way that doesn't create false assumptions (that f16/f128 is too slow to use, for instance), removing the software implementation part could mislead people to thinking that f16/f128 is only available on some platforms, not all, so I believe it is important to keep in.\
"not all *major* platforms" is specifically said so as to not be redundant, because not all platforms implement many things, but the average rustacean is probably going to be using x86_64 or aarch64 derived ISA's, which is who this documentation is targeted towards.
I'm not sure of the best way to word the documentation, or if it should even be added, but I feel like it may be useful to have (potentially in a reworded way, I'm not very confident in the current wording and cannot decide if that is because it is too vague to be useful or too specific to be generally correct).
|
|
Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com>
Update library/core/src/primitive_docs.rs
Remove orphaned doc link and clean up grammar a bit
Update library/core/src/primitive_docs.rs
|
|
Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com>
Update library/core/src/primitive_docs.rs
Rewrite f16 and f128 hw support comments to match PR feedback
I wrote RISC-V allcaps in all cases, and wrote amd64 lowercase in all
cases, im not sure if either is the more correct way for either
platform, thats just how I normally write them, if theres a precedent
elsewhere it should probably be changed to match though.
Update library/core/src/primitive_docs.rs
Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com>
Update library/core/src/primitive_docs.rs
Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com>
Update library/core/src/primitive_docs.rs
|
|
Co-authored-by: Trevor Gross <t.gross35@gmail.com>
Update library/core/src/primitive_docs.rs
Co-authored-by: Trevor Gross <t.gross35@gmail.com>
Update library/core/src/primitive_docs.rs
|
|
Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com>
|
