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
linker-flavor
The tracking issue for this feature is: None
Every rustc
target defaults to some linker. For example, Linux targets default
to gcc. In some cases, you may want to override the default; you can do that
with the unstable CLI argument: -Z linker-flavor
.
Here how you would use this flag to link a Rust binary for the
thumbv7m-none-eabi
using LLD instead of GCC.
$ xargo rustc --target thumbv7m-none-eabi -- \
-C linker=ld.lld \
-Z linker-flavor=ld \
-Z print-link-args | tr ' ' '\n'
"ld.lld"
"-L"
"$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib"
"$PWD/target/thumbv7m-none-eabi/debug/deps/app-512e9dbf385f233c.0.o"
"-o"
"$PWD/target/thumbv7m-none-eabi/debug/deps/app-512e9dbf385f233c"
"--gc-sections"
"-L"
"$PWD/target/thumbv7m-none-eabi/debug/deps"
"-L"
"$PWD/target/debug/deps"
"-L"
"$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib"
"-Bstatic"
"$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib/libcore-e1ccb7dfb1cb9ebb.rlib"
"-Bdynamic"
Whereas the default is:
$ xargo rustc --target thumbv7m-none-eabi -- \
-C link-arg=-nostartfiles \
-Z print-link-args | tr ' ' '\n'
"arm-none-eabi-gcc"
"-L"
"$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib"
"$PWD/target/thumbv7m-none-eabi/debug/deps/app-961e39416baa38d9.0.o"
"-o"
"$PWD/target/thumbv7m-none-eabi/debug/deps/app-961e39416baa38d9"
"-Wl,--gc-sections"
"-nodefaultlibs"
"-L"
"$PWD/target/thumbv7m-none-eabi/debug/deps"
"-L"
"$PWD/target/debug/deps"
"-L"
"$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib"
"-Wl,-Bstatic"
"$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib/libcore-e1ccb7dfb1cb9ebb.rlib"
"-nostartfiles"
"-Wl,-Bdynamic"
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.
remap-path-prefix
The tracking issue for this feature is: #41555
The -Z remap-path-prefix-from
, -Z remap-path-prefix-to
commandline option
pair allows to replace prefixes of any file paths the compiler emits in various
places. This is useful for bringing debuginfo paths into a well-known form and
for achieving reproducible builds independent of the directory the compiler was
executed in. All paths emitted by the compiler are affected, including those in
error messages.
In order to map all paths starting with /home/foo/my-project/src
to
/sources/my-project
, one would invoke the compiler as follows:
rustc -Zremap-path-prefix-from="/home/foo/my-project/src" -Zremap-path-prefix-to="/sources/my-project"
Debuginfo for code from the file /home/foo/my-project/src/foo/mod.rs
,
for example, would then point debuggers to /sources/my-project/foo/mod.rs
instead of the original file.
The options can be specified multiple times when multiple prefixes should be mapped:
rustc -Zremap-path-prefix-from="/home/foo/my-project/src" \
-Zremap-path-prefix-to="/sources/my-project" \
-Zremap-path-prefix-from="/home/foo/my-project/build-dir" \
-Zremap-path-prefix-to="/stable-build-dir"
When the options are given multiple times, the nth -from
will be matched up
with the nth -to
and they can appear anywhere on the commandline. Mappings
specified later on the line will take precedence over earlier ones.
Language features
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_sysv64
The tracking issue for this feature is: #36167
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
advanced_slice_patterns
The tracking issue for this feature is: #23121
See also slice_patterns
.
The advanced_slice_patterns
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 identifier before the ..
, the result of the
slice will be bound to that name. For example:
#![feature(advanced_slice_patterns, 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)); }
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: #42219
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.
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.
associated_type_defaults
The tracking issue for this feature is: #29661
attr_literals
The tracking issue for this feature is: #34981
At present, literals are only accepted as the value of a key-value pair in
attributes. What's more, only string literals are accepted. This means that
literals can only appear in forms of #[attr(name = "value")]
or
#[attr = "value"]
.
The attr_literals
unstable feature allows other types of literals to be used
in attributes. Here are some examples of attributes that can now be used with
this feature enabled:
+rust,ignore +#[attr] +#[attr(true)] +#[attr(ident)] +#[attr(ident, 100, true, "true", ident = 100, ident = "hello", ident(100))] +#[attr(100)] +#[attr(enabled = true)] +#[enabled(true)] +#[attr("hello")] +#[repr(C, align = 4)] +#[repr(C, align(4))]
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: #27779
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; }
catch_expr
The tracking issue for this feature is: #31436
The catch_expr
feature adds support for a catch
expression. The catch
expression creates a new scope one can use the ?
operator in.
# #![allow(unused_variables)] #![feature(catch_expr)] #fn main() { use std::num::ParseIntError; let result: Result<i32, ParseIntError> = do catch { Ok("1".parse::<i32>()? + "2".parse::<i32>()? + "3".parse::<i32>()?) }; assert_eq!(result, Ok(6)); let result: Result<i32, ParseIntError> = do catch { Ok("1".parse::<i32>()? + "foo".parse::<i32>()? + "3".parse::<i32>()?) }; assert!(result.is_err()); #}
cfg_target_feature
The tracking issue for this feature is: #29717
cfg_target_has_atomic
The tracking issue for this feature is: #32976
cfg_target_thread_local
The tracking issue for this feature is: #29594
cfg_target_vendor
The tracking issue for this feature is: #29718
compiler_builtins
This feature is internal to the Rust compiler and is not intended for general use.
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); }
conservative_impl_trait
The tracking issue for this feature is: #34511
The conservative_impl_trait
feature allows a conservative form of abstract
return types.
Abstract return types allow a function to hide a concrete return type behind a trait interface similar to trait objects, while still generating the same statically dispatched code as with concrete types.
Examples
#![feature(conservative_impl_trait)] fn even_iter() -> impl Iterator<Item=u32> { (0..).map(|n| n * 2) } fn main() { let first_four_even_numbers = even_iter().take(4).collect::<Vec<_>>(); assert_eq!(first_four_even_numbers, vec![0, 2, 4, 6]); }
Background
In today's Rust, you can write function signatures like:
fn consume_iter_static<I: Iterator<Item=u8>>(iter: I) { }
fn consume_iter_dynamic(iter: Box<Iterator<Item=u8>>) { }
In both cases, the function does not depend on the exact type of the argument. The type held is "abstract", and is assumed only to satisfy a trait bound.
- In the
_static
version using generics, each use of the function is specialized to a concrete, statically-known type, giving static dispatch, inline layout, and other performance wins. - In the
_dynamic
version using trait objects, the concrete argument type is only known at runtime using a vtable.
On the other hand, while you can write:
fn produce_iter_dynamic() -> Box<Iterator<Item=u8>> { }
...but you cannot write something like:
fn produce_iter_static() -> Iterator<Item=u8> { }
That is, in today's Rust, abstract return types can only be written using trait
objects, which can be a significant performance penalty. This RFC proposes
"unboxed abstract types" as a way of achieving signatures like
produce_iter_static
. Like generics, unboxed abstract types guarantee static
dispatch and inline data layout.
const_fn
The tracking issue for this feature is: #24111
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_indexing
The tracking issue for this feature is: #29947
The const_indexing
feature allows the constant evaluation of index operations
on constant arrays and repeat expressions.
Examples
# #![allow(unused_variables)] #![feature(const_indexing)] #fn main() { const ARR: [usize; 5] = [1, 2, 3, 4, 5]; const ARR2: [usize; ARR[1]] = [42, 99]; #}
custom_attribute
The tracking issue for this feature is: #29642
custom_derive
The tracking issue for this feature is: #29644
decl_macro
The tracking issue for this feature is: #39412
default_type_parameter_fallback
The tracking issue for this feature is: #27336
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.
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, feature = "documentation"))] #[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 { // ... } #}
drop_types_in_const
The tracking issue for this feature is: #33156
dropck_eyepatch
The tracking issue for this feature is: #34761
dropck_parametricity
The tracking issue for this feature is: #28498
exclusive_range_pattern
The tracking issue for this feature is: #37854
fn_must_use
The tracking issue for this feature is: #43302
fundamental
The tracking issue for this feature is: #29635
generic_param_attrs
The tracking issue for this feature is: #34761
global_allocator
The tracking issue for this feature is: #27389
Rust programs may need to change the allocator that they're running with from
time to time. This use case is distinct from an allocator-per-collection (e.g. a
Vec
with a custom allocator) and instead is more related to changing the
global default allocator, e.g. what Vec<T>
uses by default.
Currently Rust programs don't have a specified global allocator. The compiler
may link to a version of jemalloc on some platforms, but this is not
guaranteed. Libraries, however, like cdylibs and staticlibs are guaranteed
to use the "system allocator" which means something like malloc
on Unixes and
HeapAlloc
on Windows.
The #[global_allocator]
attribute, however, allows configuring this choice.
You can use this to implement a completely custom global allocator to route all
default allocation requests to a custom object. Defined in RFC 1974 usage
looks like:
#![feature(global_allocator, allocator_api, heap_api)] use std::heap::{Alloc, System, Layout, AllocErr}; struct MyAllocator; unsafe impl<'a> Alloc for &'a MyAllocator { unsafe fn alloc(&mut self, layout: Layout) -> Result<*mut u8, AllocErr> { System.alloc(layout) } unsafe fn dealloc(&mut self, ptr: *mut u8, layout: Layout) { System.dealloc(ptr, layout) } } #[global_allocator] static GLOBAL: MyAllocator = MyAllocator; fn main() { // This `Vec` will allocate memory through `GLOBAL` above let mut v = Vec::new(); v.push(1); }
And that's it! The #[global_allocator]
attribute is applied to a static
which implements the Alloc
trait in the std::heap
module. Note, though,
that the implementation is defined for &MyAllocator
, not just MyAllocator
.
You may wish, however, to also provide Alloc for MyAllocator
for other use
cases.
A crate can only have one instance of #[global_allocator]
and this instance
may be loaded through a dependency. For example #[global_allocator]
above
could have been placed in one of the dependencies loaded through extern crate
.
Note that Alloc
itself is an unsafe
trait, with much documentation on the
trait itself about usage and for implementors. Extra care should be taken when
implementing a global allocator as well as the allocator may be called from many
portions of the standard library, such as the panicking routine. As a result it
is highly recommended to not panic during allocation and work in as many
situations with as few dependencies as possible as well.
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.
i128_type
The tracking issue for this feature is: #35118
The i128_type
feature adds support for 128 bit signed and unsigned integer
types.
#![feature(i128_type)] fn main() { assert_eq!(1u128 + 1u128, 2u128); assert_eq!(u128::min_value(), 0); assert_eq!(u128::max_value(), 340282366920938463463374607431768211455); assert_eq!(1i128 - 2i128, -1i128); assert_eq!(i128::min_value(), -170141183460469231731687303715884105728); assert_eq!(i128::max_value(), 170141183460469231731687303715884105727); }
inclusive_range_syntax
The tracking issue for this feature is: #28237
To get a range that goes from 0 to 10 and includes the value 10, you
can write 0...10
:
#![feature(inclusive_range_syntax)] fn main() { for i in 0...10 { println!("{}", i); } }
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.
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;
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 = "exchange_free"]
unsafe fn deallocate(ptr: *mut u8, _size: usize, _align: usize) {
libc::free(ptr as *mut libc::c_void)
}
#[lang = "box_free"]
unsafe fn box_free<T: ?Sized>(ptr: *mut T) {
deallocate(ptr as *mut u8, ::core::mem::size_of_val(&*ptr), ::core::mem::align_of_val(&*ptr));
}
#[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_fmt"] extern fn rust_begin_panic() -> ! { 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
, andadd
respectively. - stack unwinding and general failure; the
eh_personality
,eh_unwind_resume
,fail
andfail_bounds_checks
lang items. - the traits in
std::marker
used to indicate types of various kinds; lang itemssend
,sync
andcopy
. - 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 exchange_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;
// 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_fmt"]
#[no_mangle]
pub extern fn rust_begin_panic(_msg: core::fmt::Arguments,
_file: &'static str,
_line: u32,
_column: u32) -> ! {
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;
// 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_fmt"]
#[no_mangle]
pub extern fn rust_begin_panic(_msg: core::fmt::Arguments,
_file: &'static str,
_line: u32,
_column: u32) -> ! {
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_fmt
, 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
.
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
log_syntax
The tracking issue for this feature is: #29598
macro_reexport
The tracking issue for this feature is: #29638
macro_vis_matcher
The tracking issue for this feature is: #41022
With this feature gate enabled, the list of fragment specifiers gains one more entry:
vis
: a visibility qualifier. Examples: nothing (default visibility);pub
;pub(crate)
.
A vis
variable may be followed by a comma, ident, type, or path.
main
The tracking issue for this feature is: #29634
naked_functions
The tracking issue for this feature is: #32408
needs_allocator
The tracking issue for this feature is: #27389
needs_panic_runtime
The tracking issue for this feature is: #32837
never_type
The tracking issue for this feature is: #35121
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: #28979
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; #}
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.
For example:
#![feature(on_unimplemented)] #[rustc_on_unimplemented="a collection of type `{Self}` cannot be built from an \ iterator over elements of type `{A}`"] 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][..]);
| ^^^^^^^^^^^^^ the trait `MyIterator<char>` is not implemented for `&[{integer}]`
|
= note: a collection of type `&[{integer}]` cannot be built from an iterator over elements of type `char`
= note: required by `iterate_chars`
error: aborting due to previous error
optin_builtin_traits
The tracking issue for this feature is: #13231
overlapping_marker_traits
The tracking issue for this feature is: #29864
panic_runtime
The tracking issue for this feature is: #32837
placement_in_syntax
The tracking issue for this feature is: #27779
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_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 rustc;
extern crate rustc_plugin;
use syntax::parse::token;
use syntax::tokenstream::TokenTree;
use syntax::ext::base::{ExtCtxt, MacResult, DummyResult, MacEager};
use syntax::ext::build::AstBuilder; // A trait for expr_usize.
use syntax::ext::quote::rt::Span;
use rustc_plugin::Registry;
fn expand_rn(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
-> Box<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[0] {
TokenTree::Token(_, 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
enum. For a more involved macro example, see
regex_macros
.
Tips and tricks
Some of the macro debugging tips are applicable.
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 Span
s 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
.
The example above produced an integer literal using AstBuilder::expr_usize
.
As an alternative to the AstBuilder
trait, libsyntax
provides a set of
quasiquote macros. They are undocumented and very rough around the edges.
However, the implementation may be a good starting point for an improved
quasiquote as an ordinary plugin library.
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_plugin;
use rustc::lint::{EarlyContext, LintContext, LintPass, EarlyLintPass,
EarlyLintPassObject, LintArray};
use rustc_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.name.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 staticLint
structs; -
a struct holding any state needed by the lint pass (here, none);
-
a
LintPass
implementation defining how to check each syntax element. A singleLintPass
may callspan_lint
for several differentLint
s, but should register them all through theget_lints
method.
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.
prelude_import
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
proc_macro
The tracking issue for this feature is: #38356
This feature flag guards the new procedural macro features as laid out by RFC 1566, which alongside the now-stable custom derives, provide stabilizable alternatives to the compiler plugin API (which requires the use of perma-unstable internal APIs) for programmatically modifying Rust code at compile-time.
The two new procedural macro kinds are:
-
Function-like procedural macros which are invoked like regular declarative macros, and:
-
Attribute-like procedural macros which can be applied to any item which built-in attributes can be applied to, and which can take arguments in their invocation as well.
Additionally, this feature flag implicitly enables the use_extern_macros
feature,
which allows macros to be imported like any other item with use
statements, as compared to
applying #[macro_use]
to an extern crate
declaration. It is important to note that procedural macros may
only be imported in this manner, and will throw an error otherwise.
You must declare the proc_macro
feature in both the crate declaring these new procedural macro kinds as well as
in any crates that use them.
Common Concepts
As with custom derives, procedural macros may only be declared in crates of the proc-macro
type, and must be public
functions. No other public items may be declared in proc-macro
crates, but private items are fine.
To declare your crate as a proc-macro
crate, simply add:
[lib]
proc-macro = true
to your Cargo.toml
.
Unlike custom derives, however, the name of the function implementing the procedural macro is used directly as the procedural macro's name, so choose carefully.
Additionally, both new kinds of procedural macros return a TokenStream
which wholly replaces the original
invocation and its input.
Importing
As referenced above, the new procedural macros are not meant to be imported via #[macro_use]
and will throw an
error if they are. Instead, they are meant to be imported like any other item in Rust, with use
statements:
#![feature(proc_macro)]
// Where `my_proc_macros` is some crate of type `proc_macro`
extern crate my_proc_macros;
// And declares a `#[proc_macro] pub fn my_bang_macro()` at its root.
use my_proc_macros::my_bang_macro;
fn main() {
println!("{}", my_bang_macro!());
}
Error Reporting
Any panics in a procedural macro implementation will be caught by the compiler and turned into an error message pointing
to the problematic invocation. Thus, it is important to make your panic messages as informative as possible: use
Option::expect
instead of Option::unwrap
and Result::expect
instead of Result::unwrap
, and inform the user of
the error condition as unambiguously as you can.
TokenStream
The proc_macro::TokenStream
type is hardcoded into the signatures of procedural macro functions for both input and
output. It is a wrapper around the compiler's internal representation for a given chunk of Rust code.
Function-like Procedural Macros
These are procedural macros that are invoked like regular declarative macros. They are declared as public functions in
crates of the proc_macro
type and using the #[proc_macro]
attribute. The name of the declared function becomes the
name of the macro as it is to be imported and used. The function must be of the kind fn(TokenStream) -> TokenStream
where the sole argument is the input to the macro and the return type is the macro's output.
This kind of macro can expand to anything that is valid for the context it is invoked in, including expressions and statements, as well as items.
Note: invocations of this kind of macro require a wrapping []
, {}
or ()
like regular macros, but these do not
appear in the input, only the tokens between them. The tokens between the braces do not need to be valid Rust syntax.
my_macro_crate/src/lib.rs
#![feature(proc_macro)]
// This is always necessary to get the `TokenStream` typedef.
extern crate proc_macro;
use proc_macro::TokenStream;
#[proc_macro]
pub fn say_hello(_input: TokenStream) -> TokenStream {
// This macro will accept any input because it ignores it.
// To enforce correctness in macros which don't take input,
// you may want to add `assert!(_input.to_string().is_empty());`.
"println!(\"Hello, world!\")".parse().unwrap()
}
my_macro_user/Cargo.toml
[dependencies]
my_macro_crate = { path = "<relative path to my_macro_crate>" }
my_macro_user/src/lib.rs
#![feature(proc_macro)]
extern crate my_macro_crate;
use my_macro_crate::say_hello;
fn main() {
say_hello!();
}
As expected, this prints Hello, world!
.
Attribute-like Procedural Macros
These are arguably the most powerful flavor of procedural macro as they can be applied anywhere attributes are allowed.
They are declared as public functions in crates of the proc-macro
type, using the #[proc_macro_attribute]
attribute.
The name of the function becomes the name of the attribute as it is to be imported and used. The function must be of the
kind fn(TokenStream, TokenStream) -> TokenStream
where:
The first argument represents any metadata for the attribute (see the reference chapter on attributes). Only the metadata itself will appear in this argument, for example:
#[my_macro]
will get an empty string.#[my_macro = "string"]
will get= "string"
.#[my_macro(ident)]
will get(ident)
.- etc.
The second argument is the item that the attribute is applied to. It can be a function, a type definition,
an impl block, an extern
block, or a module—attribute invocations can take the inner form (#![my_attr]
)
or outer form (#[my_attr]
).
The return type is the output of the macro which wholly replaces the item it was applied to. Thus, if your intention is to merely modify an item, it must be copied to the output. The output must be an item; expressions, statements and bare blocks are not allowed.
There is no restriction on how many items an attribute-like procedural macro can emit as long as they are valid in the given context.
my_macro_crate/src/lib.rs
#![feature(proc_macro)]
extern crate proc_macro;
use proc_macro::TokenStream;
/// Adds a `/// ### Panics` docstring to the end of the input's documentation
///
/// Does not assert that its receiver is a function or method.
#[proc_macro_attribute]
pub fn panics_note(args: TokenStream, input: TokenStream) -> TokenStream {
let args = args.to_string();
let mut input = input.to_string();
assert!(args.starts_with("= \""), "`#[panics_note]` requires an argument of the form \
`#[panics_note = \"panic note here\"]`");
// Get just the bare note string
let panics_note = args.trim_matches(&['=', ' ', '"'][..]);
// The input will include all docstrings regardless of where the attribute is placed,
// so we need to find the last index before the start of the item
let insert_idx = idx_after_last_docstring(&input);
// And insert our `### Panics` note there so it always appears at the end of an item's docs
input.insert_str(insert_idx, &format!("/// # Panics \n/// {}\n", panics_note));
input.parse().unwrap()
}
// `proc-macro` crates can contain any kind of private item still
fn idx_after_last_docstring(input: &str) -> usize {
// Skip docstring lines to find the start of the item proper
input.lines().skip_while(|line| line.trim_left().starts_with("///")).next()
// Find the index of the first non-docstring line in the input
// Note: assumes this exact line is unique in the input
.and_then(|line_after| input.find(line_after))
// No docstrings in the input
.unwrap_or(0)
}
my_macro_user/Cargo.toml
[dependencies]
my_macro_crate = { path = "<relative path to my_macro_crate>" }
my_macro_user/src/lib.rs
#![feature(proc_macro)]
extern crate my_macro_crate;
use my_macro_crate::panics_note;
/// Do the `foo` thing.
#[panics_note = "Always."]
pub fn foo() {
panic!()
}
Then the rendered documentation for pub fn foo
will look like this:
pub fn foo()
Do the
foo
thing.Panics
Always.
profiler_runtime
The tracking issue for this feature is: #42524.
quote
The tracking issue for this feature is: #29601
repr_align
The tracking issue for this feature is: #33626
repr_simd
The tracking issue for this feature is: #27731
rustc_attrs
The tracking issue for this feature is: #29642
rustc_diagnostic_macros
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
sanitizer_runtime
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
simd
The tracking issue for this feature is: #27731
simd_ffi
The tracking issue for this feature is: #27731
slice_patterns
The tracking issue for this feature is: #23121
See also
advanced_slice_patterns
.
If you want to match against a slice or array, you can use &
with the
slice_patterns
feature:
#![feature(slice_patterns)] fn main() { let v = vec!["match_this", "1"]; match &v[..] { &["match_this", second] => println!("The second element is {}", second), _ => {}, } }
specialization
The tracking issue for this feature is: #31844
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
target_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
trace_macros
The tracking issue for this feature is: #29598
type_ascription
The tracking issue for this feature is: #23416
unboxed_closures
The tracking issue for this feature is: #29625
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
This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
use_extern_macros
The tracking issue for this feature is: #35896
used
The tracking issue for this feature is: 40289.
The #[used]
attribute can be applied to static
variables to prevent the Rust
compiler from optimizing them away even if they appear to be unused by the crate
(appear to be "dead code").
#![feature(used)] #[used] static FOO: i32 = 1; static BAR: i32 = 2; fn main() {}
If you compile this program into an object file, you'll see that FOO
makes it
to the object file but BAR
doesn't. Neither static variable is used by the
program.
$ rustc -C opt-level=3 --emit=obj used.rs
$ nm -C used.o
0000000000000000 T main
U std::rt::lang_start
0000000000000000 r used::FOO
0000000000000000 t used::main
Note that the linker knows nothing about the #[used]
attribute and will
remove #[used]
symbols if they are not referenced by other parts of the
program:
$ rustc -C opt-level=3 used.rs
$ nm -C used | grep FOO
"This doesn't sound too useful then!" you may think but keep reading.
To preserve the symbols all the way to the final binary, you'll need the cooperation of the linker. Here's one example:
The ELF standard defines two special sections, .init_array
and
.pre_init_array
, that may contain function pointers which will be executed
before the main
function is invoked. The linker will preserve symbols placed
in these sections (at least when linking programs that target the *-*-linux-*
targets).
#![feature(used)]
extern "C" fn before_main() {
println!("Hello, world!");
}
#[link_section = ".init_array"]
#[used]
static INIT_ARRAY: [extern "C" fn(); 1] = [before_main];
fn main() {}
So, #[used]
and #[link_section]
can be combined to obtain "life before
main".
$ rustc -C opt-level=3 before-main.rs
$ ./before-main
Hello, world!
Another example: ARM Cortex-M microcontrollers need their reset handler, a pointer to the function that will executed right after the microcontroller is turned on, to be placed near the start of their FLASH memory to boot properly.
This condition can be met using #[used]
and #[link_section]
plus a linker
script.
#![feature(lang_items)]
#![feature(used)]
#![no_main]
#![no_std]
extern "C" fn reset_handler() -> ! {
loop {}
}
#[link_section = ".reset_handler"]
#[used]
static RESET_HANDLER: extern "C" fn() -> ! = reset_handler;
#[lang = "panic_fmt"]
fn panic_fmt() {}
MEMORY
{
FLASH : ORIGIN = 0x08000000, LENGTH = 128K
RAM : ORIGIN = 0x20000000, LENGTH = 20K
}
SECTIONS
{
.text ORIGIN(FLASH) :
{
/* Vector table */
LONG(ORIGIN(RAM) + LENGTH(RAM)); /* initial SP value */
KEEP(*(.reset_handler));
/* Omitted: The rest of the vector table */
*(.text.*);
} > FLASH
/DISCARD/ :
{
/* Unused unwinding stuff */
*(.ARM.exidx.*)
}
}
$ xargo rustc --target thumbv7m-none-eabi --release -- \
-C link-arg=-Tlink.x -C link-arg=-nostartfiles
$ arm-none-eabi-objdump -Cd target/thumbv7m-none-eabi/release/app
./target/thumbv7m-none-eabi/release/app: file format elf32-littlearm
Disassembly of section .text:
08000000 <app::RESET_HANDLER-0x4>:
8000000: 20005000 .word 0x20005000
08000004 <app::RESET_HANDLER>:
8000004: 08000009 ....
08000008 <app::reset_handler>:
8000008: e7fe b.n 8000008 <app::reset_handler>
Library Features
alloc
The tracking issue for this feature is: #27783
alloc_jemalloc
The tracking issue for this feature is: #33082
See also alloc_system
.
The compiler currently ships two default allocators: alloc_system
and
alloc_jemalloc
(some targets don't have jemalloc, however). These allocators
are normal Rust crates and contain an implementation of the routines to
allocate and deallocate memory. The standard library is not compiled assuming
either one, and the compiler will decide which allocator is in use at
compile-time depending on the type of output artifact being produced.
Binaries generated by the compiler will use alloc_jemalloc
by default (where
available). In this situation the compiler "controls the world" in the sense of
it has power over the final link. Primarily this means that the allocator
decision can be left up the compiler.
Dynamic and static libraries, however, will use alloc_system
by default. Here
Rust is typically a 'guest' in another application or another world where it
cannot authoritatively decide what allocator is in use. As a result it resorts
back to the standard APIs (e.g. malloc
and free
) for acquiring and releasing
memory.
Switching Allocators
Although the compiler's default choices may work most of the time, it's often necessary to tweak certain aspects. Overriding the compiler's decision about which allocator is in use is done simply by linking to the desired allocator:
#![feature(alloc_system)] extern crate alloc_system; fn main() { let a = Box::new(4); // Allocates from the system allocator. println!("{}", a); }
In this example the binary generated will not link to jemalloc by default but instead use the system allocator. Conversely to generate a dynamic library which uses jemalloc by default one would write:
#![feature(alloc_jemalloc)]
#![crate_type = "dylib"]
extern crate alloc_jemalloc;
pub fn foo() {
let a = Box::new(4); // Allocates from jemalloc.
println!("{}", a);
}
# fn main() {}
alloc_system
The tracking issue for this feature is: #33082
See also alloc_jemalloc
.
The compiler currently ships two default allocators: alloc_system
and
alloc_jemalloc
(some targets don't have jemalloc, however). These allocators
are normal Rust crates and contain an implementation of the routines to
allocate and deallocate memory. The standard library is not compiled assuming
either one, and the compiler will decide which allocator is in use at
compile-time depending on the type of output artifact being produced.
Binaries generated by the compiler will use alloc_jemalloc
by default (where
available). In this situation the compiler "controls the world" in the sense of
it has power over the final link. Primarily this means that the allocator
decision can be left up the compiler.
Dynamic and static libraries, however, will use alloc_system
by default. Here
Rust is typically a 'guest' in another application or another world where it
cannot authoritatively decide what allocator is in use. As a result it resorts
back to the standard APIs (e.g. malloc
and free
) for acquiring and releasing
memory.
Switching Allocators
Although the compiler's default choices may work most of the time, it's often necessary to tweak certain aspects. Overriding the compiler's decision about which allocator is in use is done simply by linking to the desired allocator:
#![feature(alloc_system)] extern crate alloc_system; fn main() { let a = Box::new(4); // Allocates from the system allocator. println!("{}", a); }
In this example the binary generated will not link to jemalloc by default but instead use the system allocator. Conversely to generate a dynamic library which uses jemalloc by default one would write:
#![feature(alloc_jemalloc)]
#![crate_type = "dylib"]
extern crate alloc_jemalloc;
pub fn foo() {
let a = Box::new(4); // Allocates from jemalloc.
println!("{}", a);
}
# fn main() {}
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
ascii_ctype
The tracking issue for this feature is: #39658
box_heap
The tracking issue for this feature is: #27779
c_void_variant
This feature is internal to the Rust compiler and is not intended for general use.
char_error_internals
This feature is internal to the Rust compiler and is not intended for general use.
coerce_unsized
The tracking issue for this feature is: #27732
collection_placement
The tracking issue for this feature is: #30172
collections
This feature is internal to the Rust compiler and is not intended for general use.
collections_range
The tracking issue for this feature is: #30877
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 u64
s. 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_macro
The tracking issue for this feature is: #29599
core_char_ext
The tracking issue for this feature is: #32110
core_float
The tracking issue for this feature is: #32110
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_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.
core_slice_ext
The tracking issue for this feature is: #32110
core_str_ext
The tracking issue for this feature is: #32110
dec2flt
This feature is internal to the Rust compiler and is not intended for general use.
decode_utf8
The tracking issue for this feature is: #33906
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.
drain_filter
The tracking issue for this feature is: #43244
error_type_id
The tracking issue for this feature is: #27745
exact_size_is_empty
The tracking issue for this feature is: #35428
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
flt2dec
This feature is internal to the Rust compiler and is not intended for general use.
fmt_flags_align
The tracking issue for this feature is: #27726
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
fnbox
The tracking issue for this feature is: #28796
from_utf8_error_as_bytes
The tracking issue for this feature is: #40895
fused
The tracking issue for this feature is: #35602
future_atomic_orderings
This feature is internal to the Rust compiler and is not intended for general use.
get_type_id
The tracking issue for this feature is: #27745
heap_api
The tracking issue for this feature is: #27700
hint_core_should_pause
The tracking issue for this feature is: #41196
Many programs have spin loops like the following:
# #![allow(unused_variables)] #fn main() { use std::sync::atomic::{AtomicBool,Ordering}; fn spin_loop(value: &AtomicBool) { loop { if value.load(Ordering::Acquire) { break; } } } #}
These programs can be improved in performance like so:
# #![allow(unused_variables)] #![feature(hint_core_should_pause)] #fn main() { use std::sync::atomic; use std::sync::atomic::{AtomicBool,Ordering}; fn spin_loop(value: &AtomicBool) { loop { if value.load(Ordering::Acquire) { break; } atomic::hint_core_should_pause(); } } #}
Further improvements could combine hint_core_should_pause
with
exponential backoff or std::thread::yield_now
.
i128
The tracking issue for this feature is: #35118
inclusive_range
The tracking issue for this feature is: #28237
int_error_internals
This feature is internal to the Rust compiler and is not intended for general use.
integer_atomics
The tracking issue for this feature is: #32976
io
The tracking issue for this feature is: #27802
io_error_internals
This feature is internal to the Rust compiler and is not intended for general use.
ip
The tracking issue for this feature is: #27709
iter_rfind
The tracking issue for this feature is: #39480
iterator_step_by
The tracking issue for this feature is: #27741
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
lookup_host
The tracking issue for this feature is: #27705
mpsc_select
The tracking issue for this feature is: #27800
n16
This feature is internal to the Rust compiler and is not intended for general use.
never_type_impls
The tracking issue for this feature is: #35121
nonzero
The tracking issue for this feature is: #27730
offset_to
The tracking issue for this feature is: #41079
once_poison
The tracking issue for this feature is: #33577
panic_abort
The tracking issue for this feature is: #32837
panic_col
The tracking issue for this feature is: #42939
panic_unwind
The tracking issue for this feature is: #32837
pattern
The tracking issue for this feature is: #27721
placement_in
The tracking issue for this feature is: #27779
placement_new_protocol
The tracking issue for this feature is: #27779
print_internals
This feature is internal to the Rust compiler and is not intended for general use.
proc_macro
The tracking issue for this feature is: #38356
proc_macro_internals
The tracking issue for this feature is: #27812
profiler_runtime_lib
This feature is internal to the Rust compiler and is not intended for general use.
rand
This feature is internal to the Rust compiler and is not intended for general use.
range_contains
The tracking issue for this feature is: #32311
raw
The tracking issue for this feature is: #27751
read_initializer
The tracking issue for this feature is: [#42788]
refcell_replace_swap
The tracking issue for this feature is: #43570
rt
This feature is internal to the Rust compiler and is not intended for general use.
rustc_private
The tracking issue for this feature is: #27812
sanitizer_runtime_lib
This feature is internal to the Rust compiler and is not intended for general use.
set_stdio
This feature is internal to the Rust compiler and is not intended for general use.
shared
The tracking issue for this feature is: #27730
sip_hash_13
The tracking issue for this feature is: #34767
slice_concat_ext
The tracking issue for this feature is: #27747
slice_get_slice
The tracking issue for this feature is: #35729
slice_rotate
The tracking issue for this feature is: #41891
slice_rsplit
The tracking issue for this feature is: #41020
The slice_rsplit
feature enables two methods on slices:
slice.rsplit(predicate)
and slice.rsplit_mut(predicate)
.
sort_internals
This feature is internal to the Rust compiler and is not intended for general use.
splice
The tracking issue for this feature is: #44643
The splice()
method on String
allows you to replace a range
of values in a string with another range of values.
A simple example:
# #![allow(unused_variables)] #![feature(splice)] #fn main() { let mut s = String::from("α is alpha, β is beta"); let beta_offset = s.find('β').unwrap_or(s.len()); // Replace the range up until the β from the string let t: String = s.splice(..beta_offset, "Α is capital alpha; ").collect(); assert_eq!(t, "α is alpha, "); assert_eq!(s, "Α is capital alpha; β is beta"); #}
step_trait
The tracking issue for this feature is: #42168
str_escape
The tracking issue for this feature is: #27791
str_internals
This feature is internal to the Rust compiler and is not intended for general use.
string_retain
The tracking issue for this feature is: #43874
Retains only the characters specified by the predicate.
In other words, remove all characters c
such that f(c)
returns false
.
This method operates in place and preserves the order of the retained
characters.
# #![allow(unused_variables)] #![feature(string_retain)] #fn main() { let mut s = String::from("f_o_ob_ar"); s.retain(|c| c != '_'); assert_eq!(s, "foobar"); #}
swap_nonoverlapping
The tracking issue for this feature is: #42818
swap_with_slice
The tracking issue for this feature is: #44030
take_set_limit
The tracking issue for this feature is: #42781
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
iter
loop; 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
iter
loop short and fast so benchmark runs are fast and the calibrator can adjust the run-length at fine resolution - Make the code in the
iter
loop 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_local_state
The tracking issue for this feature is: #27716
toowned_clone_into
The tracking issue for this feature is: #41263
trusted_len
The tracking issue for this feature is: #37572
try_from
The tracking issue for this feature is: #33417
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.
unicode
The tracking issue for this feature is: #27783
unique
The tracking issue for this feature is: #27730
unreachable
The tracking issue for this feature is: #43751
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_remove_item
The tracking issue for this feature is: #40062
vec_resize_default
The tracking issue for this feature is: #41758
windows_c
This feature is internal to the Rust compiler and is not 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.