The Unstable Book
Welcome to the Unstable Book! This book consists of a number of chapters, each one organized by a "feature flag." That is, when using an unstable feature of Rust, you must use a flag, like this:
#![feature(box_syntax)] fn main() { let five = box 5; }
The box_syntax feature has a chapter describing how to use it.
Because this documentation relates to unstable features, we make no guarantees that what is contained here is accurate or up to date. It's developed on a best-effort basis. Each page will have a link to its tracking issue with the latest developments; you might want to check those as well.
Compiler flags
emit-stack-sizes
The tracking issue for this feature is: #54192
The rustc flag -Z emit-stack-sizes makes LLVM emit stack size metadata.
NOTE: This LLVM feature only supports the ELF object format as of LLVM 8.0. Using this flag with targets that use other object formats (e.g. macOS and Windows) will result in it being ignored.
Consider this crate:
#![crate_type = "lib"]
use std::ptr;
pub fn foo() {
// this function doesn't use the stack
}
pub fn bar() {
let xs = [0u32; 2];
// force LLVM to allocate `xs` on the stack
unsafe { ptr::read_volatile(&xs.as_ptr()); }
}
Using the -Z emit-stack-sizes flag produces extra linker sections in the
output object file.
$ rustc -C opt-level=3 --emit=obj foo.rs
$ size -A foo.o
foo.o :
section size addr
.text 0 0
.text._ZN3foo3foo17he211d7b4a3a0c16eE 1 0
.text._ZN3foo3bar17h1acb594305f70c2eE 22 0
.note.GNU-stack 0 0
.eh_frame 72 0
Total 95
$ rustc -C opt-level=3 --emit=obj -Z emit-stack-sizes foo.rs
$ size -A foo.o
foo.o :
section size addr
.text 0 0
.text._ZN3foo3foo17he211d7b4a3a0c16eE 1 0
.stack_sizes 9 0
.text._ZN3foo3bar17h1acb594305f70c2eE 22 0
.stack_sizes 9 0
.note.GNU-stack 0 0
.eh_frame 72 0
Total 113
As of LLVM 7.0 the data will be written into a section named .stack_sizes and
the format is "an array of pairs of function symbol values (pointer size) and
stack sizes (unsigned LEB128)".
$ objdump -d foo.o
foo.o: file format elf64-x86-64
Disassembly of section .text._ZN3foo3foo17he211d7b4a3a0c16eE:
0000000000000000 <_ZN3foo3foo17he211d7b4a3a0c16eE>:
0: c3 retq
Disassembly of section .text._ZN3foo3bar17h1acb594305f70c2eE:
0000000000000000 <_ZN3foo3bar17h1acb594305f70c2eE>:
0: 48 83 ec 10 sub $0x10,%rsp
4: 48 8d 44 24 08 lea 0x8(%rsp),%rax
9: 48 89 04 24 mov %rax,(%rsp)
d: 48 8b 04 24 mov (%rsp),%rax
11: 48 83 c4 10 add $0x10,%rsp
15: c3 retq
$ objdump -s -j .stack_sizes foo.o
foo.o: file format elf64-x86-64
Contents of section .stack_sizes:
0000 00000000 00000000 00 .........
Contents of section .stack_sizes:
0000 00000000 00000000 10 .........
It's important to note that linkers will discard this linker section by default. To preserve the section you can use a linker script like the one shown below.
/* file: keep-stack-sizes.x */
SECTIONS
{
/* `INFO` makes the section not allocatable so it won't be loaded into memory */
.stack_sizes (INFO) :
{
KEEP(*(.stack_sizes));
}
}
The linker script must be passed to the linker using a rustc flag like -C link-arg.
// file: src/main.rs
use std::ptr;
#[inline(never)]
fn main() {
let xs = [0u32; 2];
// force LLVM to allocate `xs` on the stack
unsafe { ptr::read_volatile(&xs.as_ptr()); }
}
$ RUSTFLAGS="-Z emit-stack-sizes" cargo build --release
$ size -A target/release/hello | grep stack_sizes || echo section was not found
section was not found
$ RUSTFLAGS="-Z emit-stack-sizes" cargo rustc --release -- \
-C link-arg=-Wl,-Tkeep-stack-sizes.x \
-C link-arg=-N
$ size -A target/release/hello | grep stack_sizes
.stack_sizes 90 176272
$ # non-allocatable section (flags don't contain the "A" (alloc) flag)
$ readelf -S target/release/hello
Section Headers:
[Nr] Name Type Address Offset
Size EntSize Flags Link Info Align
(..)
[1031] .stack_sizes PROGBITS 000000000002b090 0002b0f0
000000000000005a 0000000000000000 L 5 0 1
$ objdump -s -j .stack_sizes target/release/hello
target/release/hello: file format elf64-x86-64
Contents of section .stack_sizes:
2b090 c0040000 00000000 08f00400 00000000 ................
2b0a0 00080005 00000000 00000810 05000000 ................
2b0b0 00000000 20050000 00000000 10400500 .... ........@..
2b0c0 00000000 00087005 00000000 00000080 ......p.........
2b0d0 05000000 00000000 90050000 00000000 ................
2b0e0 00a00500 00000000 0000 ..........
Author note: I'm not entirely sure why, in this case,
-Nis required in addition to-Tkeep-stack-sizes.x. For example, it's not required when producing statically linked files for the ARM Cortex-M architecture.
profile
The tracking issue for this feature is: #42524.
This feature allows the generation of code coverage reports.
Set the -Zprofile compiler flag in order to enable gcov profiling.
For example:
cargo new testgcov --bin
cd testgcov
export RUSTFLAGS="-Zprofile"
cargo build
cargo run
Once you've built and run your program, files with the gcno (after build) and gcda (after execution) extensions will be created.
You can parse them with llvm-cov gcov or grcov.
Language features
aarch64_target_feature
The tracking issue for this feature is: #44839
abi_amdgpu_kernel
The tracking issue for this feature is: #51575
abi_msp430_interrupt
The tracking issue for this feature is: #38487
In the MSP430 architecture, interrupt handlers have a special calling
convention. You can use the "msp430-interrupt" ABI to make the compiler apply
the right calling convention to the interrupt handlers you define.
#![feature(abi_msp430_interrupt)]
#![no_std]
// Place the interrupt handler at the appropriate memory address
// (Alternatively, you can use `#[used]` and remove `pub` and `#[no_mangle]`)
#[link_section = "__interrupt_vector_10"]
#[no_mangle]
pub static TIM0_VECTOR: extern "msp430-interrupt" fn() = tim0;
// The interrupt handler
extern "msp430-interrupt" fn tim0() {
// ..
}
$ msp430-elf-objdump -CD ./target/msp430/release/app
Disassembly of section __interrupt_vector_10:
0000fff2 <TIM0_VECTOR>:
fff2: 00 c0 interrupt service routine at 0xc000
Disassembly of section .text:
0000c000 <int::tim0>:
c000: 00 13 reti
abi_ptx
The tracking issue for this feature is: #38788
When emitting PTX code, all vanilla Rust functions (fn) get translated to
"device" functions. These functions are not callable from the host via the
CUDA API so a crate with only device functions is not too useful!
OTOH, "global" functions can be called by the host; you can think of them
as the real public API of your crate. To produce a global function use the
"ptx-kernel" ABI.
#![feature(abi_ptx)]
#![no_std]
pub unsafe extern "ptx-kernel" fn global_function() {
device_function();
}
pub fn device_function() {
// ..
}
$ xargo rustc --target nvptx64-nvidia-cuda --release -- --emit=asm
$ cat $(find -name '*.s')
//
// Generated by LLVM NVPTX Back-End
//
.version 3.2
.target sm_20
.address_size 64
// .globl _ZN6kernel15global_function17h46111ebe6516b382E
.visible .entry _ZN6kernel15global_function17h46111ebe6516b382E()
{
ret;
}
// .globl _ZN6kernel15device_function17hd6a0e4993bbf3f78E
.visible .func _ZN6kernel15device_function17hd6a0e4993bbf3f78E()
{
ret;
}
abi_thiscall
The tracking issue for this feature is: #42202
The MSVC ABI on x86 Windows uses the thiscall calling convention for C++
instance methods by default; it is identical to the usual (C) calling
convention on x86 Windows except that the first parameter of the method,
the this pointer, is passed in the ECX register.
abi_unadjusted
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
abi_vectorcall
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
abi_x86_interrupt
The tracking issue for this feature is: #40180
adx_target_feature
The tracking issue for this feature is: #44839
alloc_error_handler
The tracking issue for this feature is: #51540
allocator_internals
This feature does not have a tracking issue, it is an unstable implementation
detail of the global_allocator feature not intended for use outside the
compiler.
allow_fail
The tracking issue for this feature is: #46488
allow_internal_unsafe
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
allow_internal_unstable
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
arbitrary_enum_discriminant
The tracking issue for this feature is: #60553
The arbitrary_enum_discriminant feature permits tuple-like and
struct-like enum variants with #[repr(<int-type>)] to have explicit discriminants.
Examples
# #![allow(unused_variables)] #![feature(arbitrary_enum_discriminant)] #fn main() { #[allow(dead_code)] #[repr(u8)] enum Enum { Unit = 3, Tuple(u16) = 2, Struct { a: u8, b: u16, } = 1, } impl Enum { fn tag(&self) -> u8 { unsafe { *(self as *const Self as *const u8) } } } assert_eq!(3, Enum::Unit.tag()); assert_eq!(2, Enum::Tuple(5).tag()); assert_eq!(1, Enum::Struct{a: 7, b: 11}.tag()); #}
arbitrary_self_types
The tracking issue for this feature is: #44874
arm_target_feature
The tracking issue for this feature is: #44839
associated_type_bounds
The tracking issue for this feature is: #52662
associated_type_defaults
The tracking issue for this feature is: #29661
async_closure
The tracking issue for this feature is: #62290
avx512_target_feature
The tracking issue for this feature is: #44839
box_patterns
The tracking issue for this feature is: #29641
See also box_syntax
Box patterns let you match on Box<T>s:
#![feature(box_patterns)] fn main() { let b = Some(Box::new(5)); match b { Some(box n) if n < 0 => { println!("Box contains negative number {}", n); }, Some(box n) if n >= 0 => { println!("Box contains non-negative number {}", n); }, None => { println!("No box"); }, _ => unreachable!() } }
box_syntax
The tracking issue for this feature is: #49733
See also box_patterns
Currently the only stable way to create a Box is via the Box::new method.
Also it is not possible in stable Rust to destructure a Box in a match
pattern. The unstable box keyword can be used to create a Box. An example
usage would be:
#![feature(box_syntax)] fn main() { let b = box 5; }
c_variadic
The tracking issue for this feature is: #44930
The c_variadic language feature enables C-variadic functions to be
defined in Rust. The may be called both from within Rust and via FFI.
Examples
# #![allow(unused_variables)] #![feature(c_variadic)] #fn main() { pub unsafe extern "C" fn add(n: usize, mut args: ...) -> usize { let mut sum = 0; for _ in 0..n { sum += args.arg::<usize>(); } sum } #}
cfg_doctest
The tracking issue for this feature is: #62210
cfg_target_has_atomic
The tracking issue for this feature is: #32976
cfg_target_thread_local
The tracking issue for this feature is: #29594
cmpxchg16b_target_feature
The tracking issue for this feature is: #44839
compiler_builtins
This feature is internal to the Rust compiler and is not intended for general use.
const_compare_raw_pointers
The tracking issue for this feature is: #53020
const_constructor
The tracking issue for this feature is: #61456
const_fn
The tracking issue for this feature is: #57563
The const_fn feature allows marking free functions and inherent methods as
const, enabling them to be called in constants contexts, with constant
arguments.
Examples
#![feature(const_fn)] const fn double(x: i32) -> i32 { x * 2 } const FIVE: i32 = 5; const TEN: i32 = double(FIVE); fn main() { assert_eq!(5, FIVE); assert_eq!(10, TEN); }
const_fn_union
The tracking issue for this feature is: #51909
const_generics
The tracking issue for this feature is: #44580
const_in_array_repeat_expressions
The tracking issue for this feature is: [#49147]
Relaxes the rules for repeat expressions, [x; N] such that x may also be const (strictly
speaking rvalue promotable), in addition to typeof(x): Copy. The result of [x; N] where x is
const is itself also const.
const_panic
The tracking issue for this feature is: #51999
const_raw_ptr_deref
The tracking issue for this feature is: #51911
const_raw_ptr_to_usize_cast
The tracking issue for this feature is: #51910
const_transmute
The tracking issue for this feature is: #53605
crate_visibility_modifier
The tracking issue for this feature is: #53120
The crate_visibility_modifier feature allows the crate keyword to be used
as a visibility modifier synonymous to pub(crate), indicating that a type
(function, &c.) is to be visible to the entire enclosing crate, but not to
other crates.
# #![allow(unused_variables)] #![feature(crate_visibility_modifier)] #fn main() { crate struct Foo { bar: usize, } #}
custom_attribute
The tracking issue for this feature is: #29642
custom_inner_attributes
The tracking issue for this feature is: #54726
custom_test_frameworks
The tracking issue for this feature is: #50297
The custom_test_frameworks feature allows the use of #[test_case] and #![test_runner].
Any function, const, or static can be annotated with #[test_case] causing it to be aggregated (like #[test])
and be passed to the test runner determined by the #![test_runner] crate attribute.
# #![allow(unused_variables)] #![feature(custom_test_frameworks)] #![test_runner(my_runner)] #fn main() { fn my_runner(tests: &[&i32]) { for t in tests { if **t == 0 { println!("PASSED"); } else { println!("FAILED"); } } } #[test_case] const WILL_PASS: i32 = 0; #[test_case] const WILL_FAIL: i32 = 4; #}
decl_macro
The tracking issue for this feature is: #39412
default_type_parameter_fallback
The tracking issue for this feature is: #27336
doc_alias
The tracking issue for this feature is: #50146
You can add alias(es) to an item when using the rustdoc search through the
doc(alias) attribute. Example:
# #![allow(unused_variables)] #![feature(doc_alias)] #fn main() { #[doc(alias = "x")] #[doc(alias = "big")] pub struct BigX; #}
Then, when looking for it through the rustdoc search, if you enter "x" or
"big", search will show the BigX struct first.
Note that this feature is currently hidden behind the feature(doc_alias) gate.
doc_cfg
The tracking issue for this feature is: #43781
The doc_cfg feature allows an API be documented as only available in some specific platforms.
This attribute has two effects:
-
In the annotated item's documentation, there will be a message saying "This is supported on (platform) only".
-
The item's doc-tests will only run on the specific platform.
In addition to allowing the use of the #[doc(cfg)] attribute, this feature enables the use of a
special conditional compilation flag, #[cfg(rustdoc)], set whenever building documentation on your
crate.
This feature was introduced as part of PR #43348 to allow the platform-specific parts of the standard library be documented.
# #![allow(unused_variables)] #![feature(doc_cfg)] #fn main() { #[cfg(any(windows, rustdoc))] #[doc(cfg(windows))] /// The application's icon in the notification area (a.k.a. system tray). /// /// # Examples /// /// ```no_run /// extern crate my_awesome_ui_library; /// use my_awesome_ui_library::current_app; /// use my_awesome_ui_library::windows::notification; /// /// let icon = current_app().get::<notification::Icon>(); /// icon.show(); /// icon.show_message("Hello"); /// ``` pub struct Icon { // ... } #}
doc_keyword
The tracking issue for this feature is: #51315
doc_masked
The tracking issue for this feature is: #44027
The doc_masked feature allows a crate to exclude types from a given crate from appearing in lists
of trait implementations. The specifics of the feature are as follows:
-
When rustdoc encounters an
extern cratestatement annotated with a#[doc(masked)]attribute, it marks the crate as being masked. -
When listing traits a given type implements, rustdoc ensures that traits from masked crates are not emitted into the documentation.
-
When listing types that implement a given trait, rustdoc ensures that types from masked crates are not emitted into the documentation.
This feature was introduced in PR #44026 to ensure that compiler-internal and implementation-specific types and traits were not included in the standard library's documentation. Such types would introduce broken links into the documentation.
doc_spotlight
The tracking issue for this feature is: #45040
The doc_spotlight feature allows the use of the spotlight parameter to the #[doc] attribute,
to "spotlight" a specific trait on the return values of functions. Adding a #[doc(spotlight)]
attribute to a trait definition will make rustdoc print extra information for functions which return
a type that implements that trait. This attribute is applied to the Iterator, io::Read, and
io::Write traits in the standard library.
You can do this on your own traits, like this:
#![feature(doc_spotlight)]
#[doc(spotlight)]
pub trait MyTrait {}
pub struct MyStruct;
impl MyTrait for MyStruct {}
/// The docs for this function will have an extra line about `MyStruct` implementing `MyTrait`,
/// without having to write that yourself!
pub fn my_fn() -> MyStruct { MyStruct }
This feature was originally implemented in PR #45039.
dropck_eyepatch
The tracking issue for this feature is: #34761
exclusive_range_pattern
The tracking issue for this feature is: #37854
exhaustive_patterns
The tracking issue for this feature is: #51085
extern_types
The tracking issue for this feature is: #43467
external_doc
The tracking issue for this feature is: #44732
The external_doc feature allows the use of the include parameter to the #[doc] attribute, to
include external files in documentation. Use the attribute in place of, or in addition to, regular
doc comments and #[doc] attributes, and rustdoc will load the given file when it renders
documentation for your crate.
With the following files in the same directory:
external-doc.md:
# My Awesome Type
This is the documentation for this spectacular type.
lib.rs:
#![feature(external_doc)]
#[doc(include = "external-doc.md")]
pub struct MyAwesomeType;
rustdoc will load the file external-doc.md and use it as the documentation for the MyAwesomeType
struct.
When locating files, rustdoc will base paths in the src/ directory, as if they were alongside the
lib.rs for your crate. So if you want a docs/ folder to live alongside the src/ directory,
start your paths with ../docs/ for rustdoc to properly find the file.
This feature was proposed in RFC #1990 and initially implemented in PR #44781.
f16c_target_feature
The tracking issue for this feature is: #44839
ffi_returns_twice
The tracking issue for this feature is: #58314
fundamental
The tracking issue for this feature is: #29635
generators
The tracking issue for this feature is: #43122
The generators feature gate in Rust allows you to define generator or
coroutine literals. A generator is a "resumable function" that syntactically
resembles a closure but compiles to much different semantics in the compiler
itself. The primary feature of a generator is that it can be suspended during
execution to be resumed at a later date. Generators use the yield keyword to
"return", and then the caller can resume a generator to resume execution just
after the yield keyword.
Generators are an extra-unstable feature in the compiler right now. Added in RFC 2033 they're mostly intended right now as a information/constraint gathering phase. The intent is that experimentation can happen on the nightly compiler before actual stabilization. A further RFC will be required to stabilize generators/coroutines and will likely contain at least a few small tweaks to the overall design.
A syntactical example of a generator is:
#![feature(generators, generator_trait)] use std::ops::{Generator, GeneratorState}; use std::pin::Pin; fn main() { let mut generator = || { yield 1; return "foo" }; match Pin::new(&mut generator).resume() { GeneratorState::Yielded(1) => {} _ => panic!("unexpected value from resume"), } match Pin::new(&mut generator).resume() { GeneratorState::Complete("foo") => {} _ => panic!("unexpected value from resume"), } }
Generators are closure-like literals which can contain a yield statement. The
yield statement takes an optional expression of a value to yield out of the
generator. All generator literals implement the Generator trait in the
std::ops module. The Generator trait has one main method, resume, which
resumes execution of the generator at the previous suspension point.
An example of the control flow of generators is that the following example prints all numbers in order:
#![feature(generators, generator_trait)] use std::ops::Generator; use std::pin::Pin; fn main() { let mut generator = || { println!("2"); yield; println!("4"); }; println!("1"); Pin::new(&mut generator).resume(); println!("3"); Pin::new(&mut generator).resume(); println!("5"); }
At this time the main intended use case of generators is an implementation primitive for async/await syntax, but generators will likely be extended to ergonomic implementations of iterators and other primitives in the future. Feedback on the design and usage is always appreciated!
The Generator trait
The Generator trait in std::ops currently looks like:
# #![feature(arbitrary_self_types, generator_trait)]
# use std::ops::GeneratorState;
# use std::pin::Pin;
pub trait Generator {
type Yield;
type Return;
fn resume(self: Pin<&mut Self>) -> GeneratorState<Self::Yield, Self::Return>;
}
The Generator::Yield type is the type of values that can be yielded with the
yield statement. The Generator::Return type is the returned type of the
generator. This is typically the last expression in a generator's definition or
any value passed to return in a generator. The resume function is the entry
point for executing the Generator itself.
The return value of resume, GeneratorState, looks like:
pub enum GeneratorState<Y, R> {
Yielded(Y),
Complete(R),
}
The Yielded variant indicates that the generator can later be resumed. This
corresponds to a yield point in a generator. The Complete variant indicates
that the generator is complete and cannot be resumed again. Calling resume
after a generator has returned Complete will likely result in a panic of the
program.
Closure-like semantics
The closure-like syntax for generators alludes to the fact that they also have closure-like semantics. Namely:
-
When created, a generator executes no code. A closure literal does not actually execute any of the closure's code on construction, and similarly a generator literal does not execute any code inside the generator when constructed.
-
Generators can capture outer variables by reference or by move, and this can be tweaked with the
movekeyword at the beginning of the closure. Like closures all generators will have an implicit environment which is inferred by the compiler. Outer variables can be moved into a generator for use as the generator progresses. -
Generator literals produce a value with a unique type which implements the
std::ops::Generatortrait. This allows actual execution of the generator through theGenerator::resumemethod as well as also naming it in return types and such. -
Traits like
SendandSyncare automatically implemented for aGeneratordepending on the captured variables of the environment. Unlike closures, generators also depend on variables live across suspension points. This means that although the ambient environment may beSendorSync, the generator itself may not be due to internal variables live acrossyieldpoints being not-Sendor not-Sync. Note that generators do not implement traits likeCopyorCloneautomatically. -
Whenever a generator is dropped it will drop all captured environment variables.
Note that unlike closures, generators at this time cannot take any arguments.
That is, generators must always look like || { ... }. This restriction may be
lifted at a future date, the design is ongoing!
Generators as state machines
In the compiler, generators are currently compiled as state machines. Each
yield expression will correspond to a different state that stores all live
variables over that suspension point. Resumption of a generator will dispatch on
the current state and then execute internally until a yield is reached, at
which point all state is saved off in the generator and a value is returned.
Let's take a look at an example to see what's going on here:
#![feature(generators, generator_trait)] use std::ops::Generator; use std::pin::Pin; fn main() { let ret = "foo"; let mut generator = move || { yield 1; return ret }; Pin::new(&mut generator).resume(); Pin::new(&mut generator).resume(); }
This generator literal will compile down to something similar to:
#![feature(arbitrary_self_types, generators, generator_trait)] use std::ops::{Generator, GeneratorState}; use std::pin::Pin; fn main() { let ret = "foo"; let mut generator = { enum __Generator { Start(&'static str), Yield1(&'static str), Done, } impl Generator for __Generator { type Yield = i32; type Return = &'static str; fn resume(mut self: Pin<&mut Self>) -> GeneratorState<i32, &'static str> { use std::mem; match mem::replace(&mut *self, __Generator::Done) { __Generator::Start(s) => { *self = __Generator::Yield1(s); GeneratorState::Yielded(1) } __Generator::Yield1(s) => { *self = __Generator::Done; GeneratorState::Complete(s) } __Generator::Done => { panic!("generator resumed after completion") } } } } __Generator::Start(ret) }; Pin::new(&mut generator).resume(); Pin::new(&mut generator).resume(); }
Notably here we can see that the compiler is generating a fresh type,
__Generator in this case. This type has a number of states (represented here
as an enum) corresponding to each of the conceptual states of the generator.
At the beginning we're closing over our outer variable foo and then that
variable is also live over the yield point, so it's stored in both states.
When the generator starts it'll immediately yield 1, but it saves off its state
just before it does so indicating that it has reached the yield point. Upon
resuming again we'll execute the return ret which returns the Complete
state.
Here we can also note that the Done state, if resumed, panics immediately as
it's invalid to resume a completed generator. It's also worth noting that this
is just a rough desugaring, not a normative specification for what the compiler
does.
generic_associated_types
The tracking issue for this feature is: #44265
hexagon_target_feature
The tracking issue for this feature is: #44839
impl_trait_in_bindings
The tracking issue for this feature is: #34511
The impl_trait_in_bindings feature gate lets you use impl Trait syntax in
let, static, and const bindings.
A simple example is:
#![feature(impl_trait_in_bindings)] use std::fmt::Debug; fn main() { let a: impl Debug + Clone = 42; let b = a.clone(); println!("{:?}", b); // prints `42` }
Note however that because the types of a and b are opaque in the above
example, calling inherent methods or methods outside of the specified traits
(e.g., a.abs() or b.abs()) is not allowed, and yields an error.
in_band_lifetimes
The tracking issue for this feature is: #44524
infer_static_outlives_requirements
The tracking issue for this feature is: #44493
The infer_static_outlives_requirements feature indicates that certain
'static outlives requirements can be inferred by the compiler rather than
stating them explicitly.
Note: It is an accompanying feature to infer_outlives_requirements,
which must be enabled to infer outlives requirements.
For example, currently generic struct definitions that contain references, require where-clauses of the form T: 'static. By using this feature the outlives predicates will be inferred, although they may still be written explicitly.
struct Foo<U> where U: 'static { // <-- currently required
bar: Bar<U>
}
struct Bar<T: 'static> {
x: T,
}
Examples:
#![feature(infer_outlives_requirements)]
#![feature(infer_static_outlives_requirements)]
#[rustc_outlives]
// Implicitly infer U: 'static
struct Foo<U> {
bar: Bar<U>
}
struct Bar<T: 'static> {
x: T,
}
intrinsics
The tracking issue for this feature is: None.
Intrinsics are never intended to be stable directly, but intrinsics are often exported in some sort of stable manner. Prefer using the stable interfaces to the intrinsic directly when you can.
These are imported as if they were FFI functions, with the special
rust-intrinsic ABI. For example, if one was in a freestanding
context, but wished to be able to transmute between types, and
perform efficient pointer arithmetic, one would import those functions
via a declaration like
#![feature(intrinsics)] # fn main() {} extern "rust-intrinsic" { fn transmute<T, U>(x: T) -> U; fn offset<T>(dst: *const T, offset: isize) -> *const T; }
As with any other FFI functions, these are always unsafe to call.
label_break_value
The tracking issue for this feature is: #48594
lang_items
The tracking issue for this feature is: None.
The rustc compiler has certain pluggable operations, that is,
functionality that isn't hard-coded into the language, but is
implemented in libraries, with a special marker to tell the compiler
it exists. The marker is the attribute #[lang = "..."] and there are
various different values of ..., i.e. various different 'lang
items'.
For example, Box pointers require two lang items, one for allocation
and one for deallocation. A freestanding program that uses the Box
sugar for dynamic allocations via malloc and free:
#![feature(lang_items, box_syntax, start, libc, core_intrinsics)]
#![no_std]
use core::intrinsics;
use core::panic::PanicInfo;
extern crate libc;
#[lang = "owned_box"]
pub struct Box<T>(*mut T);
#[lang = "exchange_malloc"]
unsafe fn allocate(size: usize, _align: usize) -> *mut u8 {
let p = libc::malloc(size as libc::size_t) as *mut u8;
// Check if `malloc` failed:
if p as usize == 0 {
intrinsics::abort();
}
p
}
#[lang = "box_free"]
unsafe fn box_free<T: ?Sized>(ptr: *mut T) {
libc::free(ptr as *mut libc::c_void)
}
#[start]
fn main(_argc: isize, _argv: *const *const u8) -> isize {
let _x = box 1;
0
}
#[lang = "eh_personality"] extern fn rust_eh_personality() {}
#[lang = "panic_impl"] extern fn rust_begin_panic(info: &PanicInfo) -> ! { unsafe { intrinsics::abort() } }
#[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {}
#[no_mangle] pub extern fn rust_eh_register_frames () {}
#[no_mangle] pub extern fn rust_eh_unregister_frames () {}
Note the use of abort: the exchange_malloc lang item is assumed to
return a valid pointer, and so needs to do the check internally.
Other features provided by lang items include:
- overloadable operators via traits: the traits corresponding to the
==,<, dereferencing (*) and+(etc.) operators are all marked with lang items; those specific four areeq,ord,deref, andaddrespectively. - stack unwinding and general failure; the
eh_personality,eh_unwind_resume,failandfail_bounds_checkslang items. - the traits in
std::markerused to indicate types of various kinds; lang itemssend,syncandcopy. - the marker types and variance indicators found in
std::marker; lang itemscovariant_type,contravariant_lifetime, etc.
Lang items are loaded lazily by the compiler; e.g. if one never uses
Box then there is no need to define functions for exchange_malloc
and box_free. rustc will emit an error when an item is needed
but not found in the current crate or any that it depends on.
Most lang items are defined by libcore, but if you're trying to build
an executable without the standard library, you'll run into the need
for lang items. The rest of this page focuses on this use-case, even though
lang items are a bit broader than that.
Using libc
In order to build a #[no_std] executable we will need libc as a dependency.
We can specify this using our Cargo.toml file:
[dependencies]
libc = { version = "0.2.14", default-features = false }
Note that the default features have been disabled. This is a critical step - the default features of libc include the standard library and so must be disabled.
Writing an executable without stdlib
Controlling the entry point is possible in two ways: the #[start] attribute,
or overriding the default shim for the C main function with your own.
The function marked #[start] is passed the command line parameters
in the same format as C:
#![feature(lang_items, core_intrinsics)]
#![feature(start)]
#![no_std]
use core::intrinsics;
use core::panic::PanicInfo;
// Pull in the system libc library for what crt0.o likely requires.
extern crate libc;
// Entry point for this program.
#[start]
fn start(_argc: isize, _argv: *const *const u8) -> isize {
0
}
// These functions are used by the compiler, but not
// for a bare-bones hello world. These are normally
// provided by libstd.
#[lang = "eh_personality"]
#[no_mangle]
pub extern fn rust_eh_personality() {
}
// This function may be needed based on the compilation target.
#[lang = "eh_unwind_resume"]
#[no_mangle]
pub extern fn rust_eh_unwind_resume() {
}
#[lang = "panic_impl"]
#[no_mangle]
pub extern fn rust_begin_panic(info: &PanicInfo) -> ! {
unsafe { intrinsics::abort() }
}
To override the compiler-inserted main shim, one has to disable it
with #![no_main] and then create the appropriate symbol with the
correct ABI and the correct name, which requires overriding the
compiler's name mangling too:
#![feature(lang_items, core_intrinsics)]
#![feature(start)]
#![no_std]
#![no_main]
use core::intrinsics;
use core::panic::PanicInfo;
// Pull in the system libc library for what crt0.o likely requires.
extern crate libc;
// Entry point for this program.
#[no_mangle] // ensure that this symbol is called `main` in the output
pub extern fn main(_argc: i32, _argv: *const *const u8) -> i32 {
0
}
// These functions are used by the compiler, but not
// for a bare-bones hello world. These are normally
// provided by libstd.
#[lang = "eh_personality"]
#[no_mangle]
pub extern fn rust_eh_personality() {
}
// This function may be needed based on the compilation target.
#[lang = "eh_unwind_resume"]
#[no_mangle]
pub extern fn rust_eh_unwind_resume() {
}
#[lang = "panic_impl"]
#[no_mangle]
pub extern fn rust_begin_panic(info: &PanicInfo) -> ! {
unsafe { intrinsics::abort() }
}
In many cases, you may need to manually link to the compiler_builtins crate
when building a no_std binary. You may observe this via linker error messages
such as "undefined reference to `__rust_probestack'". Using this crate
also requires enabling the library feature compiler_builtins_lib. You can read
more about this here.
More about the language items
The compiler currently makes a few assumptions about symbols which are available in the executable to call. Normally these functions are provided by the standard library, but without it you must define your own. These symbols are called "language items", and they each have an internal name, and then a signature that an implementation must conform to.
The first of these functions, rust_eh_personality, is used by the failure
mechanisms of the compiler. This is often mapped to GCC's personality function
(see the libstd implementation for more information), but crates
which do not trigger a panic can be assured that this function is never
called. The language item's name is eh_personality.
The second function, rust_begin_panic, is also used by the failure mechanisms of the
compiler. When a panic happens, this controls the message that's displayed on
the screen. While the language item's name is panic_impl, the symbol name is
rust_begin_panic.
A third function, rust_eh_unwind_resume, is also needed if the custom_unwind_resume
flag is set in the options of the compilation target. It allows customizing the
process of resuming unwind at the end of the landing pads. The language item's name
is eh_unwind_resume.
List of all language items
This is a list of all language items in Rust along with where they are located in the source code.
- Primitives
i8:libcore/num/mod.rsi16:libcore/num/mod.rsi32:libcore/num/mod.rsi64:libcore/num/mod.rsi128:libcore/num/mod.rsisize:libcore/num/mod.rsu8:libcore/num/mod.rsu16:libcore/num/mod.rsu32:libcore/num/mod.rsu64:libcore/num/mod.rsu128:libcore/num/mod.rsusize:libcore/num/mod.rsf32:libstd/f32.rsf64:libstd/f64.rschar:libcore/char.rsslice:liballoc/slice.rsstr:liballoc/str.rsconst_ptr:libcore/ptr.rsmut_ptr:libcore/ptr.rsunsafe_cell:libcore/cell.rs
- Runtime
start:libstd/rt.rseh_personality:libpanic_unwind/emcc.rs(EMCC)eh_personality:libpanic_unwind/seh64_gnu.rs(SEH64 GNU)eh_personality:libpanic_unwind/seh.rs(SEH)eh_unwind_resume:libpanic_unwind/seh64_gnu.rs(SEH64 GNU)eh_unwind_resume:libpanic_unwind/gcc.rs(GCC)msvc_try_filter:libpanic_unwind/seh.rs(SEH)panic:libcore/panicking.rspanic_bounds_check:libcore/panicking.rspanic_impl:libcore/panicking.rspanic_impl:libstd/panicking.rs
- Allocations
owned_box:liballoc/boxed.rsexchange_malloc:liballoc/heap.rsbox_free:liballoc/heap.rs
- Operands
not:libcore/ops/bit.rsbitand:libcore/ops/bit.rsbitor:libcore/ops/bit.rsbitxor:libcore/ops/bit.rsshl:libcore/ops/bit.rsshr:libcore/ops/bit.rsbitand_assign:libcore/ops/bit.rsbitor_assign:libcore/ops/bit.rsbitxor_assign:libcore/ops/bit.rsshl_assign:libcore/ops/bit.rsshr_assign:libcore/ops/bit.rsderef:libcore/ops/deref.rsderef_mut:libcore/ops/deref.rsindex:libcore/ops/index.rsindex_mut:libcore/ops/index.rsadd:libcore/ops/arith.rssub:libcore/ops/arith.rsmul:libcore/ops/arith.rsdiv:libcore/ops/arith.rsrem:libcore/ops/arith.rsneg:libcore/ops/arith.rsadd_assign:libcore/ops/arith.rssub_assign:libcore/ops/arith.rsmul_assign:libcore/ops/arith.rsdiv_assign:libcore/ops/arith.rsrem_assign:libcore/ops/arith.rseq:libcore/cmp.rsord:libcore/cmp.rs
- Functions
fn:libcore/ops/function.rsfn_mut:libcore/ops/function.rsfn_once:libcore/ops/function.rsgenerator_state:libcore/ops/generator.rsgenerator:libcore/ops/generator.rs
- Other
coerce_unsized:libcore/ops/unsize.rsdrop:libcore/ops/drop.rsdrop_in_place:libcore/ptr.rsclone:libcore/clone.rscopy:libcore/marker.rssend:libcore/marker.rssized:libcore/marker.rsunsize:libcore/marker.rssync:libcore/marker.rsphantom_data:libcore/marker.rsfreeze:libcore/marker.rsdebug_trait:libcore/fmt/mod.rsnon_zero:libcore/nonzero.rsarc:liballoc/sync.rsrc:liballoc/rc.rs
let_chains
The tracking issue for this feature is: #53667
link_args
The tracking issue for this feature is: #29596
You can tell rustc how to customize linking, and that is via the link_args
attribute. This attribute is applied to extern blocks and specifies raw flags
which need to get passed to the linker when producing an artifact. An example
usage would be:
#![feature(link_args)] #[link_args = "-foo -bar -baz"] extern {} # fn main() {}
Note that this feature is currently hidden behind the feature(link_args) gate
because this is not a sanctioned way of performing linking. Right now rustc
shells out to the system linker (gcc on most systems, link.exe on MSVC), so
it makes sense to provide extra command line arguments, but this will not
always be the case. In the future rustc may use LLVM directly to link native
libraries, in which case link_args will have no meaning. You can achieve the
same effect as the link_args attribute with the -C link-args argument to
rustc.
It is highly recommended to not use this attribute, and rather use the more
formal #[link(...)] attribute on extern blocks instead.
link_cfg
The tracking issue for this feature is: #37406
link_llvm_intrinsics
The tracking issue for this feature is: #29602
linkage
The tracking issue for this feature is: #29603
lint_reasons
The tracking issue for this feature is: #54503
macros_in_extern
The tracking issue for this feature is: #49476
main
The tracking issue for this feature is: #29634
marker_trait_attr
The tracking issue for this feature is: #29864
Normally, Rust keeps you from adding trait implementations that could overlap with each other, as it would be ambiguous which to use. This feature, however, carves out an exception to that rule: a trait can opt-in to having overlapping implementations, at the cost that those implementations are not allowed to override anything (and thus the trait itself cannot have any associated items, as they're pointless when they'd need to do the same thing for every type anyway).
# #![allow(unused_variables)] #![feature(marker_trait_attr)] #fn main() { #[marker] trait CheapToClone: Clone {} impl<T: Copy> CheapToClone for T {} // These could potentally overlap with the blanket implementation above, // so are only allowed because CheapToClone is a marker trait. impl<T: CheapToClone, U: CheapToClone> CheapToClone for (T, U) {} impl<T: CheapToClone> CheapToClone for std::ops::Range<T> {} fn cheap_clone<T: CheapToClone>(t: T) -> T { t.clone() } #}
This is expected to replace the unstable overlapping_marker_traits
feature, which applied to all empty traits (without needing an opt-in).
member_constraints
The tracking issue for this feature is: #61977
The member_constraints feature gate lets you use impl Trait syntax with
multiple unrelated lifetime parameters.
A simple example is:
#![feature(member_constraints)] trait Trait<'a, 'b> { } impl<T> Trait<'_, '_> for T {} fn foo<'a, 'b>(x: &'a u32, y: &'b u32) -> impl Trait<'a, 'b> { (x, y) } fn main() { }
Without the member_constraints feature gate, the above example is an
error because both 'a and 'b appear in the impl Trait bounds, but
neither outlives the other.
mips_target_feature
The tracking issue for this feature is: #44839
mmx_target_feature
The tracking issue for this feature is: #44839
movbe_target_feature
The tracking issue for this feature is: #44839
naked_functions
The tracking issue for this feature is: #32408
needs_panic_runtime
The tracking issue for this feature is: #32837
never_type
The tracking issue for this feature is: #35121
nll
The tracking issue for this feature is: #43234
no_core
The tracking issue for this feature is: #29639
no_debug
The tracking issue for this feature is: #29721
non_ascii_idents
The tracking issue for this feature is: #55467
The non_ascii_idents feature adds support for non-ASCII identifiers.
Examples
# #![allow(unused_variables)] #![feature(non_ascii_idents)] #fn main() { const ε: f64 = 0.00001f64; const Π: f64 = 3.14f64; #}
Changes to the language reference
Lexer:
IDENTIFIER :
    XID_start XID_continue\*
  |_XID_continue+
An identifier is any nonempty Unicode string of the following form:
Either
- The first character has property
XID_start - The remaining characters have property
XID_continue
Or
- The first character is
_ - The identifier is more than one character,
_alone is not an identifier - The remaining characters have property
XID_continue
that does not occur in the set of strict keywords.
Note:
XID_startandXID_continueas character properties cover the character ranges used to form the more familiar C and Java language-family identifiers.
non_exhaustive
The tracking issue for this feature is: #44109
The non_exhaustive gate allows you to use the #[non_exhaustive] attribute
on structs, enums and enum variants. When applied within a crate, users of the
crate will need to use the _ pattern when matching enums and use the ..
pattern when matching structs. Enum variants cannot be matched against.
Structs and enum variants marked as non_exhaustive will not be able to
be created normally outside of the defining crate. This is demonstrated
below:
use std::error::Error as StdError;
#[non_exhaustive]
pub enum Error {
Message(String),
Other,
}
impl StdError for Error {
fn description(&self) -> &str {
// This will not error, despite being marked as non_exhaustive, as this
// enum is defined within the current crate, it can be matched
// exhaustively.
match *self {
Message(ref s) => s,
Other => "other or unknown error",
}
}
}
use mycrate::Error;
// This will not error as the non_exhaustive Error enum has been matched with
// a wildcard.
match error {
Message(ref s) => ...,
Other => ...,
_ => ...,
}
#[non_exhaustive]
pub struct Config {
pub window_width: u16,
pub window_height: u16,
}
// We can create structs as normal within the defining crate when marked as
// non_exhaustive.
let config = Config { window_width: 640, window_height: 480 };
// We can match structs exhaustively when within the defining crate.
if let Ok(Config { window_width, window_height }) = load_config() {
// ...
}
use mycrate::Config;
// We cannot create a struct like normal if it has been marked as
// non_exhaustive.
let config = Config { window_width: 640, window_height: 480 };
// By adding the `..` we can match the config as below outside of the crate
// when marked non_exhaustive.
let &Config { window_width, window_height, .. } = config;
omit_gdb_pretty_printer_section
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
on_unimplemented
The tracking issue for this feature is: #29628
The on_unimplemented feature provides the #[rustc_on_unimplemented]
attribute, which allows trait definitions to add specialized notes to error
messages when an implementation was expected but not found. You can refer
to the trait's generic arguments by name and to the resolved type using
Self.
For example:
#![feature(on_unimplemented)] #[rustc_on_unimplemented="an iterator over elements of type `{A}` \ cannot be built from a collection of type `{Self}`"] trait MyIterator<A> { fn next(&mut self) -> A; } fn iterate_chars<I: MyIterator<char>>(i: I) { // ... } fn main() { iterate_chars(&[1, 2, 3][..]); }
When the user compiles this, they will see the following;
error[E0277]: the trait bound `&[{integer}]: MyIterator<char>` is not satisfied
--> <anon>:14:5
|
14 | iterate_chars(&[1, 2, 3][..]);
| ^^^^^^^^^^^^^ an iterator over elements of type `char` cannot be built from a collection of type `&[{integer}]`
|
= help: the trait `MyIterator<char>` is not implemented for `&[{integer}]`
= note: required by `iterate_chars`
on_unimplemented also supports advanced filtering for better targeting
of messages, as well as modifying specific parts of the error message. You
target the text of:
- the main error message (
message) - the label (
label) - an extra note (
note)
For example, the following attribute
# #![allow(unused_variables)] #fn main() { #[rustc_on_unimplemented( message="message", label="label", note="note" )] trait MyIterator<A> { fn next(&mut self) -> A; } #}
Would generate the following output:
error[E0277]: message
--> <anon>:14:5
|
14 | iterate_chars(&[1, 2, 3][..]);
| ^^^^^^^^^^^^^ label
|
= note: note
= help: the trait `MyIterator<char>` is not implemented for `&[{integer}]`
= note: required by `iterate_chars`
To allow more targeted error messages, it is possible to filter the
application of these fields based on a variety of attributes when using
on:
crate_local: whether the code causing the trait bound to not be fulfilled is part of the user's crate. This is used to avoid suggesting code changes that would require modifying a dependency.- Any of the generic arguments that can be substituted in the text can be
referred by name as well for filtering, like
Rhs="i32", except forSelf. _Self: to filter only on a particular calculated trait resolution, likeSelf="std::iter::Iterator<char>". This is needed becauseSelfis a keyword which cannot appear in attributes.direct: user-specified rather than derived obligation.from_method: usable both as boolean (whether the flag is present, likecrate_local) or matching against a particular method. Currently used fortry.from_desugaring: usable both as boolean (whether the flag is present) or matching against a particular desugaring. The desugaring is identified with its variant name in theDesugaringKindenum.
For example, the Iterator trait can be annotated in the following way:
# #![allow(unused_variables)] #fn main() { #[rustc_on_unimplemented( on( _Self="&str", note="call `.chars()` or `.as_bytes()` on `{Self}" ), message="`{Self}` is not an iterator", label="`{Self}` is not an iterator", note="maybe try calling `.iter()` or a similar method" )] pub trait Iterator {} #}
Which would produce the following outputs:
error[E0277]: `Foo` is not an iterator
--> src/main.rs:4:16
|
4 | for foo in Foo {}
| ^^^ `Foo` is not an iterator
|
= note: maybe try calling `.iter()` or a similar method
= help: the trait `std::iter::Iterator` is not implemented for `Foo`
= note: required by `std::iter::IntoIterator::into_iter`
error[E0277]: `&str` is not an iterator
--> src/main.rs:5:16
|
5 | for foo in "" {}
| ^^ `&str` is not an iterator
|
= note: call `.chars()` or `.bytes() on `&str`
= help: the trait `std::iter::Iterator` is not implemented for `&str`
= note: required by `std::iter::IntoIterator::into_iter`
If you need to filter on multiple attributes, you can use all, any or
not in the following way:
# #![allow(unused_variables)] #fn main() { #[rustc_on_unimplemented( on( all(_Self="&str", T="std::string::String"), note="you can coerce a `{T}` into a `{Self}` by writing `&*variable`" ) )] pub trait From<T>: Sized { /* ... */ } #}
optimize_attribute
The tracking issue for this feature is: #54882
optin_builtin_traits
The tracking issue for this feature is #13231
The optin_builtin_traits feature gate allows you to define auto traits.
Auto traits, like Send or Sync in the standard library, are marker traits
that are automatically implemented for every type, unless the type, or a type it contains,
has explicitly opted out via a negative impl.
impl !Type for Trait
Example:
#![feature(optin_builtin_traits)] auto trait Valid {} struct True; struct False; impl !Valid for False {} struct MaybeValid<T>(T); fn must_be_valid<T: Valid>(_t: T) { } fn main() { // works must_be_valid( MaybeValid(True) ); // compiler error - trait bound not satisfied // must_be_valid( MaybeValid(False) ); }
or_patterns
The tracking issue for this feature is: #54883
The or_pattern language feature allows | to be arbitrarily nested within
a pattern, for example, Some(A(0) | B(1 | 2)) becomes a valid pattern.
Examples
#![feature(or_patterns)]
pub enum Foo {
Bar,
Baz,
Quux,
}
pub fn example(maybe_foo: Option<Foo>) {
match maybe_foo {
Some(Foo::Bar | Foo::Baz) => {
println!("The value contained `Bar` or `Baz`");
}
Some(_) => {
println!("The value did not contain `Bar` or `Baz`");
}
None => {
println!("The value was `None`");
}
}
}
overlapping_marker_traits
The tracking issue for this feature is: #29864
panic_runtime
The tracking issue for this feature is: #32837
platform_intrinsics
The tracking issue for this feature is: #27731
plugin
The tracking issue for this feature is: #29597
This feature is part of "compiler plugins." It will often be used with the
plugin_registrar and rustc_private features.
rustc can load compiler plugins, which are user-provided libraries that
extend the compiler's behavior with new syntax extensions, lint checks, etc.
A plugin is a dynamic library crate with a designated registrar function that
registers extensions with rustc. Other crates can load these extensions using
the crate attribute #![plugin(...)]. See the
rustc_driver::plugin documentation for more about the
mechanics of defining and loading a plugin.
If present, arguments passed as #![plugin(foo(... args ...))] are not
interpreted by rustc itself. They are provided to the plugin through the
Registry's args method.
In the vast majority of cases, a plugin should only be used through
#![plugin] and not through an extern crate item. Linking a plugin would
pull in all of libsyntax and librustc as dependencies of your crate. This is
generally unwanted unless you are building another plugin. The
plugin_as_library lint checks these guidelines.
The usual practice is to put compiler plugins in their own crate, separate from
any macro_rules! macros or ordinary Rust code meant to be used by consumers
of a library.
Syntax extensions
Plugins can extend Rust's syntax in various ways. One kind of syntax extension is the procedural macro. These are invoked the same way as ordinary macros, but the expansion is performed by arbitrary Rust code that manipulates syntax trees at compile time.
Let's write a plugin
roman_numerals.rs
that implements Roman numeral integer literals.
#![crate_type="dylib"]
#![feature(plugin_registrar, rustc_private)]
extern crate syntax;
extern crate syntax_pos;
extern crate rustc;
extern crate rustc_driver;
use syntax::parse::token::{self, Token};
use syntax::tokenstream::{TokenTree, TokenStream};
use syntax::ext::base::{ExtCtxt, MacResult, DummyResult, MacEager};
use syntax_pos::Span;
use rustc_driver::plugin::Registry;
fn expand_rn(cx: &mut ExtCtxt, sp: Span, args: TokenStream)
-> Box<dyn MacResult + 'static> {
static NUMERALS: &'static [(&'static str, usize)] = &[
("M", 1000), ("CM", 900), ("D", 500), ("CD", 400),
("C", 100), ("XC", 90), ("L", 50), ("XL", 40),
("X", 10), ("IX", 9), ("V", 5), ("IV", 4),
("I", 1)];
if args.len() != 1 {
cx.span_err(
sp,
&format!("argument should be a single identifier, but got {} arguments", args.len()));
return DummyResult::any(sp);
}
let text = match args.into_trees().next().unwrap() {
TokenTree::Token(Token { kind: token::Ident(s, _), .. }) => s.to_string(),
_ => {
cx.span_err(sp, "argument should be a single identifier");
return DummyResult::any(sp);
}
};
let mut text = &*text;
let mut total = 0;
while !text.is_empty() {
match NUMERALS.iter().find(|&&(rn, _)| text.starts_with(rn)) {
Some(&(rn, val)) => {
total += val;
text = &text[rn.len()..];
}
None => {
cx.span_err(sp, "invalid Roman numeral");
return DummyResult::any(sp);
}
}
}
MacEager::expr(cx.expr_usize(sp, total))
}
#[plugin_registrar]
pub fn plugin_registrar(reg: &mut Registry) {
reg.register_macro("rn", expand_rn);
}
Then we can use rn!() like any other macro:
#![feature(plugin)]
#![plugin(roman_numerals)]
fn main() {
assert_eq!(rn!(MMXV), 2015);
}
The advantages over a simple fn(&str) -> u32 are:
- The (arbitrarily complex) conversion is done at compile time.
- Input validation is also performed at compile time.
- It can be extended to allow use in patterns, which effectively gives a way to define new literal syntax for any data type.
In addition to procedural macros, you can define new
derive-like attributes and other kinds
of extensions. See Registry::register_syntax_extension and the
SyntaxExtension struct. For a more involved macro example, see
regex_macros.
Tips and tricks
You can use syntax::parse to turn token trees into
higher-level syntax elements like expressions:
fn expand_foo(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
-> Box<MacResult+'static> {
let mut parser = cx.new_parser_from_tts(args);
let expr: P<Expr> = parser.parse_expr();
Looking through libsyntax parser
code
will give you a feel for how the parsing infrastructure works.
Keep the Spans of everything you parse, for better error reporting. You can
wrap Spanned around your custom data structures.
Calling ExtCtxt::span_fatal will immediately abort compilation. It's better to
instead call ExtCtxt::span_err and return DummyResult so that the compiler
can continue and find further errors.
To print syntax fragments for debugging, you can use span_note together with
syntax::print::pprust::*_to_string.
Lint plugins
Plugins can extend Rust's lint
infrastructure with
additional checks for code style, safety, etc. Now let's write a plugin
lint_plugin_test.rs
that warns about any item named lintme.
#![feature(plugin_registrar)]
#![feature(box_syntax, rustc_private)]
extern crate syntax;
// Load rustc as a plugin to get macros
#[macro_use]
extern crate rustc;
extern crate rustc_driver;
use rustc::lint::{EarlyContext, LintContext, LintPass, EarlyLintPass,
EarlyLintPassObject, LintArray};
use rustc_driver::plugin::Registry;
use syntax::ast;
declare_lint!(TEST_LINT, Warn, "Warn about items named 'lintme'");
struct Pass;
impl LintPass for Pass {
fn get_lints(&self) -> LintArray {
lint_array!(TEST_LINT)
}
}
impl EarlyLintPass for Pass {
fn check_item(&mut self, cx: &EarlyContext, it: &ast::Item) {
if it.ident.as_str() == "lintme" {
cx.span_lint(TEST_LINT, it.span, "item is named 'lintme'");
}
}
}
#[plugin_registrar]
pub fn plugin_registrar(reg: &mut Registry) {
reg.register_early_lint_pass(box Pass as EarlyLintPassObject);
}
Then code like
#![plugin(lint_plugin_test)]
fn lintme() { }
will produce a compiler warning:
foo.rs:4:1: 4:16 warning: item is named 'lintme', #[warn(test_lint)] on by default
foo.rs:4 fn lintme() { }
^~~~~~~~~~~~~~~
The components of a lint plugin are:
-
one or more
declare_lint!invocations, which define staticLintstructs; -
a struct holding any state needed by the lint pass (here, none);
-
a
LintPassimplementation defining how to check each syntax element. A singleLintPassmay callspan_lintfor several differentLints, but should register them all through theget_lintsmethod.
Lint passes are syntax traversals, but they run at a late stage of compilation
where type information is available. rustc's built-in
lints
mostly use the same infrastructure as lint plugins, and provide examples of how
to access type information.
Lints defined by plugins are controlled by the usual attributes and compiler
flags, e.g.
#[allow(test_lint)] or -A test-lint. These identifiers are derived from the
first argument to declare_lint!, with appropriate case and punctuation
conversion.
You can run rustc -W help foo.rs to see a list of lints known to rustc,
including those provided by plugins loaded by foo.rs.
plugin_registrar
The tracking issue for this feature is: #29597
This feature is part of "compiler plugins." It will often be used with the
plugin and rustc_private features as well. For more details, see
their docs.
powerpc_target_feature
The tracking issue for this feature is: #44839
precise_pointer_size_matching
The tracking issue for this feature is: #56354
prelude_import
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
proc_macro_hygiene
The tracking issue for this feature is: #54727
profiler_runtime
The tracking issue for this feature is: #42524.
re_rebalance_coherence
The tracking issue for this feature is: #55437
The re_rebalance_coherence feature tweaks the rules regarding which trait
impls are allowed in crates.
The following rule is used:
Given impl<P1..=Pn> Trait<T1..=Tn> for T0, an impl is valid only if at
least one of the following is true:
Traitis a local trait- All of
- At least one of the types
T0..=Tnmust be a local type. LetTibe the first such type. - No uncovered type parameters
P1..=Pnmay appear inT0..Ti(excludingTi)
- At least one of the types
See the RFC for details.
repr_simd
The tracking issue for this feature is: #27731
repr128
The tracking issue for this feature is: #35118
The repr128 feature adds support for #[repr(u128)] on enums.
# #![allow(unused_variables)] #![feature(repr128)] #fn main() { #[repr(u128)] enum Foo { Bar(u64), } #}
rtm_target_feature
The tracking issue for this feature is: #44839
rustc_attrs
The tracking issue for this feature is: #29642
rustc_const_unstable
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
rustc_private
The tracking issue for this feature is: #27812
sanitizer_runtime
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
simd_ffi
The tracking issue for this feature is: #27731
slice_patterns
The tracking issue for this feature is: #62254
The slice_patterns feature gate lets you use .. to indicate any number of
elements inside a pattern matching a slice. This wildcard can only be used once
for a given array. If there's an pattern before the .., the subslice will be
matched against that pattern. For example:
#![feature(slice_patterns)] fn is_symmetric(list: &[u32]) -> bool { match list { &[] | &[_] => true, &[x, ref inside @ .., y] if x == y => is_symmetric(inside), &[..] => false, } } fn main() { let sym = &[0, 1, 4, 2, 4, 1, 0]; assert!(is_symmetric(sym)); let not_sym = &[0, 1, 7, 2, 4, 1, 0]; assert!(!is_symmetric(not_sym)); }
specialization
The tracking issue for this feature is: #31844
sse4a_target_feature
The tracking issue for this feature is: #44839
staged_api
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
start
The tracking issue for this feature is: #29633
static_nobundle
The tracking issue for this feature is: #37403
stmt_expr_attributes
The tracking issue for this feature is: #15701
structural_match
The tracking issue for this feature is: #31434
tbm_target_feature
The tracking issue for this feature is: #44839
test_2018_feature
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
thread_local
The tracking issue for this feature is: #29594
trait_alias
The tracking issue for this feature is: [#41517]
The trait_alias feature adds support for trait aliases. These allow aliases
to be created for one or more traits (currently just a single regular trait plus
any number of auto-traits), and used wherever traits would normally be used as
either bounds or trait objects.
#![feature(trait_alias)] trait Foo = std::fmt::Debug + Send; trait Bar = Foo + Sync; // Use trait alias as bound on type parameter. fn foo<T: Foo>(v: &T) { println!("{:?}", v); } pub fn main() { foo(&1); // Use trait alias for trait objects. let a: &Bar = &123; println!("{:?}", a); let b = Box::new(456) as Box<dyn Foo>; println!("{:?}", b); }
transparent_enums
The tracking issue for this feature is [#60405]
The transparent_enums feature allows you mark enums as
#[repr(transparent)]. An enum may be #[repr(transparent)] if it has
exactly one variant, and that variant matches the same conditions which struct
requires for transparency. Some concrete illustrations follow.
# #![allow(unused_variables)] #![feature(transparent_enums)] #fn main() { // This enum has the same representation as `f32`. #[repr(transparent)] enum SingleFieldEnum { Variant(f32) } // This enum has the same representation as `usize`. #[repr(transparent)] enum MultiFieldEnum { Variant { field: usize, nothing: () }, } #}
For consistency with transparent structs, enums must have exactly one
non-zero-sized field. If all fields are zero-sized, the enum must not be
#[repr(transparent)]:
# #![allow(unused_variables)] #![feature(transparent_enums)] #fn main() { // This (non-transparent) enum is already valid in stable Rust: pub enum GoodEnum { Nothing, } // Error: transparent enum needs exactly one non-zero-sized field, but has 0 // #[repr(transparent)] // pub enum BadEnum { // Nothing(()), // } // Error: transparent enum needs exactly one non-zero-sized field, but has 0 // #[repr(transparent)] // pub enum BadEmptyEnum { // Nothing, // } #}
The one exception is if the enum is generic over T and has a field of type
T, it may be #[repr(transparent)] even if T is a zero-sized type:
# #![allow(unused_variables)] #![feature(transparent_enums)] #fn main() { // This enum has the same representation as `T`. #[repr(transparent)] pub enum GenericEnum<T> { Variant(T, ()), } // This is okay even though `()` is a zero-sized type. pub const THIS_IS_OKAY: GenericEnum<()> = GenericEnum::Variant((), ()); #}
Transparent enums require exactly one variant:
# #![allow(unused_variables)] #fn main() { // Error: transparent enum needs exactly one variant, but has 0 // #[repr(transparent)] // pub enum TooFewVariants { // } // Error: transparent enum needs exactly one variant, but has 2 // #[repr(transparent)] // pub enum TooManyVariants { // First(usize), // Second, // } #}
Like transarent structs, a transparent enum of type E has the same layout,
size, and ABI as its single non-ZST field. If it is generic over a type T, and
all its fields are ZSTs except for exactly one field of type T, then it has
the same layout and ABI as T (even if T is a ZST when monomorphized).
Like transparent structs, transparent enums are FFI-safe if and only if
their underlying representation type is also FFI-safe.
transparent_unions
The tracking issue for this feature is [#60405]
The transparent_unions feature allows you mark unions as
#[repr(transparent)]. A union may be #[repr(transparent)] in exactly the
same conditions in which a struct may be #[repr(transparent)] (generally,
this means the union must have exactly one non-zero-sized field). Some
concrete illustrations follow.
# #![allow(unused_variables)] #![feature(transparent_unions)] #fn main() { // This union has the same representation as `f32`. #[repr(transparent)] union SingleFieldUnion { field: f32, } // This union has the same representation as `usize`. #[repr(transparent)] union MultiFieldUnion { field: usize, nothing: (), } #}
For consistency with transparent structs, unions must have exactly one
non-zero-sized field. If all fields are zero-sized, the union must not be
#[repr(transparent)]:
# #![allow(unused_variables)] #![feature(transparent_unions)] #fn main() { // This (non-transparent) union is already valid in stable Rust: pub union GoodUnion { pub nothing: (), } // Error: transparent union needs exactly one non-zero-sized field, but has 0 // #[repr(transparent)] // pub union BadUnion { // pub nothing: (), // } #}
The one exception is if the union is generic over T and has a field of type
T, it may be #[repr(transparent)] even if T is a zero-sized type:
# #![allow(unused_variables)] #![feature(transparent_unions)] #fn main() { // This union has the same representation as `T`. #[repr(transparent)] pub union GenericUnion<T: Copy> { // Unions with non-`Copy` fields are unstable. pub field: T, pub nothing: (), } // This is okay even though `()` is a zero-sized type. pub const THIS_IS_OKAY: GenericUnion<()> = GenericUnion { field: () }; #}
Like transarent structs, a transparent union of type U has the same
layout, size, and ABI as its single non-ZST field. If it is generic over a type
T, and all its fields are ZSTs except for exactly one field of type T, then
it has the same layout and ABI as T (even if T is a ZST when monomorphized).
Like transparent structs, transparent unions are FFI-safe if and only if
their underlying representation type is also FFI-safe.
A union may not be eligible for the same nonnull-style optimizations that a
struct or enum (with the same fields) are eligible for. Adding
#[repr(transparent)] to union does not change this. To give a more concrete
example, it is unspecified whether size_of::<T>() is equal to
size_of::<Option<T>>(), where T is a union (regardless of whether or not
it is transparent). The Rust compiler is free to perform this optimization if
possible, but is not required to, and different compiler versions may differ in
their application of these optimizations.
trivial_bounds
The tracking issue for this feature is: #48214
try_blocks
The tracking issue for this feature is: #31436
The try_blocks feature adds support for try blocks. A try
block creates a new scope one can use the ? operator in.
# #![allow(unused_variables)] #![feature(try_blocks)] #fn main() { use std::num::ParseIntError; let result: Result<i32, ParseIntError> = try { "1".parse::<i32>()? + "2".parse::<i32>()? + "3".parse::<i32>()? }; assert_eq!(result, Ok(6)); let result: Result<i32, ParseIntError> = try { "1".parse::<i32>()? + "foo".parse::<i32>()? + "3".parse::<i32>()? }; assert!(result.is_err()); #}
type_alias_impl_trait
The tracking issue for this feature is: #63063
type_ascription
The tracking issue for this feature is: #23416
unboxed_closures
The tracking issue for this feature is #29625
See Also: fn_traits
The unboxed_closures feature allows you to write functions using the "rust-call" ABI,
required for implementing the Fn* family of traits. "rust-call" functions must have
exactly one (non self) argument, a tuple representing the argument list.
#![feature(unboxed_closures)] extern "rust-call" fn add_args(args: (u32, u32)) -> u32 { args.0 + args.1 } fn main() {}
unsized_locals
The tracking issue for this feature is: #48055
This implements RFC1909. When turned on, you can have unsized arguments and locals:
#![feature(unsized_locals)] use std::any::Any; fn main() { let x: Box<dyn Any> = Box::new(42); let x: dyn Any = *x; // ^ unsized local variable // ^^ unsized temporary foo(x); } fn foo(_: dyn Any) {} // ^^^^^^ unsized argument
The RFC still forbids the following unsized expressions:
#![feature(unsized_locals)]
use std::any::Any;
struct MyStruct<T: ?Sized> {
content: T,
}
struct MyTupleStruct<T: ?Sized>(T);
fn answer() -> Box<dyn Any> {
Box::new(42)
}
fn main() {
// You CANNOT have unsized statics.
static X: dyn Any = *answer(); // ERROR
const Y: dyn Any = *answer(); // ERROR
// You CANNOT have struct initialized unsized.
MyStruct { content: *answer() }; // ERROR
MyTupleStruct(*answer()); // ERROR
(42, *answer()); // ERROR
// You CANNOT have unsized return types.
fn my_function() -> dyn Any { *answer() } // ERROR
// You CAN have unsized local variables...
let mut x: dyn Any = *answer(); // OK
// ...but you CANNOT reassign to them.
x = *answer(); // ERROR
// You CANNOT even initialize them separately.
let y: dyn Any; // OK
y = *answer(); // ERROR
// Not mentioned in the RFC, but by-move captured variables are also Sized.
let x: dyn Any = *answer();
(move || { // ERROR
let y = x;
})();
// You CAN create a closure with unsized arguments,
// but you CANNOT call it.
// This is an implementation detail and may be changed in the future.
let f = |x: dyn Any| {};
f(*answer()); // ERROR
}
By-value trait objects
With this feature, you can have by-value self arguments without Self: Sized bounds.
#![feature(unsized_locals)] trait Foo { fn foo(self) {} } impl<T: ?Sized> Foo for T {} fn main() { let slice: Box<[i32]> = Box::new([1, 2, 3]); <[i32] as Foo>::foo(*slice); }
And Foo will also be object-safe.
#![feature(unsized_locals)] trait Foo { fn foo(self) {} } impl<T: ?Sized> Foo for T {} fn main () { let slice: Box<dyn Foo> = Box::new([1, 2, 3]); // doesn't compile yet <dyn Foo as Foo>::foo(*slice); }
One of the objectives of this feature is to allow Box<dyn FnOnce>.
Variable length arrays
The RFC also describes an extension to the array literal syntax: [e; dyn n]. In the syntax, n isn't necessarily a constant expression. The array is dynamically allocated on the stack and has the type of [T], instead of [T; n].
#![feature(unsized_locals)]
fn mergesort<T: Ord>(a: &mut [T]) {
let mut tmp = [T; dyn a.len()];
// ...
}
fn main() {
let mut a = [3, 1, 5, 6];
mergesort(&mut a);
assert_eq!(a, [1, 3, 5, 6]);
}
VLAs are not implemented yet. The syntax isn't final, either. We may need an alternative syntax for Rust 2015 because, in Rust 2015, expressions like [e; dyn(1)] would be ambiguous. One possible alternative proposed in the RFC is [e; n]: if n captures one or more local variables, then it is considered as [e; dyn n].
Advisory on stack usage
It's advised not to casually use the #![feature(unsized_locals)] feature. Typical use-cases are:
- When you need a by-value trait objects.
- When you really need a fast allocation of small temporary arrays.
Another pitfall is repetitive allocation and temporaries. Currently the compiler simply extends the stack frame every time it encounters an unsized assignment. So for example, the code
#![feature(unsized_locals)] fn main() { let x: Box<[i32]> = Box::new([1, 2, 3, 4, 5]); let _x = {{{{{{{{{{*x}}}}}}}}}}; }
and the code
#![feature(unsized_locals)] fn main() { for _ in 0..10 { let x: Box<[i32]> = Box::new([1, 2, 3, 4, 5]); let _x = *x; } }
will unnecessarily extend the stack frame.
unsized_tuple_coercion
The tracking issue for this feature is: #42877
This is a part of RFC0401. According to the RFC, there should be an implementation like this:
impl<..., T, U: ?Sized> Unsized<(..., U)> for (..., T) where T: Unsized<U> {}
This implementation is currently gated behind #[feature(unsized_tuple_coercion)] to avoid insta-stability. Therefore you can use it like this:
#![feature(unsized_tuple_coercion)] fn main() { let x : ([i32; 3], [i32; 3]) = ([1, 2, 3], [4, 5, 6]); let y : &([i32; 3], [i32]) = &x; assert_eq!(y.1[0], 4); }
untagged_unions
The tracking issue for this feature is: #32836
unwind_attributes
The tracking issue for this feature is: #58760
wasm_target_feature
The tracking issue for this feature is: #44839
Library Features
alloc_error_hook
The tracking issue for this feature is: #51245
alloc_internals
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
alloc_layout_extra
The tracking issue for this feature is: #55724
alloc_prelude
The tracking issue for this feature is: #58935
allocator_api
The tracking issue for this feature is #32838
Sometimes you want the memory for one collection to use a different
allocator than the memory for another collection. In this case,
replacing the global allocator is not a workable option. Instead,
you need to pass in an instance of an Alloc to each collection
for which you want a custom allocator.
TBD
array_error_internals
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
asm
The tracking issue for this feature is: #29722
For extremely low-level manipulations and performance reasons, one
might wish to control the CPU directly. Rust supports using inline
assembly to do this via the asm! macro.
asm!(assembly template
: output operands
: input operands
: clobbers
: options
);
Any use of asm is feature gated (requires #![feature(asm)] on the
crate to allow) and of course requires an unsafe block.
Note: the examples here are given in x86/x86-64 assembly, but all platforms are supported.
Assembly template
The assembly template is the only required parameter and must be a
literal string (i.e. "")
#![feature(asm)] #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] fn foo() { unsafe { asm!("NOP"); } } // Other platforms: #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] fn foo() { /* ... */ } fn main() { // ... foo(); // ... }
(The feature(asm) and #[cfg]s are omitted from now on.)
Output operands, input operands, clobbers and options are all optional
but you must add the right number of : if you skip them:
# #![feature(asm)] # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] # fn main() { unsafe { asm!("xor %eax, %eax" : : : "eax" ); # } } # #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] # fn main() {}
Whitespace also doesn't matter:
# #![feature(asm)] # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] # fn main() { unsafe { asm!("xor %eax, %eax" ::: "eax"); # } } # #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] # fn main() {}
Operands
Input and output operands follow the same format: : "constraints1"(expr1), "constraints2"(expr2), ...". Output operand
expressions must be mutable lvalues, or not yet assigned:
# #![feature(asm)] # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] fn add(a: i32, b: i32) -> i32 { let c: i32; unsafe { asm!("add $2, $0" : "=r"(c) : "0"(a), "r"(b) ); } c } # #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] # fn add(a: i32, b: i32) -> i32 { a + b } fn main() { assert_eq!(add(3, 14159), 14162) }
If you would like to use real operands in this position, however,
you are required to put curly braces {} around the register that
you want, and you are required to put the specific size of the
operand. This is useful for very low level programming, where
which register you use is important:
# #![allow(unused_variables)] #fn main() { # #![feature(asm)] # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] # unsafe fn read_byte_in(port: u16) -> u8 { let result: u8; asm!("in %dx, %al" : "={al}"(result) : "{dx}"(port)); result # } #}
Clobbers
Some instructions modify registers which might otherwise have held different values so we use the clobbers list to indicate to the compiler not to assume any values loaded into those registers will stay valid.
# #![feature(asm)] # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] # fn main() { unsafe { // Put the value 0x200 in eax: asm!("mov $$0x200, %eax" : /* no outputs */ : /* no inputs */ : "eax"); # } } # #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] # fn main() {}
Input and output registers need not be listed since that information is already communicated by the given constraints. Otherwise, any other registers used either implicitly or explicitly should be listed.
If the assembly changes the condition code register cc should be
specified as one of the clobbers. Similarly, if the assembly modifies
memory, memory should also be specified.
Options
The last section, options is specific to Rust. The format is comma
separated literal strings (i.e. :"foo", "bar", "baz"). It's used to
specify some extra info about the inline assembly:
Current valid options are:
- volatile - specifying this is analogous to
__asm__ __volatile__ (...)in gcc/clang. - alignstack - certain instructions expect the stack to be aligned a certain way (i.e. SSE) and specifying this indicates to the compiler to insert its usual stack alignment code
- intel - use intel syntax instead of the default AT&T.
# #![feature(asm)] # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] # fn main() { let result: i32; unsafe { asm!("mov eax, 2" : "={eax}"(result) : : : "intel") } println!("eax is currently {}", result); # } # #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] # fn main() {}
More Information
The current implementation of the asm! macro is a direct binding to LLVM's
inline assembler expressions, so be sure to check out their
documentation as well for more information about clobbers,
constraints, etc.
If you need more power and don't mind losing some of the niceties of
asm!, check out global_asm.
atomic_min_max
The tracking issue for this feature is: #48655
backtrace
The tracking issue for this feature is: #53487
bool_to_option
The tracking issue for this feature is: #64260
bound_cloned
The tracking issue for this feature is: #61356
box_into_pin
The tracking issue for this feature is: #62370
box_into_raw_non_null
The tracking issue for this feature is: #47336
boxed_slice_try_from
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
bufreader_seek_relative
The tracking issue for this feature is: #31100
c_void_variant
This feature is internal to the Rust compiler and is not intended for general use.
cell_update
The tracking issue for this feature is: #50186
char_error_internals
This feature is internal to the Rust compiler and is not intended for general use.
clamp
The tracking issue for this feature is: #44095
cmp_min_max_by
The tracking issue for this feature is: #64460
coerce_unsized
The tracking issue for this feature is: #27732
compiler_builtins_lib
The tracking issue for this feature is: None.
This feature is required to link to the compiler_builtins crate which contains
"compiler intrinsics". Compiler intrinsics are software implementations of basic
operations like multiplication of u64s. These intrinsics are only required on
platforms where these operations don't directly map to a hardware instruction.
You should never need to explicitly link to the compiler_builtins crate when
building "std" programs as compiler_builtins is already in the dependency
graph of std. But you may need it when building no_std binary crates. If
you get a linker error like:
$PWD/src/main.rs:11: undefined reference to `__aeabi_lmul'
$PWD/src/main.rs:11: undefined reference to `__aeabi_uldivmod'
That means that you need to link to this crate.
When you link to this crate, make sure it only appears once in your crate
dependency graph. Also, it doesn't matter where in the dependency graph you
place the compiler_builtins crate.
#![feature(compiler_builtins_lib)]
#![no_std]
extern crate compiler_builtins;
concat_idents
The tracking issue for this feature is: #29599
The concat_idents feature adds a macro for concatenating multiple identifiers
into one identifier.
Examples
#![feature(concat_idents)] fn main() { fn foobar() -> u32 { 23 } let f = concat_idents!(foo, bar); assert_eq!(f(), 23); }
const_cstr_unchecked
The tracking issue for this feature is: #57563
const_generic_impls_guard
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
const_int_conversion
The tracking issue for this feature is: #57563
const_int_sign
The tracking issue for this feature is: #57563
const_saturating_int_methods
The tracking issue for this feature is: #57563
const_slice_len
The tracking issue for this feature is: #57563
const_str_as_bytes
The tracking issue for this feature is: #57563
const_str_len
The tracking issue for this feature is: #57563
const_string_new
The tracking issue for this feature is: #57563
const_type_id
The tracking issue for this feature is: #57563
const_type_name
The tracking issue for this feature is: #57563
const_vec_new
The tracking issue for this feature is: #57563
container_error_extra
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
core_intrinsics
This feature is internal to the Rust compiler and is not intended for general use.
core_panic
This feature is internal to the Rust compiler and is not intended for general use.
core_panic_info
The tracking issue for this feature is: #44489
core_private_bignum
This feature is internal to the Rust compiler and is not intended for general use.
core_private_diy_float
This feature is internal to the Rust compiler and is not intended for general use.
deadline_api
The tracking issue for this feature is: #46316
debug_map_key_value
The tracking issue for this feature is: #62482
Add the methods key and value to DebugMap so that an entry can be formatted across multiple calls without additional buffering.
dec2flt
This feature is internal to the Rust compiler and is not intended for general use.
derive_clone_copy
This feature is internal to the Rust compiler and is not intended for general use.
derive_eq
This feature is internal to the Rust compiler and is not intended for general use.
dispatch_from_dyn
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
div_duration
The tracking issue for this feature is: #63139
drain_filter
The tracking issue for this feature is: #43244
duration_constants
The tracking issue for this feature is: #57391
error_iter
The tracking issue for this feature is: #58520
error_type_id
The tracking issue for this feature is: #60784
exact_size_is_empty
The tracking issue for this feature is: #35428
extra_log_consts
The tracking issue for this feature is: #50540
fd
This feature is internal to the Rust compiler and is not intended for general use.
fd_read
This feature is internal to the Rust compiler and is not intended for general use.
fixed_size_array
The tracking issue for this feature is: #27778
float_to_from_bytes
The tracking issue for this feature is: #60446
flt2dec
This feature is internal to the Rust compiler and is not intended for general use.
fmt_internals
This feature is internal to the Rust compiler and is not intended for general use.
fn_traits
The tracking issue for this feature is #29625
See Also: unboxed_closures
The fn_traits feature allows for implementation of the Fn* traits
for creating custom closure-like types.
#![feature(unboxed_closures)] #![feature(fn_traits)] struct Adder { a: u32 } impl FnOnce<(u32, )> for Adder { type Output = u32; extern "rust-call" fn call_once(self, b: (u32, )) -> Self::Output { self.a + b.0 } } fn main() { let adder = Adder { a: 3 }; assert_eq!(adder(2), 5); }
foo
The tracking issue for this feature is: #57563
forget_unsized
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
format_args_nl
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
gen_future
The tracking issue for this feature is: #50547
generator_trait
The tracking issue for this feature is: #43122
get_mut_unchecked
The tracking issue for this feature is: #63292
global_asm
The tracking issue for this feature is: #35119
The global_asm! macro allows the programmer to write arbitrary
assembly outside the scope of a function body, passing it through
rustc and llvm to the assembler. The macro is a no-frills
interface to LLVM's concept of module-level inline assembly. That is,
all caveats applicable to LLVM's module-level inline assembly apply
to global_asm!.
global_asm! fills a role not currently satisfied by either asm!
or #[naked] functions. The programmer has all features of the
assembler at their disposal. The linker will expect to resolve any
symbols defined in the inline assembly, modulo any symbols marked as
external. It also means syntax for directives and assembly follow the
conventions of the assembler in your toolchain.
A simple usage looks like this:
# #![feature(global_asm)]
# you also need relevant target_arch cfgs
global_asm!(include_str!("something_neato.s"));
And a more complicated usage looks like this:
# #![feature(global_asm)]
# #![cfg(any(target_arch = "x86", target_arch = "x86_64"))]
pub mod sally {
global_asm!(r#"
.global foo
foo:
jmp baz
"#);
#[no_mangle]
pub unsafe extern "C" fn baz() {}
}
// the symbols `foo` and `bar` are global, no matter where
// `global_asm!` was used.
extern "C" {
fn foo();
fn bar();
}
pub mod harry {
global_asm!(r#"
.global bar
bar:
jmp quux
"#);
#[no_mangle]
pub unsafe extern "C" fn quux() {}
}
You may use global_asm! multiple times, anywhere in your crate, in
whatever way suits you. The effect is as if you concatenated all
usages and placed the larger, single usage in the crate root.
If you don't need quite as much power and flexibility as
global_asm! provides, and you don't mind restricting your inline
assembly to fn bodies only, you might try the
asm feature instead.
hash_raw_entry
The tracking issue for this feature is: #56167
hash_set_entry
The tracking issue for this feature is: #60896
hashmap_internals
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
inner_deref
The tracking issue for this feature is: #50264
int_error_internals
This feature is internal to the Rust compiler and is not intended for general use.
int_error_matching
The tracking issue for this feature is: #22639
integer_atomics
The tracking issue for this feature is: #32976
internal_uninit_const
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
io_slice_advance
The tracking issue for this feature is: #62726
ip
The tracking issue for this feature is: #27709
is_sorted
The tracking issue for this feature is: #53485
Add the methods is_sorted, is_sorted_by and is_sorted_by_key to [T];
add the methods is_sorted, is_sorted_by and is_sorted_by_key to
Iterator.
iter_is_partitioned
The tracking issue for this feature is: #62544
iter_once_with
The tracking issue for this feature is: #57581
iter_order_by
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
iter_partition_in_place
The tracking issue for this feature is: #62543
liballoc_internals
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
libstd_io_internals
This feature is internal to the Rust compiler and is not intended for general use.
libstd_sys_internals
This feature is internal to the Rust compiler and is not intended for general use.
libstd_thread_internals
This feature is internal to the Rust compiler and is not intended for general use.
linked_list_extras
The tracking issue for this feature is: #27794
log_syntax
The tracking issue for this feature is: #29598
manually_drop_take
The tracking issue for this feature is: #55422
map_entry_replace
The tracking issue for this feature is: #44286
map_get_key_value
The tracking issue for this feature is: #49347
maybe_uninit_extra
The tracking issue for this feature is: #63567
maybe_uninit_ref
The tracking issue for this feature is: #63568
maybe_uninit_slice
The tracking issue for this feature is: #63569
mem_take
The tracking issue for this feature is: #61129
new_uninit
The tracking issue for this feature is: #63291
no_more_cas
The tracking issue for this feature is: #48655
once_is_completed
The tracking issue for this feature is: #54890
once_poison
The tracking issue for this feature is: #33577
option_expect_none
The tracking issue for this feature is: #62633
option_flattening
The tracking issue for this feature is: #60258
option_result_contains
The tracking issue for this feature is: #62358
option_unwrap_none
The tracking issue for this feature is: #62633
panic_abort
The tracking issue for this feature is: #32837
panic_info_message
The tracking issue for this feature is: #44489
panic_internals
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
panic_unwind
The tracking issue for this feature is: #32837
path_buf_capacity
The tracking issue for this feature is: #58234
pattern
The tracking issue for this feature is: #27721
poll_map
The tracking issue for this feature is: #63514
print_internals
This feature is internal to the Rust compiler and is not intended for general use.
proc_macro_def_site
The tracking issue for this feature is: #54724
proc_macro_diagnostic
The tracking issue for this feature is: #54140
proc_macro_internals
The tracking issue for this feature is: #27812
proc_macro_quote
The tracking issue for this feature is: #54722
proc_macro_raw_ident
The tracking issue for this feature is: #54723
proc_macro_span
The tracking issue for this feature is: #54725
process_exitcode_placeholder
The tracking issue for this feature is: #48711
process_internals
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
profiler_runtime_lib
This feature is internal to the Rust compiler and is not intended for general use.
ptr_internals
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
ptr_offset_from
The tracking issue for this feature is: #41079
ptr_wrapping_offset_from
The tracking issue for this feature is: #41079
range_is_empty
The tracking issue for this feature is: #48111
raw
The tracking issue for this feature is: #27751
raw_vec_internals
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
rc_into_raw_non_null
The tracking issue for this feature is: #47336
read_initializer
The tracking issue for this feature is: [#42788]
receiver_trait
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
renamed_spin_loop
The tracking issue for this feature is: #55002
repeat_generic_slice
The tracking issue for this feature is: #48784
result_cloned
The tracking issue for this feature is: #63168
result_contains_err
The tracking issue for this feature is: #62358
result_copied
The tracking issue for this feature is: #63168
result_map_or_else
The tracking issue for this feature is: #53268
rt
This feature is internal to the Rust compiler and is not intended for general use.
sanitizer_runtime_lib
This feature is internal to the Rust compiler and is not intended for general use.
saturating_neg
The tracking issue for this feature is: #59983
seek_convenience
The tracking issue for this feature is: #59359
set_stdio
This feature is internal to the Rust compiler and is not intended for general use.
sgx_platform
The tracking issue for this feature is: #56975
shrink_to
The tracking issue for this feature is: #56431
slice_concat_ext
The tracking issue for this feature is: #27747
slice_concat_trait
The tracking issue for this feature is: #27747
slice_from_raw_parts
The tracking issue for this feature is: #36925
slice_index_methods
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
slice_internals
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
slice_iter_mut_as_slice
The tracking issue for this feature is: #58957
slice_partition_at_index
The tracking issue for this feature is: #55300
slice_partition_dedup
The tracking issue for this feature is: #54279
sort_internals
This feature is internal to the Rust compiler and is not intended for general use.
std_internals
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
stdsimd
The tracking issue for this feature is: #48556
step_trait
The tracking issue for this feature is: #42168
str_internals
This feature is internal to the Rust compiler and is not intended for general use.
termination_trait_lib
The tracking issue for this feature is: #43301
test
The tracking issue for this feature is: None.
The internals of the test crate are unstable, behind the test flag. The
most widely used part of the test crate are benchmark tests, which can test
the performance of your code. Let's make our src/lib.rs look like this
(comments elided):
#![feature(test)]
extern crate test;
pub fn add_two(a: i32) -> i32 {
a + 2
}
#[cfg(test)]
mod tests {
use super::*;
use test::Bencher;
#[test]
fn it_works() {
assert_eq!(4, add_two(2));
}
#[bench]
fn bench_add_two(b: &mut Bencher) {
b.iter(|| add_two(2));
}
}
Note the test feature gate, which enables this unstable feature.
We've imported the test crate, which contains our benchmarking support.
We have a new function as well, with the bench attribute. Unlike regular
tests, which take no arguments, benchmark tests take a &mut Bencher. This
Bencher provides an iter method, which takes a closure. This closure
contains the code we'd like to benchmark.
We can run benchmark tests with cargo bench:
$ cargo bench
Compiling adder v0.0.1 (file:///home/steve/tmp/adder)
Running target/release/adder-91b3e234d4ed382a
running 2 tests
test tests::it_works ... ignored
test tests::bench_add_two ... bench: 1 ns/iter (+/- 0)
test result: ok. 0 passed; 0 failed; 1 ignored; 1 measured
Our non-benchmark test was ignored. You may have noticed that cargo bench
takes a bit longer than cargo test. This is because Rust runs our benchmark
a number of times, and then takes the average. Because we're doing so little
work in this example, we have a 1 ns/iter (+/- 0), but this would show
the variance if there was one.
Advice on writing benchmarks:
- Move setup code outside the
iterloop; only put the part you want to measure inside - Make the code do "the same thing" on each iteration; do not accumulate or change state
- Make the outer function idempotent too; the benchmark runner is likely to run it many times
- Make the inner
iterloop short and fast so benchmark runs are fast and the calibrator can adjust the run-length at fine resolution - Make the code in the
iterloop do something simple, to assist in pinpointing performance improvements (or regressions)
Gotcha: optimizations
There's another tricky part to writing benchmarks: benchmarks compiled with optimizations activated can be dramatically changed by the optimizer so that the benchmark is no longer benchmarking what one expects. For example, the compiler might recognize that some calculation has no external effects and remove it entirely.
#![feature(test)]
extern crate test;
use test::Bencher;
#[bench]
fn bench_xor_1000_ints(b: &mut Bencher) {
b.iter(|| {
(0..1000).fold(0, |old, new| old ^ new);
});
}
gives the following results
running 1 test
test bench_xor_1000_ints ... bench: 0 ns/iter (+/- 0)
test result: ok. 0 passed; 0 failed; 0 ignored; 1 measured
The benchmarking runner offers two ways to avoid this. Either, the closure that
the iter method receives can return an arbitrary value which forces the
optimizer to consider the result used and ensures it cannot remove the
computation entirely. This could be done for the example above by adjusting the
b.iter call to
# #![allow(unused_variables)] #fn main() { # struct X; # impl X { fn iter<T, F>(&self, _: F) where F: FnMut() -> T {} } let b = X; b.iter(|| { // Note lack of `;` (could also use an explicit `return`). (0..1000).fold(0, |old, new| old ^ new) }); #}
Or, the other option is to call the generic test::black_box function, which
is an opaque "black box" to the optimizer and so forces it to consider any
argument as used.
#![feature(test)] extern crate test; # fn main() { # struct X; # impl X { fn iter<T, F>(&self, _: F) where F: FnMut() -> T {} } let b = X; b.iter(|| { let n = test::black_box(1000); (0..n).fold(0, |a, b| a ^ b) }) # }
Neither of these read or modify the value, and are very cheap for small values.
Larger values can be passed indirectly to reduce overhead (e.g.
black_box(&huge_struct)).
Performing either of the above changes gives the following benchmarking results
running 1 test
test bench_xor_1000_ints ... bench: 131 ns/iter (+/- 3)
test result: ok. 0 passed; 0 failed; 0 ignored; 1 measured
However, the optimizer can still modify a testcase in an undesirable manner even when using either of the above.
thread_local_internals
This feature is internal to the Rust compiler and is not intended for general use.
thread_spawn_unchecked
The tracking issue for this feature is: #55132
tidy_test_never_used_anywhere_else
The tracking issue for this feature is: #58402
todo_macro
The tracking issue for this feature is: #59277
toowned_clone_into
The tracking issue for this feature is: #41263
trace_macros
The tracking issue for this feature is #29598.
With trace_macros you can trace the expansion of macros in your code.
Examples
#![feature(trace_macros)] fn main() { trace_macros!(true); println!("Hello, Rust!"); trace_macros!(false); }
The cargo build output:
note: trace_macro
--> src/main.rs:5:5
|
5 | println!("Hello, Rust!");
| ^^^^^^^^^^^^^^^^^^^^^^^^^
|
= note: expanding `println! { "Hello, Rust!" }`
= note: to `print ! ( concat ! ( "Hello, Rust!" , "\n" ) )`
= note: expanding `print! { concat ! ( "Hello, Rust!" , "\n" ) }`
= note: to `$crate :: io :: _print ( format_args ! ( concat ! ( "Hello, Rust!" , "\n" ) )
)`
Finished dev [unoptimized + debuginfo] target(s) in 0.60 secs
trusted_len
The tracking issue for this feature is: #37572
try_reserve
The tracking issue for this feature is: #48043
try_trait
The tracking issue for this feature is: #42327
This introduces a new trait Try for extending the ? operator to types
other than Result (a part of RFC 1859). The trait provides the canonical
way to view a type in terms of a success/failure dichotomy. This will
allow ? to supplant the try_opt! macro on Option and the try_ready!
macro on Poll, among other things.
Here's an example implementation of the trait:
/// A distinct type to represent the `None` value of an `Option`.
///
/// This enables using the `?` operator on `Option`; it's rarely useful alone.
#[derive(Debug)]
#[unstable(feature = "try_trait", issue = "42327")]
pub struct None { _priv: () }
#[unstable(feature = "try_trait", issue = "42327")]
impl<T> ops::Try for Option<T> {
type Ok = T;
type Error = None;
fn into_result(self) -> Result<T, None> {
self.ok_or(None { _priv: () })
}
fn from_ok(v: T) -> Self {
Some(v)
}
fn from_error(_: None) -> Self {
None
}
}
Note the Error associated type here is a new marker. The ? operator
allows interconversion between different Try implementers only when
the error type can be converted Into the error type of the enclosing
function (or catch block). Having a distinct error type (as opposed to
just (), or similar) restricts this to where it's semantically meaningful.
udp_peer_addr
The tracking issue for this feature is: #59127
unicode_internals
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
unicode_version
The tracking issue for this feature is: #49726
unsize
The tracking issue for this feature is: #27732
update_panic_count
This feature is internal to the Rust compiler and is not intended for general use.
vec_drain_as_slice
The tracking issue for this feature is: #58957
vec_leak
The tracking issue for this feature is: #62195
vec_remove_item
The tracking issue for this feature is: #40062
vec_resize_default
The tracking issue for this feature is: #41758
wait_timeout_until
The tracking issue for this feature is: #47960
wait_until
The tracking issue for this feature is: #47960
wasi_ext
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
weak_counts
The tracking issue for this feature is: #57977
weak_into_raw
The tracking issue for this feature is: #60728
windows_by_handle
The tracking issue for this feature is: #63010
windows_c
This feature is internal to the Rust compiler and is not intended for general use.
windows_file_type_ext
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
windows_handle
This feature is internal to the Rust compiler and is not intended for general use.
windows_net
This feature is internal to the Rust compiler and is not intended for general use.
windows_stdio
This feature is internal to the Rust compiler and is not intended for general use.
wrapping_int_impl
The tracking issue for this feature is: #32463
wrapping_next_power_of_two
The tracking issue for this feature is: #32463