Prior to this commit, the contents of the Unstable Book were assumed to
be unstable features. This commit moves features into 'language features'
or 'library features' subsections. It also moves the 'linker_flavor'
compiler flag into a new 'Compiler Flags' subsection.
Even though it was helpful, I removed the tidy check that
cross-references the SUMMARY.md links with the Unstable Book directory
contents just because it would be difficult to maintain.
Relevant PR: https://github.com/rust-lang/rust/issues/41142.
Add `as_bytes()` for `FromUtf8Error`.
This change allows to obtain an underlying invalid UTF-8 bytes without `FromUtf8Error` destruction. Such method may be useful for example in a library that attempts to save both valid and invalid UTF-8 strings in some struct and to be able to provide immutable access to it without destruction.
Personally without this change I ended with `Result<String, (Vec<u8>, Utf8Error)`, which almost copies the functionality of `FromUtf8Error`, but allows immutable view access.
Add functions to safely transmute float to int
The safe subset of Rust tries to be as powerful as possible. While it is very powerful already, its currently impossible to safely transmute integers to floats. While crates exist that provide a safe interface, most prominently the `iee754` crate (which also inspired naming of the added functions), they themselves only use the unsafe `mem::transmute` function to accomplish this task.
Also, including an entire crate for just two lines of unsafe code seems quite wasteful.
That's why this PR adds functions to safely transmute integers to floats and vice versa, currently gated by the newly added `float_bits_conv` feature.
The functions added are no niche case. Not just `ieee754` [currently implements](https://github.com/huonw/ieee754/blob/master/src/lib.rs#L441) float to int transmutation via unsafe code but also the [very popular `byteorder` crate](https://github.com/BurntSushi/byteorder/blob/1.0.0/src/lib.rs#L258). This functionality of byteorder is in turn used by higher level crates. I only give two examples out of many: [chor](a7363ea9aa/src/ser.rs (L227)) and [bincode](f06a4cfcb5/src/serde/reader.rs (L218)).
One alternative would be to manually use functions like pow or multiplication by 1 to get a similar result, but they only work in the int -> float direction, and are not bit exact, and much slower (also, most likely the optimizer will never optimize it to a transmute because the conversion is not bit exact while the transmute is).
Tracking issue: #40470
Rename compiler_barrier to compiler_fence
This addresses concerns raised following the merge of #41092. Specifically:
> The naming of these seems surprising: the multithreaded functions (and both the single and multithreaded intrinsics themselves) are fences, but this is a barrier. It's not incorrect, but the latter is both inconsistent with the existing functions and slightly confusing with another type in std (e.g., `Barrier`).
`compiler_fence` carries the same semantic implication that this is a compiler-only operation, while being more in line with the fence/barrier concepts already in use in `std`.
:vis matcher for macro_rules
Resurrection of @DanielKeep's implementation posted with [RFC 1575](https://github.com/rust-lang/rfcs/pull/1575).
@jseyfried was of the opinion that this doesn't need an RFC.
Needed before merge:
- [x] sign-off from @DanielKeep since I stole his code
- [x] feature gate
- [x] docs
Specialize Vec::from_elem to use calloc
Fixes#38723. This specializes the implementation for `u8` only, but it could be extended to other zeroable types if desired.
I haven't tested this extensively, but I did verify that it gives the expected performance boost for large `vec![0; n]` allocations with both alloc_system and jemalloc, on Linux. (I have not tested or even built the Windows code.)
Implement global_asm!() (RFC 1548)
This is a first attempt. ~~One (potential) problem I haven't solved is how to handle multiple usages of `global_asm!` in a module/crate. It looks like `LLVMSetModuleInlineAsm` overwrites module asm, and `LLVMAppendModuleInlineAsm` is not provided in LLVM C headers 😦~~
I can provide more detail as needed, but honestly, there's not a lot going on here.
r? @eddyb
CC @Amanieu @jackpot51
Tracking issue: #35119
This addresses concerns raised following the merge of #41092.
Specifically:
> The naming of these seems surprising: the multithreaded functions (and
> both the single and multithreaded intrinsics themselves) are fences,
> but this is a barrier. It's not incorrect, but the latter is both
> inconsistent with the existing functions and slightly confusing with
> another type in std (e.g., `Barrier`).
`compiler_fence` carries the same semantic implication that this is a
compiler-only operation, while being more in line with the fence/barrier
concepts already in use in `std`.
Add a resource-reusing method to `ToOwned`
`ToOwned::to_owned` generalizes `Clone::clone`, but `ToOwned` doesn't have an equivalent to `Clone::clone_from`. This PR adds such a method as `clone_into` under a new unstable feature `toowned_clone_into`.
Analogous to `clone_from`, this has the obvious default implementation in terms of `to_owned`. I've updated the `libcollections` impls: for `T:Clone` it uses `clone_from`, for `[T]` I moved the code from `Vec::clone_from` and implemented that in terms of this, and for `str` it's a predictable implementation in terms of `[u8]`.
Used it in `Cow::clone_from` to reuse resources when both are `Cow::Owned`, and added a test that `Cow<str>` thus keeps capacity in `clone_from` in that situation.
The obvious question: is this the right place for the method?
- It's here so it lives next to `to_owned`, making the default implementation reasonable, and avoiding another trait. But allowing method syntax forces a name like `clone_into`, rather than something more consistent like `owned_from`.
- Another trait would allow `owned_from` and could support multiple owning types per borrow type. But it'd be another single-method trait that generalizes `Clone`, and I don't know how to give it a default impl in terms of `ToOwned::to_owned`, since a blanket would mean overlapping impls problems.
I did it this way as it's simpler and many of the `Borrow`s/`AsRef`s don't make sense with `owned_from` anyway (`[T;1]:Borrow<[T]>`, `Arc<T>:Borrow<T>`, `String:AsRef<OsStr>`...). I'd be happy to re-do it the other way, though, if someone has a good solution for the default handling.
(I can also update with `CStr`, `OsStr`, and `Path` once a direction is decided.)
to_owned generalizes clone; this generalizes clone_from. Use to_owned to
give it a default impl. Customize the impl for [T], str, and T:Clone.
Use it in Cow::clone_from to reuse resources when cloning Owned into Owned.
Reduce str transmutes, add mut versions of methods.
When I was working on the various parts involved in #40380 one of the comments I got was the excess of transmutes necessary to make the changes work. This is part of a set of multiple changes I'd like to offer to fix this problem.
I think that having these methods is reasonable because they're already possible via transmutes, and it makes the code that uses them safer. I can also add `pub(crate)` to these methods for now if the libs team would rather not expose them to the public without an RFC.
-Z linker-flavor
(Please read the commit message first)
This PR is an alternative to rust-lang/rust#36120 (internal lld linker). The
main goal of this PR is to make it *possible* to use LLD as a linker to allow
out of tree experimentation. Now that LLD is going to be shipped with LLVM 4.0,
it should become easier to get a hold of LLD (hopefully, it will be packaged by
Linux distros soon).
Since LLD is a multiarch linker, it has the potential to make cross compilation
easier (less tools need to be installed). Supposedly, LLD is also faster than
the gold linker so LLD may improve build times where link times are significant
(e.g. 100% incremental compilation reuse).
The place where LLD shines is at linking Rust programs that don't depend on
system libraries. For example, here's how you would link a bare metal ARM
Cortex-M program:
```
$ xargo rustc --target thumbv7m-none-eabi -- -Z linker-flavor=ld -C linker=ld.lld -Z print-link-args
"ld.lld" \
"-L" \
"$XARGO_HOME/lib/rustlib/thumbv7m-none-eabi/lib" \
"$PWD/target/thumbv7m-none-eabi/debug/deps/app-de1f86df314ad68c.0.o" \
"-o" \
"$PWD/target/thumbv7m-none-eabi/debug/deps/app-de1f86df314ad68c" \
"--gc-sections" \
"-L" \
"$PWD/target/thumbv7m-none-eabi/debug/deps" \
"-L" \
"$PWD/target/debug/deps" \
"-L" \
"$XARGO_HOME/lib/rustlib/thumbv7m-none-eabi/lib" \
"-Bstatic" \
"-Bdynamic" \
"$XARGO_HOME/lib/rustlib/thumbv7m-none-eabi/lib/libcore-11670d2bd4951fa7.rlib"
$ file target/thumbv7m-none-eabi/debug/app
app: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), statically linked, not stripped, with debug_info
```
This doesn't require installing the `arm-none-eabi-gcc` toolchain.
Even cooler (but I'm biased) is that you can link Rust programs that use
[`steed`] (`steed` is a `std` re-implementation free of C dependencies for Linux
systems) instead of `std` for a bunch of different architectures without having
to install a single cross toolchain.
[`steed`]: https://github.com/japaric/steed
```
$ xargo rustc --target aarch64-unknown-linux-steed --example hello --release -- -Z print-link-args
"ld.lld" \
"-L" \
"$XARGO_HOME/lib/rustlib/aarch64-unknown-linux-steed/lib" \
"$PWD/target/aarch64-unknown-linux-steed/release/examples/hello-80c130ad884c0f8f.0.o" \
"-o" \
"$PWD/target/aarch64-unknown-linux-steed/release/examples/hello-80c130ad884c0f8f" \
"--gc-sections" \
"-L" \
"$PWD/target/aarch64-unknown-linux-steed/release/deps" \
"-L" \
"$PWD/target/release/deps" \
"-L" \
"$XARGO_HOME/lib/rustlib/aarch64-unknown-linux-steed/lib" \
"-Bstatic" \
"-Bdynamic" \
"/tmp/rustc.lAybk9Ltx93Q/libcompiler_builtins-589aede02de78434.rlib"
$ file target/aarch64-unknown-linux-steed/release/examples/hello
hello: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), statically linked, not stripped, with debug_info
```
All these targets (architectures) worked with LLD:
- [aarch64-unknown-linux-steed](https://github.com/japaric/steed/blob/lld/docker/aarch64-unknown-linux-steed.json)
- [arm-unknown-linux-steedeabi](https://github.com/japaric/steed/blob/lld/docker/arm-unknown-linux-steedeabi.json)
- [arm-unknown-linux-steedeabihf](https://github.com/japaric/steed/blob/lld/docker/arm-unknown-linux-steedeabihf.json)
- [armv7-unknown-linux-steedeabihf](https://github.com/japaric/steed/blob/lld/docker/armv7-unknown-linux-steedeabihf.json)
- [i686-unknown-linux-steed](https://github.com/japaric/steed/blob/lld/docker/i686-unknown-linux-steed.json)
- [mips-unknown-linux-steed](https://github.com/japaric/steed/blob/lld/docker/mips-unknown-linux-steed.json)
- [mipsel-unknown-linux-steed](https://github.com/japaric/steed/blob/lld/docker/mipsel-unknown-linux-steed.json)
- [powerpc-unknown-linux-steed](https://github.com/japaric/steed/blob/lld/docker/powerpc-unknown-linux-steed.json)
- [powerpc64-unknown-linux-steed](https://github.com/japaric/steed/blob/lld/docker/powerpc64-unknown-linux-steed.json)
- [x86_64-unknown-linux-steed](https://github.com/japaric/steed/blob/lld/docker/x86_64-unknown-linux-steed.json)
---
The case where lld is unergonomic is linking binaries that depend on system
libraries. Like "Hello, world" for `x86_64-unknown-linux-gnu`. Because you have
to pass as linker arguments: the path to the startup objects, the path to the
dynamic linker and the library search paths. And all those are system specific
so they can't be encoded in the target itself.
```
$ cargo \
rustc \
--release \
-- \
-C \
linker=ld.lld \
-Z \
linker-flavor=ld \
-C \
link-args='-dynamic-linker /lib64/ld-linux-x86-64.so.2 -L/usr/lib -L/usr/lib/gcc/x86_64-pc-linux-gnu/6.3.1 /usr/lib/Scrt1.o /usr/lib/crti.o /usr/lib/gcc/x86_64-pc-linux-gnu/6.3.1/crtbeginS.o /usr/lib/gcc/x86_64-pc-linux-gnu/6.3.1/crtendS.o /usr/lib/crtn.o'
```
---
Another case where `-Z linker-flavor` may come in handy is directly calling
Solaris' linker which is also a multiarch linker (or so I have heard). cc
@binarycrusader
cc @alexcrichton
Heads up: [breaking-change] due to changes in the target specification format.
Add safe wrapper for atomic_compilerfence intrinsics
This PR adds a proposed safe wrapper for the `atomic_singlethreadfence_*` intrinsics introduced by [RFC #888](https://github.com/rust-lang/rfcs/pull/888). See #41091 for further discussion.
#[used] attribute
(For an explanation of what this feature does, read the commit message)
I'd like to propose landing this as an experimental feature (experimental as in:
no clear stabilization path -- like `asm!`, `#[linkage]`) as it's low
maintenance (I think) and relevant to the "Usage in resource-constrained
environments" exploration area.
The main use case I see is running code before `main`. This could be used, for
instance, to cheaply initialize an allocator before `main` where the alternative
is to use `lazy_static` to initialize the allocator on its first use which it's
more expensive (atomics) and doesn't work on ARM Cortex-M0 microcontrollers (no
`AtomicUsize` on that platform)
Here's a `std` example of that:
``` rust
unsafe extern "C" fn before_main_1() {
println!("Hello");
}
unsafe extern "C" fn before_main_2() {
println!("World");
}
#[link_section = ".init_arary"]
#[used]
static INIT_ARRAY: [unsafe extern "C" fn(); 2] = [before_main_1, before_main_2];
fn main() {
println!("Goodbye");
}
```
```
$ rustc -C lto -C opt-level=3 before_main.rs
$ ./before_main
Hello
World
Goodbye
```
In general, this pattern could be used to let *dependencies* run code before
`main` (which sounds like it could go very wrong in some cases). There are
probably other use cases; I hope that the people I have cc-ed can comment on
those.
Note that I'm personally unsure if the above pattern is something we want to
promote / allow and that's why I'm proposing this feature as experimental. If
this leads to more footguns than benefits then we can just axe the feature.
cc @nikomatsakis ^ I know you have some thoughts on having a process for
experimental features though I'm fine with writing an RFC before landing this.
- `dead_code` lint will have to be updated to special case `#[used]` symbols.
- Should we extend `#[used]` to work on non-generic functions?
cc rust-lang/rfcs#1002
cc rust-lang/rfcs#1459
cc @dpc @JinShil
