std::iter: document iteration over `&T` and `&mut T`
A colleague of mine is new to Rust, and mentioned that it was “slightly
confusing” to figure out what `&mut` does in iterating over `&mut foo`:
```rust
for value in &mut self.my_vec {
// ...
}
```
My colleague had read the `std::iter` docs and not found the answer
there. There is a brief section at the top about “the three forms of
iteration”, which mentions `iter_mut`, but it doesn’t cover the purpose
of `&mut coll` for a collection `coll`. This patch adds an explanatory
section to the docs. I opted to create a new section so that it can
appear after the note that `impl<I: Iterator> IntoIterator for I`, and
it’s nice for the existing “three forms of iteration” to appear near the
top.
Test Plan:
Ran `./x.py doc library/core`, and the result looked good, including
links. Manually copy-pasted the two doctests into the playground and ran
them.
wchargin-branch: doc-iter-by-reference
[rustdoc] Calculate span information on demand instead of storing it ahead of time
This brings `size_of<clean::types::Span>()` down from over 100 bytes (!!) to only 12, the same as rustc. It brings `Item` down even more, from `784` to `680`.
~~TODO: I need to figure out how to do this for the JSON backend too. That uses `From` impls everywhere, which don't allow passing in the `Session` as an argument. `@P1n3appl3,` `@tmandry,` maybe one of you have ideas?~~ Figured it out, fortunately only two functions needed to be changed. I like the `convert_x()` format better than `From` everywhere but I'm open to feedback.
Helps with #79103
Create `rustc_type_ir`
Decided to start small 😄
This PR creates a `rustc_type_ir` crate as part of the WG-Traits plan to create a shared type library.
~~There already exists a `rustc_ty` crate, so I named the new crate `rustc_ty_library`. However I think it would make sense to rename the current `rustc_ty` to something else (e.g. `rustc_ty_passes`) to free the name for this new crate.~~
r? `@jackh726`
Capture precise paths in THIR and MIR
This PR allows THIR and MIR to use the result of the new capture analysis to actually capture precise paths
To achieve we:
- Writeback min capture results to TypeckResults
- Move handling upvars to PlaceBuilder in mir_build
- Lower precise paths in THIR build by reading min_captures
- Search for ancestors in min_capture when trying to build a MIR place which starts off of an upvar
Closes: https://github.com/rust-lang/project-rfc-2229/issues/10
Partly implements: rust-lang/project-rfc-2229#18
Work that remains (not in this PR):
- [ ] [Known bugs when feature gate is enabled](https://github.com/rust-lang/project-rfc-2229/projects/1?card_filter_query=label%3Abug)
- [ ] Use min_capure_map for
- [ ] Liveness analysis
- [ ] rustc_mir/interpret/validity.rs
- [ ] regionck
- [ ] rust-lang/project-rfc-2229#8
- [ ] remove closure_captures and upvar_capture_map
r? `@ghost`
Apply `doc(cfg)` from parent items while collecting trait impls
Because trait impls bypass the standard `clean` hierarchy they do not participate in the `propagate_doc_cfg` pass, so instead we need to pre-collect all possible `doc(cfg)` attributes that will apply to them when cleaning.
fixes#79201
CTFE: tweak abort-on-uninhabited message
Having an "aborted execution:" makes it more consistent with the `Abort` terminator saying "the program aborted execution". Right now, at least one of the two errors will look weird in Miri.
r? `@oli-obk`
Use `def_path_hash_to_def_id` when re-using a `RawDefId`
Fixes#79890
Previously, we just copied a `RawDefId` from the 'old' map to the 'new'
map. However, the `RawDefId` for a given `DefPathHash` may be different
in the current compilation session. Using `def_path_hash_to_def_id`
ensures that the `RawDefId` we use is valid in the current session.
Windows TLS: ManuallyDrop instead of mem::forget
The Windows TLS implementation still used `mem::forget` instead of `ManuallyDrop`, leading to the usual problem of "using" the `Box` when it should not be used any more.
Rollup of 11 pull requests
Successful merges:
- #77027 (Improve documentation for `std::{f32,f64}::mul_add`)
- #79375 (Make the kernel_copy tests more robust/concurrent.)
- #79639 (Add long explanation for E0212)
- #79698 (Add tracking issue template for library features.)
- #79809 (Dogfood `str_split_once()`)
- #79851 (Clarify the 'default is only allowed on...' error)
- #79858 (Update const-fn doc in unstable-book)
- #79860 (Clarify that String::split_at takes a byte index.)
- #79871 (Fix small typo in `wrapping_shl` documentation)
- #79896 (Make search results tab and help button focusable with keyboard)
- #79917 (Use Symbol for inline asm register class names)
Failed merges:
r? `@ghost`
`@rustbot` modify labels: rollup
Use Symbol for inline asm register class names
This takes care of one "FIXME":
// FIXME: use direct symbol comparison for register class names
Instead of using string literals, this uses Symbol for register
class names.
This is part of work I am doing to improve how Symbol interning works.
Make search results tab and help button focusable with keyboard
Fixes https://github.com/rust-lang/rust/issues/79859.
I replaced the element with `button` tag, which allows to focus them (and "click" on them using "enter") using only the keyboard.
cc ``@sersorrel``
r? ``@Manishearth``
Clarify that String::split_at takes a byte index.
To someone skimming through the `String` docs and only reads the first line, the person could interpret "index" to be "char index". Later on in the docs it clarifies, but by adding "byte" it removes that ambiguity.
Clarify the 'default is only allowed on...' error
Code like
impl Foo {
default fn foo() {}
}
will trigger the error
error: `default` is only allowed on items in `impl` definitions
--> src/lib.rs:5:5
|
5 | default fn foo() {}
| -------^^^^^^^^^
| |
| `default` because of this
but that's very confusing! I *did* put it on an item in an impl!
So this commit changes the message to
error: `default` is only allowed on items in trait impls
--> src/lib.rs:5:5
|
5 | default fn foo() {}
| -------^^^^^^^^^
| |
| `default` because of this
Dogfood `str_split_once()`
Part of https://github.com/rust-lang/rust/issues/74773.
Beyond increased clarity, this fixes some instances of a common confusion with how `splitn(2)` behaves: the first element will always be `Some()`, regardless of the delimiter, and even if the value is empty.
Given this code:
```rust
fn main() {
let val = "...";
let mut iter = val.splitn(2, '=');
println!("Input: {:?}, first: {:?}, second: {:?}", val, iter.next(), iter.next());
}
```
We get:
```
Input: "no_delimiter", first: Some("no_delimiter"), second: None
Input: "k=v", first: Some("k"), second: Some("v")
Input: "=", first: Some(""), second: Some("")
```
Using `str_split_once()` makes more clear what happens when the delimiter is not found.
Add tracking issue template for library features.
This adds a issue template for a library tracking issue.
There's already a template for tracking issues, but it's mostly geared towards compiler/language features. A separate template makes it a bit easier to make sure it matches with the process we use for library changes.
Main differences:
- Added a note about how small library features can be added without RFC, and removed the parts that assume there's an RFC.
- Merged the 'Steps' and 'History' sections: Library features are often small enough that there's no multiple steps planned ahead of time.
- Removed the section about avoiding large discussions and opening separate issues for problems with the feature. Library features are usually focussed enough that the discussion about a feature is best kept together in the tracking issue.
- Removed links to the rustc-dev-guide, which are specific to changes in the compiler and language.
Make the kernel_copy tests more robust/concurrent.
These tests write to the same filenames in /tmp and in some cases these files don't get cleaned up properly. This caused issues for us when different users run the tests on the same system, e.g.:
```
---- sys::unix::kernel_copy::tests::bench_file_to_file_copy stdout ----
thread 'sys::unix::kernel_copy::tests::bench_file_to_file_copy' panicked at 'called `Result::unwrap()` on an `Err` value: Os { code: 13, kind: PermissionDenied, message: "Permission denied" }', library/std/src/sys/unix/kernel_copy/tests.rs:71:10
---- sys::unix::kernel_copy::tests::bench_file_to_socket_copy stdout ----
thread 'sys::unix::kernel_copy::tests::bench_file_to_socket_copy' panicked at 'called `Result::unwrap()` on an `Err` value: Os { code: 13, kind: PermissionDenied, message: "Permission denied" }', library/std/src/sys/unix/kernel_copy/tests.rs💯10
```
Use `std::sys_common::io__test::tmpdir()` to solve this.
CC ``@the8472.``
Improve documentation for `std::{f32,f64}::mul_add`
Makes it more clear that performance improvement is not guaranteed when using FMA, even when the target architecture supports it natively.
Add some core::cmp::Ordering helpers
...to allow easier equal-to-or-greater-than and less-than-or-equal-to
comparisons.
Prior to Rust 1.42 a greater-than-or-equal-to comparison might be written
either as a match block, or a traditional conditional check like this:
```rust
if cmp == Ordering::Equal || cmp == Ordering::Greater {
// Do something
}
```
Which requires two instances of `cmp`. Don't forget that while `cmp` here
is very short, it could be something much longer in real use cases.
From Rust 1.42 a nicer alternative is possible:
```rust
if matches!(cmp, Ordering::Equal | Ordering::Greater) {
// Do something
}
```
The commit adds another alternative which may be even better in some cases:
```rust
if cmp.is_equal_or_greater() {
// Do something
}
```
The earlier examples could be cleaner than they are if the variants of
`Ordering` are imported such that `Equal`, `Greater` and `Less` can be
referred to directly, but not everyone will want to do that.
The new solution can shorten lines, help avoid logic mistakes, and avoids
having to import `Ordering` / `Ordering::*`.
Enforce no-move rule of ReentrantMutex using Pin and fix UB in stdio
A `sys_common::ReentrantMutex` may not be moved after initializing it with `.init()`. This was not enforced, but only stated as a requirement in the comments on the unsafe functions. This change enforces this no-moving rule using `Pin`, by changing `&self` to a `Pin` in the `init()` and `lock()` functions.
This uncovered a bug I introduced in #77154: stdio.rs (the only user of ReentrantMutex) called `init()` on its ReentrantMutexes while constructing them in the intializer of `SyncOnceCell::get_or_init`, which would move them afterwards. Interestingly, the ReentrantMutex unit tests already had the same bug, so this invalid usage has been tested on all (CI-tested) platforms for a long time. Apparently this doesn't break badly on any of the major platforms, but it does break the rules.\*
To be able to keep using SyncOnceCell, this adds a `SyncOnceCell::get_or_init_pin` function, which makes it possible to work with pinned values inside a (pinned) SyncOnceCell. Whether this function should be public or not and what its exact behaviour and interface should be if it would be public is something I'd like to leave for a separate issue or PR. In this PR, this function is internal-only and marked with `pub(crate)`.
\* Note: That bug is now included in 1.48, while this patch can only make it to ~~1.49~~ 1.50. We should consider the implications of 1.48 shipping with a wrong usage of `pthread_mutex_t` / `CRITICAL_SECTION` / .. which technically invokes UB according to their specification. The risk is very low, considering the objects are not 'used' (locked) before the move, and the ReentrantMutex unit tests have verified this works fine in practice.
Edit: This has been backported and included in 1.48. And soon 1.49 too.
---
In future changes, I want to push this usage of Pin further inside `sys` instead of only `sys_common`, and apply it to all 'unmovable' objects there (`Mutex`, `Condvar`, `RwLock`). Also, while `sys_common`'s mutexes and condvars are already taken care of by #77147 and #77648, its `RwLock` should still be made movable or get pinned.
This takes care of one "FIXME":
// FIXME: use direct symbol comparison for register class names
Instead of using string literals, this uses Symbol for register
class names.
Fixes#79890
Previously, we just copied a `RawDefId` from the 'old' map to the 'new'
map. However, the `RawDefId` for a given `DefPathHash` may be different
in the current compilation session. Using `def_path_hash_to_def_id`
ensures that the `RawDefId` we use is valid in the current session.
...to allow easier greater-than-or-equal-to and less-than-or-equal-to
comparisons, and variant checking without needing to import the enum,
similar to `Option::is_none()` / `Option::is_some()`, in situations where
you are dealing with an `Ordering` value. (Simple `PartialOrd` / `Ord`
based evaluation may not be suitable for all situations).
Prior to Rust 1.42 a greater-than-or-equal-to comparison might be written
either as a match block, or a traditional conditional check like this:
```rust
if cmp == Ordering::Equal || cmp == Ordering::Greater {
// Do something
}
```
Which requires two instances of `cmp`. Don't forget that while `cmp` here
is very short, it could be something much longer in real use cases.
From Rust 1.42 a nicer alternative is possible:
```rust
if matches!(cmp, Ordering::Equal | Ordering::Greater) {
// Do something
}
```
The commit adds another alternative which may be even better in some cases:
```rust
if cmp.is_ge() {
// Do something
}
```
The earlier examples could be cleaner than they are if the variants of
`Ordering` are imported such that `Equal`, `Greater` and `Less` can be
referred to directly, but not everyone will want to do that.
The new solution can shorten lines, help avoid logic mistakes, and avoids
having to import `Ordering` / `Ordering::*`.
ci: use 20.04 on x86_64-gnu-nopt builder
Switch the `x86_64-gnu-nopt` builder to use Ubuntu 20.04.
Ubuntu 20.04 has a more recent gdb version than Ubuntu 16.04 (9.1 vs 7.11.1), which is required for rust-lang/rust#77177, as 16.04's gdb 7.11.1 crashes in some cases with Split DWARF. `x86_64-gnu-nopt` is chosen because it runs compare modes, which is how Split DWARF testing is implemented in rust-lang/rust#77177.
I've not confirmed that the issue is resolved with gdb 9.1 (Feb 2020), but system was using gdb 9.2 (May 2020) and that was fine and it seems more likely to me that the bug was resolved between gdb 7.11.1 (May 2016) and gdb 9.1.
Updating a builder to use 20.04 was suggested by `@Mark-Simulacrum` in https://github.com/rust-lang/rust/pull/77117#issuecomment-731846170. I'm not sure if this is the only change that is required - if more are necessary then I'm happy to do that.
r? `@pietroalbini`
cc `@Mark-Simulacrum`
