rustdoc: remove the `!` from macro URLs and titles
Because the `!` is part of a macro use, not the macro's name. E.g., you write `macro_rules! foo` not `macro_rules! foo!`, also `#[macro_import(foo)]`.
(Pulled out of #35020).
provide additional justification for array interface design
Explain why Rust does not implement traits for large arrays.
Explain why most methods are implemented on slices rather than arrays.
Note: I'm dipping my toes in the water with a tiny PR. Especially looking for feedback on wording and style. Points of concern: appropriate level of top-level explanation; foreshadowing (is it appropriate to imply that we expect Rust's type system to eventually support size-generic arrays?); using `Foo` and `Bar` as type variables instead of e.g. `T` and `S`.
@peschkaj
Add note to docs for &str that example is to demo internals only
r? @steveklabnik
This adds a note below the &str representation example explaining that the example provided should not be used under normal circumstances..
Would it make sense to point people in the direction of the method(s) they should use instead? I left it out in the interest of not complicating the documentation, but, there's definitely an argument to be made for adding a bit of guidance in there.
Emscripten test fixes
This picks up parts of #31623 to disable certain tests that emscripten can't run, as threads/processes are not supported.
I re-applied @tomaka's changes manually, I can rebase those commits with his credentials if he wants.
It also disables jemalloc for emscripten (at least in Rustbuild, I have to check if there is another setting for the same thing in the old makefile approach).
This should not impact anything for normal builds.
std: Optimize panic::catch_unwind slightly
The previous implementation of this function was overly conservative with
liberal usage of `Option` and `.unwrap()` which in theory never triggers. This
commit essentially removes the `Option`s in favor of unsafe implementations,
improving the code generation of the fast path for LLVM to see through what's
happening more clearly.
cc #34727
The previous implementation of this function was overly conservative with
liberal usage of `Option` and `.unwrap()` which in theory never triggers. This
commit essentially removes the `Option`s in favor of unsafe implementations,
improving the code generation of the fast path for LLVM to see through what's
happening more clearly.
cc #34727
Update HashMap docs regarding DoS protection
Because of changes to how Rust acquires randomness HashMap is not
guaranteed to be DoS resistant. This commit reflects these changes in
the docs themselves and provides an alternative method to creating
a hash that is resistant if needed.
This fixes#33817 and includes relevant information regarding changes made in #33086
Fix build on DragonFly (unused function errno_location)
Function errno_location() is not used on DragonFly. As warnings are
errors, this breaks the build.
Handle RwLock reader count overflow
`pthread_rwlock_rdlock` may return `EAGAIN` if the maximum reader count overflows. We shouldn't return a successful lock in that case.
Because of changes to how Rust acquires randomness HashMap is not
guaranteed to be DoS resistant. This commit reflects these changes in
the docs themselves and provides an alternative method to creating
a hash that is resistant if needed.
Configure condition variables to use monotonic time using
pthread_condattr_setclock on systems where this is possible.
This fixes the issue when thread waiting on condition variable is
woken up too late when system time is moved backwards.
The targets are:
- `arm-unknown-linux-musleabi`
- `arm-unknown-linux-musleabihf`
- `armv7-unknown-linux-musleabihf`
These mirror the existing `gnueabi` targets.
All of these targets produce fully static binaries, similar to the
x86 MUSL targets.
For now these targets can only be used with `--rustbuild` builds, as
https://github.com/rust-lang/compiler-rt/pull/22 only made the
necessary compiler-rt changes in the CMake configs, not the plain
GNU Make configs.
I've tested these targets GCC 5.3.0 compiled again musl-1.1.12
(downloaded from http://musl.codu.org/). An example `./configure`
invocation is:
```
./configure \
--enable-rustbuild
--target=arm-unknown-linux-musleabi \
--musl-root="$MUSL_ROOT"
```
where `MUSL_ROOT` points to the `arm-linux-musleabi` prefix.
Usually that path will be of the form
`/foobar/arm-linux-musleabi/arm-linux-musleabi`.
Usually the cross-compile toolchain will live under
`/foobar/arm-linux-musleabi/bin`. That path should either by added
to your `PATH` variable, or you should add a section to your
`config.toml` as follows:
```
[target.arm-unknown-linux-musleabi]
cc = "/foobar/arm-linux-musleabi/bin/arm-linux-musleabi-gcc"
cxx = "/foobar/arm-linux-musleabi/bin/arm-linux-musleabi-g++"
```
As a prerequisite you'll also have to put a cross-compiled static
`libunwind.a` library in `$MUSL_ROOT/lib`. This is similar to [how
the x86_64 MUSL targets are built]
(https://doc.rust-lang.org/book/advanced-linking.html).
This is to pull in changes to support ARM MUSL targets.
This change also commits a couple of other cargo-generated changes
to other dependencies in the various Cargo.toml files.
rustbuild: make backtraces (RUST_BACKTRACE) optional
but keep them enabled by default to maintain the status quo.
When disabled shaves ~56KB off every x86_64-unknown-linux-gnu
binary.
To disable backtraces you have to use a config.toml (see
src/bootstrap/config.toml.example for details) when building rustc/std:
$ python bootstrap.py --config=config.toml
---
r? @alexcrichton
cc rust-lang/rfcs#1417
Escape fewer Unicode codepoints in `Debug` impl of `str`
Use the same procedure as Python to determine whether a character is
printable, described in [PEP 3138]. In particular, this means that the
following character classes are escaped:
- Cc (Other, Control)
- Cf (Other, Format)
- Cs (Other, Surrogate), even though they can't appear in Rust strings
- Co (Other, Private Use)
- Cn (Other, Not Assigned)
- Zl (Separator, Line)
- Zp (Separator, Paragraph)
- Zs (Separator, Space), except for the ASCII space `' '` `0x20`
This allows for user-friendly inspection of strings that are not
English (e.g. compare `"\u{e9}\u{e8}\u{ea}"` to `"éèê"`).
Fixes#34318.
CC #34422.
[PEP 3138]: https://www.python.org/dev/peps/pep-3138/
std: Fix usage of SOCK_CLOEXEC
This code path was intended to only get executed on Linux, but unfortunately the
`cfg!` was malformed so it actually never got executed.
DoubleEndedIterator for Args
This PR implements the DoubleEndedIterator trait for the `std::env::Args[Os]` structure, as well
as the internal implementations.
It is primarily motivated by me, as I happened to implement a simple `reversor` program many times
now, which so far had to use code like this:
```Rust
for arg in std::env::args().skip(1).collect::<Vec<_>>().iter().rev() {}
```
... even though I would have loved to do this instead:
```Rust
for arg in std::env::args().skip(1).rev() {}
```
The latter is more natural, and I did not find a reason for not implementing it.
After all, on every system, the number of arguments passed to the program are known
at runtime.
To my mind, it follows KISS, and does not try to be smart at all. Also, there are no unit-tests,
primarily as I did not find any existing tests for the `Args` struct either.
The windows implementation is basically a copy-pasted variant of the `next()` method implementation,
and I could imagine sharing most of the code instead. Actually I would be happy if the reviewer would
ask for it.
but keep them enabled by default to maintain the status quo.
When disabled shaves ~56KB off every x86_64-unknown-linux-gnu
binary.
To disable backtraces you have to use a config.toml (see
src/bootstrap/config.toml.example for details) when building rustc/std:
$ python bootstrap.py --config=config.toml
The number of arguments given to a process is always known, which
makes implementing DoubleEndedIterator possible.
That way, the Iterator::rev() method becomes usable, among others.
Signed-off-by: Sebastian Thiel <byronimo@gmail.com>
Tidy for DoubleEndedIterator
I chose to not create a new feature for it, even though
technically, this makes me lie about the original availability
of the implementation.
Verify with @alexchrichton
Setup feature flag for new std::env::Args iterators
Add test for Args reverse iterator
It's somewhat depending on the input of the test program,
but made in such a way that should be somewhat flexible to changes
to the way it is called.
Deduplicate windows ArgsOS code for DEI
DEI = DoubleEndedIterator
Move env::args().rev() test to run-pass
It must be controlling it's arguments for full isolation.
Remove superfluous feature name
Assert all arguments returned by env::args().rev()
Let's be very sure it works as we expect, why take chances.
Fix rval of os_string_from_ptr
A trait cannot be returned, but only the corresponding object.
Deref pointers to actually operate on the argument
Put unsafe to correct location
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`.
Use hints with getaddrinfo() in std::net::lookup_host()
As noted in #24250, `std::net::lookup_host()` repeats each IPv[46] address in the result set. The number of repetitions is OS-dependent; e.g., Linux and FreeBSD give three copies, OpenBSD gives two. Filtering the duplicates can be done by the user if `lookup_host()` is used explicitly, but not with functions like `TcpStream::connect()`. What happens with the latter is that any unsuccessful connection attempt will be repeated as many times as there are duplicates of the address.
The program:
```rust
use std::net::TcpStream;
fn main() {
let _stream = TcpStream::connect("localhost:4444").unwrap();
}
```
results in the following capture:
[capture-before.txt](https://github.com/rust-lang/rust/files/352004/capture-before.txt)
assuming that "localhost" resolves both to ::1 and 127.0.0.1, and that the listening program opens just an IPv4 socket (e.g., `nc -l 127.0.0.1 4444`.) The reason for this behavior is explained in [this comment](https://github.com/rust-lang/rust/issues/24250#issuecomment-92240152): `getaddrinfo()` is not constrained.
Various OSS projects (I checked out Postfix, OpenLDAP, Apache HTTPD and BIND) which use `getaddrinfo()` generally constrain the result set by using a non-NULL `hints` parameter and setting at least `ai_socktype` to `SOCK_STREAM`. `SOCK_DGRAM` would also work. Other parameters are unnecessary for pure name resolution.
The patch in this PR initializes a `hints` struct and passes it to `getaddrinfo()`, which eliminates the duplicates. The same test program as above with this change produces:
[capture-after.txt](https://github.com/rust-lang/rust/files/352042/capture-after.txt)
All `libstd` tests pass with this patch.
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 commit adds a
non-blocking iterator to complement the `try_recv` method, just as the
blocking iterator complements the `recv` method.
Use hints with getaddrinfo() in std::net::lookup_host()
As noted in #24250, `std::net::lookup_host()` repeats each IPv[46] address in the result set. The number of repetitions is OS-dependent; e.g., Linux and FreeBSD give three copies, OpenBSD gives two. Filtering the duplicates can be done by the user if `lookup_host()` is used explicitly, but not with functions like `TcpStream::connect()`. What happens with the latter is that any unsuccessful connection attempt will be repeated as many times as there are duplicates of the address.
The program:
```rust
use std::net::TcpStream;
fn main() {
let _stream = TcpStream::connect("localhost:4444").unwrap();
}
```
results in the following capture:
[capture-before.txt](https://github.com/rust-lang/rust/files/352004/capture-before.txt)
assuming that "localhost" resolves both to ::1 and 127.0.0.1, and that the listening program opens just an IPv4 socket (e.g., `nc -l 127.0.0.1 4444`.) The reason for this behavior is explained in [this comment](https://github.com/rust-lang/rust/issues/24250#issuecomment-92240152): `getaddrinfo()` is not constrained.
Various OSS projects (I checked out Postfix, OpenLDAP, Apache HTTPD and BIND) which use `getaddrinfo()` generally constrain the result set by using a non-NULL `hints` parameter and setting at least `ai_socktype` to `SOCK_STREAM`. `SOCK_DGRAM` would also work. Other parameters are unnecessary for pure name resolution.
The patch in this PR initializes a `hints` struct and passes it to `getaddrinfo()`, which eliminates the duplicates. The same test program as above with this change produces:
[capture-after.txt](https://github.com/rust-lang/rust/files/352042/capture-after.txt)
All `libstd` tests pass with this patch.
