Add a method to the mpsc::Receiver for producing a non-blocking iterator
Currently, the `mpsc::Receiver` offers methods for receiving values in both blocking (`recv`) and non-blocking (`try_recv`) flavours. However only blocking iteration over values is supported. This PR adds a non-blocking iterator to complement the `try_recv` method, just as the blocking iterator complements the `recv` method.
Use-case
-------------
I predominantly use rust in my work on real-time systems and in particular real-time audio generation/processing. I use `mpsc::channel`s to communicate between threads in a purely non-blocking manner. I.e. I might send messages from the GUI thread to the audio thread to update the state of the dsp-graph, or from the audio thread to the GUI thread to display the RMS of each node. These are just a couple examples (I'm probably using 30+ channels across my various projects). I almost exclusively use the `mpsc::Receiver::try_recv` method to avoid blocking any of the real-time threads and causing unwanted glitching/stuttering. Now that I mention it, I can't think of a single time that I personally have used the `recv` method (though I can of course see why it would be useful, and perhaps the common case for many people).
As a result of this experience, I can't help but feel there is a large hole in the `Receiver` API.
| blocking | non-blocking |
|------------|--------------------|
| `recv` | `try_recv` |
| `iter` | 🙀 |
For the most part, I've been working around this using `while let Ok(v) = r.try_recv() { ... }`, however as nice as this is, it is clearly no match for the Iterator API.
As an example, in the majority of my channel use cases I only want to check for *n* number of messages before breaking from the loop so that I don't miss the audio IO callback or hog the GUI thread for too long when an unexpectedly large number of messages are sent. Currently, I have to write something like this:
```rust
let mut take = 100;
while let Ok(msg) = rx.try_recv() {
// Do stuff with msg
if take == 0 {
break;
}
take -= 1;
}
```
or wrap the `try_recv` call in a `Range<usize>`/`FilterMap` iterator combo.
On the other hand, this PR would allow for the following:
```rust
for msg in rx.try_iter().take(100) {
// Do stuff with msg
}
```
I imagine this might also be useful to game devs, embedded or anyone doing message passing across real-time threads.
Add IpAddr common methods
Per https://github.com/rust-lang/rfcs/pull/1668#issuecomment-230867962 no RFC is needed here.
The generated documentation for these methods is being weird. It shows a deprecation message referencing #27709 for each of them even though two of the referenced methods were stabilized as part of that issue. I don't know how best to address that.
Add some warnings to std::env::current_exe
/cc #21889 @rust-lang/libs @semarie
I started writing this up. I'm not sure if we want to go into other things and in what depth; we don't currently have a lot of security-specific documentation to model after.
Thoughts?
Retry on EINTR in Bytes and Chars.
>Since Bytes and Chars called directly into Read::read, they didn't use any of the retrying wrappers. This allows both iterator types to retry.
doc: Mention that writeln! and println! always use LF
Fixes#34697
I'm not really satisfied with the wording, but I didn't have a better idea. Suggestions welcome.
std: fix `readdir` errors for solaris
A `NULL` from `readdir` could be the end of stream or an error. The only
way to know is to check `errno`, so it must be set to a known value first,
like a 0 that POSIX will never use.
This currently only matters for solaris targets, as the other unix platforms
are using `readdir_r` with a direct error return indication. However, this is
getting deprecated (#34668) so they should all eventually switch to `readdir`.
This PR adds `set_errno`, uses it to clear the value before calling `readdir`,
then checks it again after to see the reason for a `NULL`. A few other small
fixes are included just to get solaris compiling at all.
I couldn't get cross-compilation completely going, so I don't have a good way
to test this beyond a smoke-test cargo build of std. I'd appreciate input from
someone more familiar with solaris -- cc @nbaksalyar?
Mutex and RwLock need RefUnwindSafe too
Incomplete, because I don't know what the appropriate stability annotation is here, but this is an attempt to bring the documentation for `std::panic` in line with reality. Right now, it says:
>Types like `&Mutex<T>`, however, are unwind safe because they implement poisoning by default.
But only `Mutex<T>`, not `&Mutex<T>`, is unwind-safe.
Mark Ipv4Addr is_unspecified as stable and provide reference.
Per [#27709 (comment)](https://github.com/rust-lang/rust/issues/27709#issuecomment-231280999), no RFC is needed here.
IPv4 "unspecified" has been defined in [Stevens], and has been part of the IPv4 stack for quite some time. This property should become stable, since this use of 0.0.0.0 is not going anywhere.
[Stevens][_UNIX Network Programming Volume 1, Second Edition_. Stevens, W. Richard. Prentice-Hall, 1998. p. 891]
Please let me know if I got the rustdoc wrong or something. I tried to be as terse as possible while still conveying the appropriate information.
This also has a slight impact on PR #34694, but that one came first, so this shouldn't block it, IMO.
std: Clean out deprecated APIs
This primarily removes a lot of `sync::Static*` APIs and rejiggers the
associated implementations. While doing this it was discovered that the
`is_poisoned` method can actually result in a data race for the Mutex/RwLock
primitives, so the inner `Cell<bool>` was changed to an `AtomicBool` to prevent
the associated data race. Otherwise the usage/gurantees should be the same
they were before.
This primarily removes a lot of `sync::Static*` APIs and rejiggers the
associated implementations. While doing this it was discovered that the
`is_poisoned` method can actually result in a data race for the Mutex/RwLock
primitives, so the inner `Cell<bool>` was changed to an `AtomicBool` to prevent
the associated data race. Otherwise the usage/gurantees should be the same
they were before.
A `NULL` from `readdir` could be the end of stream or an error. The
only way to know is to check `errno`, so it must be set to a known value
first, like a 0 that POSIX will never use.
This patch adds `set_errno`, uses it to clear the value before calling
`readdir`, then checks it again after to see the reason for a `NULL`.
The `use ffi::CStr` in `unix/thread.rs` was previously guarded, but now
all platforms need it for `Thread::set_name()`. Newlib and Solaris do
nothing here, as they have no way to set a thread name, but they still
define the same method signature.
* Link to `process::Command` from `process::Child`.
* Move out inline Markdown link in doc comment.
* Link to `process::Child::wait` from `process::Child`.
* Link to `process::Child` from `process::ChildStdin`.
* Link to `process::Child` from `process::ChildStdout`.
* Link to `process::Child` from `process::ChildStderr`.
