Clarify documentation for `[T]::contains`
Change the documentation to correctly characterize when the suggested alternative to `contains` applies, and correctly explain why it works.
Fixes#84877
Update `ptr` docs with regards to `ptr::addr_of!`
This updates the documentation since `ptr::addr_of!` and `ptr::addr_of_mut!` are now stable. One might remove the distinction between the sections `# On packed structs` and `# Examples`, as the old section on packed structs was primarily to prevent users of doing undefined behavior, which is not necessary anymore.
Technically there is now wrong/outdated documentation on stable, but I don't think this is worth a point release 😉Fixes#83509.
``````````@rustbot`````````` modify labels: T-doc
This updates the documentation since `ptr::addr_of!` and
`ptr::addr_of_mut!` are now stable. One might remove the distinction
between the sections `# On packed structs` and `# Examples`, as the old
section on packed structs was primarily to prevent users of doing unde-
fined behavior, which is not necessary anymore.
There is also a new section in "how to obtain a pointer", which referen-
ces the `ptr::addr_of!` macros.
This commit contains squashed commits from code review.
Co-authored-by: Joshua Nelson <joshua@yottadb.com>
Co-authored-by: Mara Bos <m-ou.se@m-ou.se>
Co-authored-by: Soveu <marx.tomasz@gmail.com>
Co-authored-by: Ralf Jung <post@ralfj.de>
[Arm64] use isb instruction instead of yield in spin loops
On arm64 we have seen on several databases that ISB (instruction synchronization
barrier) is better to use than yield in a spin loop. The yield instruction is a
nop. The isb instruction puts the processor to sleep for some short time. isb
is a good equivalent to the pause instruction on x86.
Below is an experiment that shows the effects of yield and isb on Arm64 and the
time of a pause instruction on x86 Intel processors. The micro-benchmarks use
https://github.com/google/benchmark.git
```
$ cat a.cc
static void BM_scalar_increment(benchmark::State& state) {
int i = 0;
for (auto _ : state)
benchmark::DoNotOptimize(i++);
}
BENCHMARK(BM_scalar_increment);
static void BM_yield(benchmark::State& state) {
for (auto _ : state)
asm volatile("yield"::);
}
BENCHMARK(BM_yield);
static void BM_isb(benchmark::State& state) {
for (auto _ : state)
asm volatile("isb"::);
}
BENCHMARK(BM_isb);
BENCHMARK_MAIN();
$ g++ -o run a.cc -O2 -lbenchmark -lpthread
$ ./run
--------------------------------------------------------------
Benchmark Time CPU Iterations
--------------------------------------------------------------
AWS Graviton2 (Neoverse-N1) processor:
BM_scalar_increment 0.485 ns 0.485 ns 1000000000
BM_yield 0.400 ns 0.400 ns 1000000000
BM_isb 13.2 ns 13.2 ns 52993304
AWS Graviton (A-72) processor:
BM_scalar_increment 0.897 ns 0.874 ns 801558633
BM_yield 0.877 ns 0.875 ns 800002377
BM_isb 13.0 ns 12.7 ns 55169412
Apple Arm64 M1 processor:
BM_scalar_increment 0.315 ns 0.315 ns 1000000000
BM_yield 0.313 ns 0.313 ns 1000000000
BM_isb 9.06 ns 9.06 ns 77259282
```
```
static void BM_pause(benchmark::State& state) {
for (auto _ : state)
asm volatile("pause"::);
}
BENCHMARK(BM_pause);
Intel Skylake processor:
BM_scalar_increment 0.295 ns 0.295 ns 1000000000
BM_pause 41.7 ns 41.7 ns 16780553
```
Tested on Graviton2 aarch64-linux with `./x.py test`.
On arm64 we have seen on several databases that ISB (instruction synchronization
barrier) is better to use than yield in a spin loop. The yield instruction is a
nop. The isb instruction puts the processor to sleep for some short time. isb
is a good equivalent to the pause instruction on x86.
Below is an experiment that shows the effects of yield and isb on Arm64 and the
time of a pause instruction on x86 Intel processors. The micro-benchmarks use
https://github.com/google/benchmark.git
$ cat a.cc
static void BM_scalar_increment(benchmark::State& state) {
int i = 0;
for (auto _ : state)
benchmark::DoNotOptimize(i++);
}
BENCHMARK(BM_scalar_increment);
static void BM_yield(benchmark::State& state) {
for (auto _ : state)
asm volatile("yield"::);
}
BENCHMARK(BM_yield);
static void BM_isb(benchmark::State& state) {
for (auto _ : state)
asm volatile("isb"::);
}
BENCHMARK(BM_isb);
BENCHMARK_MAIN();
$ g++ -o run a.cc -O2 -lbenchmark -lpthread
$ ./run
--------------------------------------------------------------
Benchmark Time CPU Iterations
--------------------------------------------------------------
AWS Graviton2 (Neoverse-N1) processor:
BM_scalar_increment 0.485 ns 0.485 ns 1000000000
BM_yield 0.400 ns 0.400 ns 1000000000
BM_isb 13.2 ns 13.2 ns 52993304
AWS Graviton (A-72) processor:
BM_scalar_increment 0.897 ns 0.874 ns 801558633
BM_yield 0.877 ns 0.875 ns 800002377
BM_isb 13.0 ns 12.7 ns 55169412
Apple Arm64 M1 processor:
BM_scalar_increment 0.315 ns 0.315 ns 1000000000
BM_yield 0.313 ns 0.313 ns 1000000000
BM_isb 9.06 ns 9.06 ns 77259282
static void BM_pause(benchmark::State& state) {
for (auto _ : state)
asm volatile("pause"::);
}
BENCHMARK(BM_pause);
Intel Skylake processor:
BM_scalar_increment 0.295 ns 0.295 ns 1000000000
BM_pause 41.7 ns 41.7 ns 16780553
Tested on Graviton2 aarch64-linux with `./x.py test`.
Searching for "reduce" currently puts the `reduce` alias for `fold`
above the actual `reduce` function. The `reduce` function already has a
cross-reference for `fold`, and vice versa.
The Eq trait has a special hidden function. MIR `InstrumentCoverage`
would add this function to the coverage map, but it is never called, so
the `Eq` trait would always appear uncovered.
Fixes: #83601
The fix required creating a new function attribute `no_coverage` to mark
functions that should be ignored by `InstrumentCoverage` and the
coverage `mapgen` (during codegen).
While testing, I also noticed two other issues:
* spanview debug file output ICEd on a function with no body. The
workaround for this is included in this PR.
* `assert_*!()` macro coverage can appear covered if followed by another
`assert_*!()` macro. Normally they appear uncovered. I submitted a new
Issue #84561, and added a coverage test to demonstrate this issue.
Add the `try_trait_v2` library basics
No compiler changes as part of this -- just new unstable traits and impls thereof.
The goal here is to add the things that aren't going to break anything, to keep the feature implementation simpler in the next PR.
(Draft since the FCP won't end until Saturday, but I was feeling optimistic today -- and had forgotten that FCP was 10 days, not 7 days.)
Stabilize Duration::MAX
Following the suggested direction from https://github.com/rust-lang/rust/issues/76416#issuecomment-817278338, this PR proposes that `Duration::MAX` should have been part of the `duration_saturating_ops` feature flag all along, having been
0. heavily referenced by that feature flag
1. an odd duck next to most of `duration_constants`, as I expressed in https://github.com/rust-lang/rust/issues/57391#issuecomment-717681193
2. introduced in #76114 which added `duration_saturating_ops`
and accordingly should be folded into `duration_saturating_ops` and therefore stabilized.
r? `@m-ou-se`
move core::hint::black_box under its own feature gate
The `black_box` function had its own RFC and is tracked separately from the `test` feature at https://github.com/rust-lang/rust/issues/64102. Let's reflect this in the feature gate.
To avoid breaking all the benchmarks, libtest's `test::black_box` is a wrapping definition, not a reexport -- this means it is still under the `test` feature gate.
Cautiously add IntoIterator for arrays by value
Add the attribute described in #84133, `#[rustc_skip_array_during_method_dispatch]`, which effectively hides a trait from method dispatch when the receiver type is an array.
Then cherry-pick `IntoIterator for [T; N]` from #65819 and gate it with that attribute. Arrays can now be used as `IntoIterator` normally, but `array.into_iter()` has edition-dependent behavior, returning `slice::Iter` for 2015 and 2018 editions, or `array::IntoIter` for 2021 and later.
r? `@nikomatsakis`
cc `@LukasKalbertodt` `@rust-lang/libs`
Duration is used in std to represent a difference between two Instants.
As such, it has to at least contain that span of time in it. However,
Instant can vary by platform. Thus, we should explain the impl of
Duration::MAX is sensitive to these vagaries of the platform.
further split up const_fn feature flag
This continues the work on splitting up `const_fn` into separate feature flags:
* `const_fn_trait_bound` for `const fn` with trait bounds
* `const_fn_unsize` for unsizing coercions in `const fn` (looks like only `dyn` unsizing is still guarded here)
I don't know if there are even any things left that `const_fn` guards... at least libcore and liballoc do not need it any more.
`@oli-obk` are you currently able to do reviews?
Mention FusedIterator case in Iterator::fuse doc
Using `fuse` on an iterator that incorrectly implements
`FusedIterator` does not fuse the iterator. This commit adds a
note about this in the documentation of this method to increase
awareness about this potential issue (esp. when relying on fuse
in unsafe code).
Closes#83969
implement `TrustedRandomAccess` for `Take` iterator adapter
`TrustedRandomAccess` requires the iterator length to fit within `usize`. `take(n)` only constrains the upper bound of an iterator. So if the inner is `TrustedRandomAccess` (which already implies a finite length) then so can be `Take`.
```````@rustbot``````` label T-libs-impl
Improve `Iterator::by_ref` example
I split the example into two: one that fails to compile, and one that
works. I also made them identical except for the addition of `by_ref`
so we don't confuse readers with random differences.
cc `@steveklabnik,` who is the one that added the previous version of this example
Using `fuse` on an iterator that incorrectly implements
`FusedIterator` does not fuse the iterator. This commit adds a
note about this in the documentation of this method to increase
awareness about this potential issue (esp. when relying on fuse
in unsafe code).
Added CharIndices::offset function
The CharIndices iterator has a field internally called front_offset, that I think would be very useful to have access to.
You can already do something like ``char_indices.next().map(|(offset, _)| offset)``, but that is wordy, in addition to not handling the case where the iterator has ended, where you'd want the offset to be equal to the length.
I'm very new to the open source world and the rust repository, so I'm sorry if I missed a step or did something weird.
Implement indexing slices with pairs of core::ops::Bound<usize>
Closes#49976.
I am not sure about code duplication between `check_range` and `into_maybe_range`. Should be former implemented in terms of the latter? Also this PR doesn't address code duplication between `impl SliceIndex for Range*`.
Format `Struct { .. }` on one line even with `{:#?}`.
The result of `debug_struct("A").finish_non_exhaustive()` before this change:
```
A {
..
}
```
And after this change:
```
A { .. }
```
If there's any fields, the result stays unchanged:
```
A {
field: value,
..
}
fix 'const-stable since' for NonZeroU*::new_unchecked
For the unsigned `NonZero` types, `new_unchecked` was const-stable from the start with https://github.com/rust-lang/rust/pull/50808. Fix the docs to accurately reflect that.
I think this `since` is also incorrect:
```rust
#[stable(feature = "from_nonzero", since = "1.31.0")]
impl From<$Ty> for $Int {
```
The signed nonzero types were only stabilized in 1.34, so that `From` impl certainly didn't exist before. But I had enough of digging through git histories after I figured out when `new_unchecked` became const-stable...^^
Replace all `fmt.pad` with `debug_struct`
This replaces any occurrence of:
- `f.pad("X")` with `f.debug_struct("X").finish()`
- `f.pad("X { .. }")` with `f.debug_struct("X").finish_non_exhaustive()`
This is in line with existing formatting code such as
1255053067/library/std/src/sync/mpsc/mod.rs (L1470-L1475)
