Centralize panic macro documentation
This is just the main commit from #61511 (which got closed because the author didn't reply) cherry-picked on the current master. Building `core` and `std` on this branch in stage 1 succeeded, which I thinks means the issues from the previous PR should be gone (but let's see what CI says).
Remove some stack frames from `.async` calls
The `Context` argument is currently smuggled through TLS for
async-generated futures. The current infrastructure is closure-based,
and results in an extra 6 stack frames when .awaiting an async-generated
future!
```
12: foo::async_b::{{closure}}
at src/main.rs:10
13: <std::future::GenFuture<T> as core::future::future::Future>::poll::{{closure}}
at /rustc/4560ea788cb760f0a34127156c78e2552949f734/src/libstd/future.rs:43
14: std::future::set_task_context
at /rustc/4560ea788cb760f0a34127156c78e2552949f734/src/libstd/future.rs:79
15: <std::future::GenFuture<T> as core::future::future::Future>::poll
at /rustc/4560ea788cb760f0a34127156c78e2552949f734/src/libstd/future.rs:43
16: std::future::poll_with_tls_context::{{closure}}
at /rustc/4560ea788cb760f0a34127156c78e2552949f734/src/libstd/future.rs:121
17: std::future::get_task_context
at /rustc/4560ea788cb760f0a34127156c78e2552949f734/src/libstd/future.rs:111
18: std::future::poll_with_tls_context
at /rustc/4560ea788cb760f0a34127156c78e2552949f734/src/libstd/future.rs:121
19: foo::async_a::{{closure}}
at src/main.rs:6
```
While the long (medium?) term solution is to remove the use of TLS
entirely, we can improve things a bit in the meantime. In particular,
this commit does 2 things:
1. `get_task_context` has been inlined into `poll_with_tls_context`,
removing 2 frames (16 and 17 above).
2. `set_task_context` now returns a guard type that resets the TLS
rather than taking a closure, removing 2 frames (13 and 14 above).
We can also remove frame 18 by removing `poll_with_tls_context` in favor
of a `get_task_context` function which returns a guard, but that
requires adjusting the code generated for .await, so I've left that off
for now.
rename Error::iter_chain() and remove Error::iter_sources()
~~Rename~~
* ~~Error::iter_chain() -> Error::chained()~~
* ~~Error::iter_sources() -> Error::ancestors()~~
* ~~ErrorIter -> Chained and Ancestors~~
according to
https://github.com/rust-lang/rust/issues/58520#issuecomment-527704110
Tracker:
https://github.com/rust-lang/rust/issues/58520
Edit:
Rename
* Error::iter_chain() -> Error::chained()
* ErrorIter -> Chain
So, it seems, that even Path::ancestors() includes itself. So, to avoid confusion and simplify it more, I reduced PR #65557 to only have `chained` and `Chain`.
Rationale:
1. Such iterators are helpful. They should better be stabilized sooner than later.
1. self should be included. It is easy to .skip(1) it. Not including self is harmful because it is harder to add self to the iterator than to remove it.
1. The chosen name should be telling and reflect the fact that self is included. `.chained()` was chosen in honor of error-chain and because the iterator iterates over the chain of errors that is somehow included in self.
1. The resulting iterator is named `Chain` because the `error::Chain` is what we want to have.
Fix broken links in Ipv4Addr::is_benchmarking docs
[The documentation for `Ipv4Addr::is_benchmarking`](https://doc.rust-lang.org/nightly/std/net/struct.Ipv4Addr.html#method.is_benchmarking) is correct — it has the right RFC number — but the Markdown links are broken. Looks like a copy-and-paste error and a typo.
This PR fixes the links to make them clickable.
The `Context` argument is currently smuggled through TLS for
async-generated futures. The current infrastructure is closure-based,
and results in an extra 6 stack frames when .awaiting an async-generated
future!
```
12: foo::async_b::{{closure}}
at src/main.rs:10
13: <std::future::GenFuture<T> as core::future::future::Future>::poll::{{closure}}
at /rustc/4560ea788cb760f0a34127156c78e2552949f734/src/libstd/future.rs:43
14: std::future::set_task_context
at /rustc/4560ea788cb760f0a34127156c78e2552949f734/src/libstd/future.rs:79
15: <std::future::GenFuture<T> as core::future::future::Future>::poll
at /rustc/4560ea788cb760f0a34127156c78e2552949f734/src/libstd/future.rs:43
16: std::future::poll_with_tls_context::{{closure}}
at /rustc/4560ea788cb760f0a34127156c78e2552949f734/src/libstd/future.rs:121
17: std::future::get_task_context
at /rustc/4560ea788cb760f0a34127156c78e2552949f734/src/libstd/future.rs:111
18: std::future::poll_with_tls_context
at /rustc/4560ea788cb760f0a34127156c78e2552949f734/src/libstd/future.rs:121
19: foo::async_a::{{closure}}
at src/main.rs:6
```
While the long (medium?) term solution is to remove the use of TLS
entirely, we can improve things a bit in the meantime. In particular,
this commit does 2 things:
1. `get_task_context` has been inlined into `poll_with_tls_context`,
removing 2 frames (16 and 17 above).
2. `set_task_context` now returns a guard type that resets the TLS
rather than taking a closure, removing 2 frames (13 and 14 above).
We can also remove frame 18 by removing `poll_with_tls_context` in favor
of a `get_task_context` function which returns a guard, but that
requires adjusting the code generated for .await, so I've left that off
for now.
docs: Fix link to BufWriter::flush
One of the links in the docs was being rendered as a literal
open-bracket followed by a single quote, instead of being transformed
into a link. Fix it to match the link earlier in the same paragraph.
Add hooks for Miri panic unwinding
This commits adds in some additional hooks to allow Miri to properly
handle panic unwinding. None of this should have any impact on CTFE mode
This supports https://github.com/rust-lang/miri/pull/693
Consider this example: small_set = 0..2, large_set = 0..1000.
To efficiently compute the union of these sets, we should
* take all elements of the larger set
* for each element of the smaller set check it is not in the larger set
This is exactly what this commit does.
This particular optimization was implemented a year ago, but the
author mistaken `<` and `>`.
Correct deprecated `is_global` IPv6 documentation
This method does currently not return false for the `site_local` unicast address space. The documentation of the `is_unicast_global` method on lines 1352 - 1382 suggests that this is intentional as the site-local prefix must no longer be supported in new implementations, thus the documentation can safely be updated to reflect that information.
If not so, either the `is_unicast_global` method should be updated to exclude the unicast site-local address space, or the `is_global` method itself.
Correct error in documentation for Ipv4Addr method
Correct statement in doctests on line 539 of `is_global` method of the `Ipv4Addr` object, which falsely attributed the tests to the broadcast address.
Refactor sync::Once
`std::sync::Once` contains some tricky code to park and unpark waiting threads. [once_cell](https://github.com/matklad/once_cell) has very similar code copied from here. I tried to add more comments and refactor the code to make it more readable (at least in my opinion). My PR to `once_cell` was rejected, because it is an advantage to remain close to the implementation in std, and because I made a mess of the atomic orderings. So now a PR here, with similar changes to `std::sync::Once`!
The initial goal was to see if there is some way to detect reentrant initialization instead of deadlocking. No luck there yet, but you first have to understand and document the complexities of the existing code 😄.
*Maybe not this entire PR will be acceptable, but I hope at least some of the commits can be useful.*
Individual commits:
#### Rename state to state_and_queue
Just a more accurate description, although a bit wordy. It helped me on a first read through the code, where before `state` was use to encode a pointer in to nodes of a linked list.
#### Simplify loop conditions in RUNNING and add comments
In the relevant loop there are two things to be careful about:
- make sure not to enqueue the current thread only while still RUNNING, otherwise we will never be woken up (the status may have changed while trying to enqueue this thread).
- pick up if another thread just replaced the head of the linked list.
Because the first check was part of the condition of the while loop, the rest of the parking code also had to live in that loop. It took me a while to get the subtlety here, and it should now be clearer.
Also call out that we really have to wait until signaled, otherwise we leave a dangling reference.
#### Don't mutate waiter nodes
Previously while waking up other threads the managing thread would `take()` out the `Thread` struct and use that to unpark the other thread. It is just as easy to clone it, just 24 bytes. This way `Waiter.thread` does not need an `Option`, `Waiter.next` does not need to be a mutable pointer, and there is less data that needs to be synchronised by later atomic operations.
#### Turn Finish into WaiterQueue
In my opinion these changes make it just a bit more clear what is going on with the thread parking stuff.
#### Move thread parking to a seperate function
Maybe controversial, but with this last commit all the thread parking stuff has a reasonably clean seperation from the state changes in `Once`. This is arguably the trickier part of `Once`, compared to the loop in `call_inner`. It may make it easier to reuse parts of this code (see https://github.com/rust-lang/rfcs/pull/2788#discussion_r336729695). Not sure if that ever becomes a reality though.
#### Reduce the amount of comments in call_inner
With the changes from the previous commits, the code pretty much speaks for itself, and the amount of comments is hurting readability a bit.
#### Use more precise atomic orderings
Now the hard one. This is the one change that is not anything but a pure refactor or change of comments.
I have a dislike for using `SeqCst` everywhere, because it hides what the atomics are supposed to do. the rationale was:
> This cold path uses SeqCst consistently because the performance difference really does not matter there, and SeqCst minimizes the chances of something going wrong.
But in my opinion, having the proper orderings and some explanation helps to understand what is going on. My rationale for the used orderings (also included as comment):
When running `Once` we deal with multiple atomics: `Once.state_and_queue` and an unknown number of `Waiter.signaled`.
* `state_and_queue` is used (1) as a state flag, (2) for synchronizing the data that is the result of the `Once`, and (3) for synchronizing `Waiter` nodes.
- At the end of the `call_inner` function we have to make sure the result of the `Once` is acquired. So every load which can be the only one to load COMPLETED must have at least Acquire ordering, which means all three of them.
- `WaiterQueue::Drop` is the only place that may store COMPLETED, and must do so with Release ordering to make result available.
- `wait` inserts `Waiter` nodes as a pointer in `state_and_queue`, and needs to make the nodes available with Release ordering. The load in its `compare_and_swap` can be Relaxed because it only has to compare the atomic, not to read other data.
- `WaiterQueue::Drop` must see the `Waiter` nodes, so it must load `state_and_queue` with Acquire ordering.
- There is just one store where `state_and_queue` is used only as a state flag, without having to synchronize data: switching the state from INCOMPLETE to RUNNING in `call_inner`. This store can be Relaxed, but the read has to be Acquire because of the requirements mentioned above.
* `Waiter.signaled` is both used as a flag, and to protect a field with interior mutability in `Waiter`. `Waiter.thread` is changed in `WaiterQueue::Drop` which then sets `signaled` with Release ordering. After `wait` loads `signaled` with Acquire and sees it is true, it needs to see the changes to drop the `Waiter` struct correctly.
* There is one place where the two atomics `Once.state_and_queue` and `Waiter.signaled` come together, and might be reordered by the compiler or processor. Because both use Aquire ordering such a reordering is not allowed, so no need for SeqCst.
cc @matklad
One of the links in the docs was being rendered as a literal
open-bracket followed by a single quote, instead of being transformed
into a link. Fix it to match the link earlier in the same paragraph.
Improve math log documentation examples
using 2.0.log(2.0) in examples does not make it clear which is the base and number. This example makes it clear for programmers who take a glance at the example by following the calculation. It is more intuitive, and eliminates the need for executing the example in the playground.
Enhance the documentation of BufReader for potential data loss
This is (IMO) and enhancement of the `std::io::BufReader` documentation, that aims to highlight how relatively easy is to end up with data loss when improperly using an instance of this class.
This is following the issue I had figuring out why my application was loosing data, because I focused my attention on the word *multiple instances* of `BufReader` in its `struct` documentation, even if I ever only had one instance.
Link to the issue: https://github.com/tokio-rs/tokio/issues/1662
Improve std:🧵:Result documentation
Thanks to @dtolnay for pointing out the different premise of the contents of the `Err` variant in `std:🧵:Result` WRT normal error handling.
gate rustc_on_unimplemented under rustc_attrs
Move `rustc_on_implemented` from the `on_implemented` gate to `rustc_attrs` as it is internal.
Closes#29628
r? @varkor
Use KERN_ARND syscall for random numbers on NetBSD, same as FreeBSD.
This system call is present on all supported NetBSD versions and provides an endless stream of non-blocking random data from the kernel's ChaCha20-based CSPRNG. It doesn't require a file like `/dev/urandom` to be opened.
The system call is documented here (under kern.arandom):
https://netbsd.gw.com/cgi-bin/man-cgi?sysctl+7+NetBSD-7.0
And defined here:
https://nxr.netbsd.org/xref/src/sys/sys/sysctl.h#273
The semantics are the same as FreeBSD so reading 256 bytes per call is fine.
Similar change for getrandom crate: rust-random/getrandom#115
