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.

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


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: #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.


arbitrary_self_types

The tracking issue for this feature is: #44874


arm_target_feature

The tracking issue for this feature is: #44839


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:

  1. volatile - specifying this is analogous to __asm__ __volatile__ (...) in gcc/clang.
  2. 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
  3. 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


async_await

The tracking issue for this feature is: #50547


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:

#[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))]

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;
}

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 {
    "1".parse::<i32>()?
        + "2".parse::<i32>()?
        + "3".parse::<i32>()?
};
assert_eq!(result, Ok(6));

let result: Result<i32, ParseIntError> = do catch {
    "1".parse::<i32>()?
        + "foo".parse::<i32>()?
        + "3".parse::<i32>()?
};
assert!(result.is_err());
#}

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);
}

const_compare_raw_pointers

The tracking issue for this feature is: #53020


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_fn_union

The tracking issue for this feature is: #51909


const_let

The tracking issue for this feature is: #48821


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


crate_in_paths

The tracking issue for this feature is: #44660


The crate_in_paths feature allows to explicitly refer to the crate root in absolute paths using keyword crate.

This feature is required in feature(extern_absolute_paths) mode to refer to any absolute path in the local crate (absolute paths refer to extern crates by default in that mode), but can be used without feature(extern_absolute_paths) as well.

#![feature(crate_in_paths)]

// Imports, `::` is added implicitly
use crate::m::f;
use crate as root;

mod m {
    pub fn f() -> u8 { 1 }
    pub fn g() -> u8 { 2 }
    pub fn h() -> u8 { 3 }

    // OK, visibilities implicitly add starting `::` as well, like imports
    pub(in crate::m) struct S;
}

mod n
{
    use crate::m::f;
    use crate as root;
    pub fn check() {
        assert_eq!(f(), 1);
        assert_eq!(crate::m::g(), 2);
        assert_eq!(root::m::h(), 3);
    }
}

fn main() {
    assert_eq!(f(), 1);
    assert_eq!(crate::m::g(), 2);
    assert_eq!(root::m::h(), 3);
    n::check();
}

crate_visibility_modifier

The tracking issue for this feature is: #45388


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_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_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:

  1. In the annotated item's documentation, there will be a message saying "This is supported on (platform) only".

  2. 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 {
    // ...
}
#}

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:

  1. When rustdoc encounters an extern crate statement annotated with a #[doc(masked)] attribute, it marks the crate as being masked.

  2. When listing traits a given type implements, rustdoc ensures that traits from masked crates are not emitted into the documentation.

  3. 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


dropck_parametricity

The tracking issue for this feature is: #28498


exclusive_range_pattern

The tracking issue for this feature is: #37854


exhaustive_patterns

The tracking issue for this feature is: #51085


existential_type

The tracking issue for this feature is: #34511


extern_absolute_paths

The tracking issue for this feature is: #44660


The extern_absolute_paths feature enables mode allowing to refer to names from other crates "inline", without introducing extern crate items, using absolute paths like ::my_crate::a::b.

::my_crate::a::b will resolve to path a::b in crate my_crate.

feature(crate_in_paths) can be used in feature(extern_absolute_paths) mode for referring to absolute paths in the local crate (crate::a::b).

feature(extern_in_paths) provides the same effect by using keyword extern to refer to paths from other crates (extern::my_crate::a::b).

#![feature(extern_absolute_paths)]

// Suppose we have a dependency crate `xcrate` available through `Cargo.toml`, or `--extern`
// options, or standard Rust distribution, or some other means.

use xcrate::Z;

fn f() {
    use xcrate;
    use xcrate as ycrate;
    let s = xcrate::S;
    assert_eq!(format!("{:?}", s), "S");
    let z = ycrate::Z;
    assert_eq!(format!("{:?}", z), "Z");
}

fn main() {
    let s = ::xcrate::S;
    assert_eq!(format!("{:?}", s), "S");
    let z = Z;
    assert_eq!(format!("{:?}", z), "Z");
}

extern_in_paths

The tracking issue for this feature is: #44660


The extern_in_paths feature allows to refer to names from other crates "inline", without introducing extern crate items, using keyword extern.

For example, extern::my_crat::a::b will resolve to path a::b in crate my_crate.

feature(extern_absolute_paths) mode provides the same effect by resolving absolute paths like ::my_crate::a::b to paths from extern crates by default.

#![feature(extern_in_paths)]

// Suppose we have a dependency crate `xcrate` available through `Cargo.toml`, or `--extern`
// options, or standard Rust distribution, or some other means.

use extern::xcrate::Z;

fn f() {
    use extern::xcrate;
    use extern::xcrate as ycrate;
    let s = xcrate::S;
    assert_eq!(format!("{:?}", s), "S");
    let z = ycrate::Z;
    assert_eq!(format!("{:?}", z), "Z");
}

fn main() {
    let s = extern::xcrate::S;
    assert_eq!(format!("{:?}", s), "S");
    let z = Z;
    assert_eq!(format!("{:?}", z), "Z");
}

extern_prelude

The tracking issue for this feature is: #44660


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.

format_args_nl

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.


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};

fn main() {
    let mut generator = || {
        yield 1;
        return "foo"
    };

    match unsafe { generator.resume() } {
        GeneratorState::Yielded(1) => {}
        _ => panic!("unexpected value from resume"),
    }
    match unsafe { 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;

fn main() {
    let mut generator = || {
        println!("2");
        yield;
        println!("4");
    };

    println!("1");
    unsafe { generator.resume() };
    println!("3");
    unsafe { 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(generator_trait)]
# use std::ops::GeneratorState;

pub trait Generator {
    type Yield;
    type Return;
    unsafe fn resume(&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 move keyword 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::Generator trait. This allows actual execution of the generator through the Generator::resume method as well as also naming it in return types and such.

  • Traits like Send and Sync are automatically implemented for a Generator depending 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 be Send or Sync, the generator itself may not be due to internal variables live across yield points being not-Send or not-Sync. Note that generators, like closures, do not implement traits like Copy or Clone automatically.

  • 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;

fn main() {
    let ret = "foo";
    let mut generator = move || {
        yield 1;
        return ret
    };

    unsafe { generator.resume() };
    unsafe { generator.resume() };
}

This generator literal will compile down to something similar to:

#![feature(generators, generator_trait)]

use std::ops::{Generator, GeneratorState};

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;

            unsafe fn resume(&mut self) -> GeneratorState<i32, &'static str> {
                use std::mem;
                match mem::replace(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)
    };

    unsafe { generator.resume() };
    unsafe { 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


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.

hexagon_target_feature

The tracking issue for this feature is: #44839


if_while_or_patterns

The tracking issue for this feature is: #48215


impl_header_lifetime_elision

The tracking issue for this feature is: #15872


in_band_lifetimes

The tracking issue for this feature is: #44524


infer_outlives_requirements

The tracking issue for this feature is: #44493


The infer_outlives_requirements feature indicates that certain outlives requirements can be infered by the compiler rather than stating them explicitly.

For example, currently generic struct definitions that contain references, require where-clauses of the form T: 'a. By using this feature the outlives predicates will be infered, although they may still be written explicitly.

struct Foo<'a, T>
  where T: 'a // <-- currently required
  {
      bar: &'a T,
  }

Examples:

#![feature(infer_outlives_requirements)]

// Implicitly infer T: 'a
struct Foo<'a, T> {
    bar: &'a T,
}
#![feature(infer_outlives_requirements)]

// Implicitly infer `U: 'b`
struct Foo<'b, U> {
    bar: Bar<'b, U>
}

struct Bar<'a, T> where T: 'a {
    x: &'a (),
    y: T,
}
#![feature(infer_outlives_requirements)]

// Implicitly infer `b': 'a`
struct Foo<'a, 'b, T> {
    x: &'a &'b T
}
#![feature(infer_outlives_requirements)]

// Implicitly infer `<T as std::iter::Iterator>::Item : 'a`
struct Foo<'a, T: Iterator> {
    bar: &'a T::Item

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 infered 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 infered, 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.

irrefutable_let_patterns

The tracking issue for this feature is: #44495


This feature changes the way that "irrefutable patterns" are handled in the if let and while let forms. An irrefutable pattern is one that cannot fail to match -- for example, the _ pattern matches any value, and hence it is "irrefutable". Without this feature, using an irrefutable pattern in an if let gives a hard error (since often this indicates programmer error). But when the feature is enabled, the error becomes a lint (since in some cases irrefutable patterns are expected). This means you can use #[allow] to silence the lint:

#![feature(irrefutable_let_patterns)]

#[allow(irrefutable_let_patterns)]
fn main() {
    // These two examples used to be errors, but now they
    // trigger a lint (that is allowed):
    if let _ = 5 {}
    while let _ = 5 { break; }
}

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 are eq, ord, deref, and add respectively.
  • stack unwinding and general failure; the eh_personality, eh_unwind_resume, fail and fail_bounds_checks lang items.
  • the traits in std::marker used to indicate types of various kinds; lang items send, sync and copy.
  • the marker types and variance indicators found in std::marker; lang items covariant_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.rs
    • i16: libcore/num/mod.rs
    • i32: libcore/num/mod.rs
    • i64: libcore/num/mod.rs
    • i128: libcore/num/mod.rs
    • isize: libcore/num/mod.rs
    • u8: libcore/num/mod.rs
    • u16: libcore/num/mod.rs
    • u32: libcore/num/mod.rs
    • u64: libcore/num/mod.rs
    • u128: libcore/num/mod.rs
    • usize: libcore/num/mod.rs
    • f32: libstd/f32.rs
    • f64: libstd/f64.rs
    • char: libcore/char.rs
    • slice: liballoc/slice.rs
    • str: liballoc/str.rs
    • const_ptr: libcore/ptr.rs
    • mut_ptr: libcore/ptr.rs
    • unsafe_cell: libcore/cell.rs
  • Runtime
    • start: libstd/rt.rs
    • eh_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.rs
    • panic_bounds_check: libcore/panicking.rs
    • panic_impl: libcore/panicking.rs
    • panic_impl: libstd/panicking.rs
  • Allocations
    • owned_box: liballoc/boxed.rs
    • exchange_malloc: liballoc/heap.rs
    • box_free: liballoc/heap.rs
  • Operands
    • not: libcore/ops/bit.rs
    • bitand: libcore/ops/bit.rs
    • bitor: libcore/ops/bit.rs
    • bitxor: libcore/ops/bit.rs
    • shl: libcore/ops/bit.rs
    • shr: libcore/ops/bit.rs
    • bitand_assign: libcore/ops/bit.rs
    • bitor_assign: libcore/ops/bit.rs
    • bitxor_assign: libcore/ops/bit.rs
    • shl_assign: libcore/ops/bit.rs
    • shr_assign: libcore/ops/bit.rs
    • deref: libcore/ops/deref.rs
    • deref_mut: libcore/ops/deref.rs
    • index: libcore/ops/index.rs
    • index_mut: libcore/ops/index.rs
    • add: libcore/ops/arith.rs
    • sub: libcore/ops/arith.rs
    • mul: libcore/ops/arith.rs
    • div: libcore/ops/arith.rs
    • rem: libcore/ops/arith.rs
    • neg: libcore/ops/arith.rs
    • add_assign: libcore/ops/arith.rs
    • sub_assign: libcore/ops/arith.rs
    • mul_assign: libcore/ops/arith.rs
    • div_assign: libcore/ops/arith.rs
    • rem_assign: libcore/ops/arith.rs
    • eq: libcore/cmp.rs
    • ord: libcore/cmp.rs
  • Functions
    • fn: libcore/ops/function.rs
    • fn_mut: libcore/ops/function.rs
    • fn_once: libcore/ops/function.rs
    • generator_state: libcore/ops/generator.rs
    • generator: libcore/ops/generator.rs
  • Other
    • coerce_unsized: libcore/ops/unsize.rs
    • drop: libcore/ops/drop.rs
    • drop_in_place: libcore/ptr.rs
    • clone: libcore/clone.rs
    • copy: libcore/marker.rs
    • send: libcore/marker.rs
    • sized: libcore/marker.rs
    • unsize: libcore/marker.rs
    • sync: libcore/marker.rs
    • phantom_data: libcore/marker.rs
    • freeze: libcore/marker.rs
    • debug_trait: libcore/fmt/mod.rs
    • non_zero: libcore/nonzero.rs

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_at_most_once_rep

NOTE: This feature is only available in the 2018 Edition.

The tracking issue for this feature is: #48075

With this feature gate enabled, one can use ? as a Kleene operator meaning "0 or 1 repetitions" in a macro definition. Previously only + and * were allowed.

For example:

#![feature(macro_at_most_once_rep)]

macro_rules! foo {
    (something $(,)?) // `?` indicates `,` is "optional"...
        => {}
}

macro_literal_matcher

The tracking issue for this feature is: #35625

The RFC is: rfc#1576.

With this feature gate enabled, the list of fragment specifiers gains one more entry:

  • literal: a literal. Examples: 2, "string", 'c'

A literal may be followed by anything, similarly to the ident specifier.


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.


macros_in_extern

The tracking issue for this feature is: #49476


main

The tracking issue for this feature is: #29634


mips_target_feature

The tracking issue for this feature is: #44839


mmx_target_feature

The tracking issue for this feature is: #44839


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


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: #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;
#}

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

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_start and XID_continue as 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 and enums. 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. Structs 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;

non_modrs_mods

The tracking issue for this feature is: #44660


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 for Self.
  • _Self: to filter only on a particular calculated trait resolution, like Self="std::iter::Iterator<char>". This is needed because Self is 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, like crate_local) or matching against a particular method. Currently used for try.
  • from_desugaring: usable both as boolean (whether the flag is present) or matching against a particular desugaring.

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`

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) );
}

overlapping_marker_traits

The tracking issue for this feature is: #29864


panic_implementation

The tracking issue for this feature is: #44489


panic_runtime

The tracking issue for this feature is: #32837


pattern_parentheses

The tracking issue for this feature is: #51087


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 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.

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)]
#![feature(macro_vis_matcher)]
#![feature(macro_at_most_once_rep)]

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.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 static Lint structs;

  • a struct holding any state needed by the lint pass (here, none);

  • a LintPass implementation defining how to check each syntax element. A single LintPass may call span_lint for several different Lints, but should register them all through the get_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.


powerpc_target_feature

The tracking issue for this feature is: #44839


prelude_import

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.


proc_macro_expr

The tracking issue for this feature is: #38356


proc_macro_gen

The tracking issue for this feature is: #38356


proc_macro_mod

The tracking issue for this feature is: #38356


proc_macro_non_items

The tracking issue for this feature is: #38356


proc_macro_path_invoc

The tracking issue for this feature is: #38356


profiler_runtime

The tracking issue for this feature is: #42524.


quote

The tracking issue for this feature is: #29601


raw_identifiers

The tracking issue for this feature is: #48589


repr_packed

The tracking issue for this feature is #33158


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),
}
#}

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_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_ffi

The tracking issue for this feature is: #27731


slice_patterns

The tracking issue for this feature is: #23121


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


thread_local

The tracking issue for this feature is: #29594


tool_attributes

The tracking issue for this feature is: #44690


Tool attributes let you use scoped attributes to control the behavior of certain tools.

Currently tool names which can be appear in scoped attributes are restricted to clippy and rustfmt.

An example

#![feature(tool_attributes)]

#[rustfmt::skip]
fn foo() { println!("hello, world"); }

fn main() {
    foo();
}

tool_lints

The tracking issue for this feature is: #44690


Tool lints let you use scoped lints, to allow, warn, deny or forbid lints of certain tools.

Currently clippy is the only available lint tool.

It is recommended for lint tools to implement the scoped lints like this:

  • #[_(TOOL_NAME::lintname)]: for lint names
  • #[_(TOOL_NAME::lintgroup)]: for groups of lints
  • #[_(TOOL_NAME::all)]: for (almost1) all lints

An example

#![feature(tool_lints)]

#![warn(clippy::pedantic)]

#[allow(clippy::filter_map)]
fn main() {
    let v = vec![0; 10];
    let _ = v.into_iter().filter(|&x| x < 1).map(|x| x + 1).collect::<Vec<_>>();
    println!("No filter_map()!");
}
1

Some defined lint groups can be excluded here.

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

trait_alias

The tracking issue for this feature is: #41517


trivial_bounds

The tracking issue for this feature is: #48214


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() {}

underscore_imports

The tracking issue for this feature is: #48216


uniform_paths

The tracking issue for this feature is: #53130


unrestricted_attribute_tokens

The tracking issue for this feature is: #44690


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.


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(panic_implementation)]
#![feature(used)]
#![no_main]
#![no_std]

use core::panic::PanicInfo;

extern "C" fn reset_handler() -> ! {
    loop {}
}

#[link_section = ".reset_handler"]
#[used]
static RESET_HANDLER: extern "C" fn() -> ! = reset_handler;

#[panic_implementation]
fn panic_impl(info: &PanicInfo) -> ! {
    loop {}
}
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>

wasm_target_feature

The tracking issue for this feature is: #44839


Library Features

align_offset

The tracking issue for this feature is: #44488


alloc

The tracking issue for this feature is: #27783


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_jemalloc

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.


alloc_system

The tracking issue for this feature is: #32838


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.


as_cell

The tracking issue for this feature is: #43038


atomic_min_max

The tracking issue for this feature is: #48655


await_macro

The tracking issue for this feature is: #50547


box_into_raw_non_null

The tracking issue for this feature is: #47336


bufreader_buffer

The tracking issue for this feature is: #45323


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.


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_macro

The tracking issue for this feature is: #29599


const_int_ops

The tracking issue for this feature is: #24111


const_ip

The tracking issue for this feature is: #24111


const_manually_drop_new

The tracking issue for this feature is: #24111


const_slice_as_ptr

The tracking issue for this feature is: #24111


const_slice_len

The tracking issue for this feature is: #24111


const_str_as_bytes

The tracking issue for this feature is: #24111


const_str_as_ptr

The tracking issue for this feature is: #24111


const_str_len

The tracking issue for this feature is: #24111


const_string_new

The tracking issue for this feature is: #24111


const_type_id

The tracking issue for this feature is: #24111


const_vec_new

The tracking issue for this feature is: #24111


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


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.


drain_filter

The tracking issue for this feature is: #43244


duration_as_u128

The tracking issue for this feature is: #50202


duration_getters

The tracking issue for this feature is: #24111


error_type_id

The tracking issue for this feature is: #27745


euclidean_division

The tracking issue for this feature is: #49048


exact_chunks

The tracking issue for this feature is: #47115


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


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);
}

fnbox

The tracking issue for this feature is: #28796


futures_api

The tracking issue for this feature is: #50547


gen_future

The tracking issue for this feature is: #50547


generator_trait

The tracking issue for this feature is: #43122


get_type_id

The tracking issue for this feature is: #27745


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_to_from_bytes

The tracking issue for this feature is: #52963


integer_atomics

The tracking issue for this feature is: #32976


ip

The tracking issue for this feature is: #27709


ip_constructors

The tracking issue for this feature is: #44582


iterator_find_map

The tracking issue for this feature is: #49602


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


map_entry_replace

The tracking issue for this feature is: #44286


map_get_key_value

The tracking issue for this feature is: #49347


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.


no_more_cas

The tracking issue for this feature is: #48655


no_panic_pow

The tracking issue for this feature is: #48320


once_poison

The tracking issue for this feature is: #33577


option_replace

The tracking issue for this feature is: #51998


option_xor

The tracking issue for this feature is: #50512


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


pattern

The tracking issue for this feature is: #27721


pin

The tracking issue for this feature is: #49150


print_internals

This feature is internal to the Rust compiler and is not intended for general use.


proc_macro_diagnostic

The tracking issue for this feature is: #38356


proc_macro_internals

The tracking issue for this feature is: #27812


proc_macro_quote

The tracking issue for this feature is: #38356


proc_macro_raw_ident

The tracking issue for this feature is: #38356


proc_macro_span

The tracking issue for this feature is: #38356


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_contains

The tracking issue for this feature is: #32311


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.


read_initializer

The tracking issue for this feature is: [#42788]


refcell_map_split

The tracking issue for this feature is: #51476


refcell_replace_swap

The tracking issue for this feature is: #43570


repeat_generic_slice

The tracking issue for this feature is: #48784


reverse_bits

The tracking issue for this feature is: #48763


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


rustc_stack_internals

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.


rw_exact_all_at

The tracking issue for this feature is: #51984


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.


shrink_to

This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.


slice_align_to

The tracking issue for this feature is: #44488


slice_concat_ext

The tracking issue for this feature is: #27747


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_sort_by_cached_key

The tracking issue for this feature is: #34447


sort_internals

This feature is internal to the Rust compiler and is not intended for general use.


split_ascii_whitespace

The tracking issue for this feature is: #48656


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_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.


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 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.


toowned_clone_into

The tracking issue for this feature is: #41263


transpose_result

The tracking issue for this feature is: #47338


trusted_len

The tracking issue for this feature is: #37572


try_from

The tracking issue for this feature is: #33417


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.

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_remove_item

The tracking issue for this feature is: #40062


vec_resize_default

The tracking issue for this feature is: #41758


vec_resize_with

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


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