Code generation attributes

The followingattributes are used for controlling code generation.

Theinline attribute

Theinlineattribute suggests whether a copy of the attributed function’s code should be placed in the caller rather than generating a call to the function.

The syntax for theinline attribute is:

Theinline attribute may only be applied to functions withbodies —closures,async blocks,free functions,associated functions in aninherent impl ortrait impl, and associated functions in atrait definition when those functions have adefault definition .

Only the first use ofinline on a function has effect.

Theinline attribute supports these modes:

• #[inline]suggests performing inline expansion.
• #[inline(always)]suggests that inline expansion should always be performed.
• #[inline(never)]suggests that inline expansion should never be performed.

Wheninline is applied to a function in atrait, it applies only to the code of thedefault definition.

Wheninline is applied to anasync function orasync closure, it applies only to the code of the generatedpoll function.

Theinline attribute is ignored if the function is externally exported withno_mangle orexport_name.

Thecold attribute

Thecoldattribute suggests that the attributed function is unlikely to be called which may help the compiler produce better code.

Thecold attribute uses theMetaWord syntax.

Thecold attribute may only be applied to functions withbodies —closures,async blocks,free functions,associated functions in aninherent impl ortrait impl, and associated functions in atrait definition when those functions have adefault definition .

Only the first use ofcold on a function has effect.

Whencold is applied to a function in atrait, it applies only to the code of thedefault definition.

Thenaked attribute

Thenakedattribute prevents the compiler from emitting a function prologue and epilogue for the attributed function.

Thefunction body must consist of exactly onenaked_asm! macro invocation.

No function prologue or epilogue is generated for the attributed function. The assembly code in thenaked_asm! block constitutes the full body of a naked function.

Thenaked attribute is anunsafe attribute. Annotating a function with#[unsafe(naked)] comes with the safety obligation that the body must respect the function’s calling convention, uphold its signature, and either return or diverge (i.e., not fall through past the end of the assembly code).

The assembly code may assume that the call stack and register state are valid on entry as per the signature and calling convention of the function.

The assembly code may not be duplicated by the compiler except when monomorphizing polymorphic functions.

Theunused_variables lint is suppressed within naked functions.

Theinline attribute cannot by applied to a naked function.

Thetrack_caller attribute cannot be applied to a naked function.

Thetesting attributes cannot be applied to a naked function.

Theno_builtins attribute

Theno_builtinsattribute disables optimization of certain code patterns related to calls to library functions that are assumed to exist.

Theno_builtins attribute uses theMetaWord syntax.

Theno_builtins attribute can only be applied to the crate root.

Only the first use of theno_builtins attribute has effect.

Thetarget_feature attribute

Thetarget_featureattribute may be applied to a function toenable code generation of that function for specific platform architecturefeatures. It uses theMetaListNameValueStr syntax with a single key ofenable whose value is a string of comma-separated feature names to enable.

#![allow(unused)]fn main() {#[cfg(target_feature = "avx2")]#[target_feature(enable = "avx2")]fn foo_avx2() {}}

Eachtarget architecture has a set of features that may be enabled. It is anerror to specify a feature for a target architecture that the crate is notbeing compiled for.

Closures defined within atarget_feature-annotated function inherit theattribute from the enclosing function.

It isundefined behavior to call a function that is compiled with a featurethat is not supported on the current platform the code is running on,exceptif the platform explicitly documents this to be safe.

The following restrictions apply unless otherwise specified by the platform rules below:

• Safe#[target_feature] functions (and closures that inherit the attribute) can only be safely called within a caller that enables all thetarget_features that the callee enables.This restriction does not apply in anunsafe context.
• Safe#[target_feature] functions (and closures that inherit the attribute) can only be coerced tosafe function pointers in contexts that enable all thetarget_features that the coercee enables.This restriction does not apply tounsafe function pointers.

Implicitly enabled features are included in this rule. For example ansse2 function can call ones marked withsse.

#![allow(unused)]fn main() {#[cfg(target_feature = "sse2")] {#[target_feature(enable = "sse")]fn foo_sse() {}fn bar() {    // Calling `foo_sse` here is unsafe, as we must ensure that SSE is    // available first, even if `sse` is enabled by default on the target    // platform or manually enabled as compiler flags.    unsafe {        foo_sse();    }}#[target_feature(enable = "sse")]fn bar_sse() {    // Calling `foo_sse` here is safe.    foo_sse();    || foo_sse();}#[target_feature(enable = "sse2")]fn bar_sse2() {    // Calling `foo_sse` here is safe because `sse2` implies `sse`.    foo_sse();}}}

A function with a#[target_feature] attributenever implements theFn family of traits, although closures inheriting features from the enclosing function do.

The#[target_feature] attribute is not allowed on the following places:

• themain function
• apanic_handler function
• safe trait methods
• safe default functions in traits

Functions marked withtarget_feature are not inlined into a context thatdoes not support the given features. The#[inline(always)] attribute may notbe used with atarget_feature attribute.

Available features

The following is a list of the available feature names.

x86 orx86_64

Executing code with unsupported features is undefined behavior on this platform.Hence on this platform usage of#[target_feature] functions follows theabove restrictions.

aarch64

On this platform the usage of#[target_feature] functions follows theabove restrictions.

Further documentation on these features can be found in theARM ArchitectureReference Manual, or elsewhere ondeveloper.arm.com.

loongarch

On this platform the usage of#[target_feature] functions follows theabove restrictions.

riscv32 orriscv64

On this platform the usage of#[target_feature] functions follows theabove restrictions.

Further documentation on these features can be found in their respectivespecification. Many specifications are described in theRISC-V ISA Manual orin another manual hosted on theRISC-V GitHub Account.

wasm32 orwasm64

Safe#[target_feature] functions may always be used in safe contexts on Wasmplatforms. It is impossible to cause undefined behavior via the#[target_feature] attribute because attempting to use instructionsunsupported by the Wasm engine will fail at load time without the risk of beinginterpreted in a way different from what the compiler expected.

Additional information

See thetarget_feature conditional compilation option for selectivelyenabling or disabling compilation of code based on compile-time settings. Notethat this option is not affected by thetarget_feature attribute, and isonly driven by the features enabled for the entire crate.

See theis_x86_feature_detected oris_aarch64_feature_detected macrosin the standard library for runtime feature detection on these platforms.

Thetrack_caller attribute

Thetrack_caller attribute may be applied to any function with"Rust" ABIwith the exception of the entry pointfn main.

When applied to functions and methods in trait declarations, the attribute applies to all implementations. If the trait provides adefault implementation with the attribute, then the attribute also applies to override implementations.

When applied to a function in anextern block the attribute must also be applied to any linkedimplementations, otherwise undefined behavior results. When applied to a function which is madeavailable to anextern block, the declaration in theextern block must also have the attribute,otherwise undefined behavior results.

Behavior

Applying the attribute to a functionf allows code withinf to get a hint of theLocation ofthe “topmost” tracked call that led tof’s invocation. At the point of observation, animplementation behaves as if it walks up the stack fromf’s frame to find the nearest frame of anunattributed functionouter, and it returns theLocation of the tracked call inouter.

#![allow(unused)]fn main() {#[track_caller]fn f() {    println!("{}", std::panic::Location::caller());}}

Examples

Whenf is called directly bycalls_f, code inf observes its callsite withincalls_f:

#![allow(unused)]fn main() {#[track_caller]fn f() {    println!("{}", std::panic::Location::caller());}fn calls_f() {    f(); // <-- f() prints this location}}

Whenf is called by another attributed functiong which is in turn called bycalls_g, code inbothf andg observesg’s callsite withincalls_g:

#![allow(unused)]fn main() {#[track_caller]fn f() {    println!("{}", std::panic::Location::caller());}#[track_caller]fn g() {    println!("{}", std::panic::Location::caller());    f();}fn calls_g() {    g(); // <-- g() prints this location twice, once itself and once from f()}}

Wheng is called by another attributed functionh which is in turn called bycalls_h, all codeinf,g, andh observesh’s callsite withincalls_h:

#![allow(unused)]fn main() {#[track_caller]fn f() {    println!("{}", std::panic::Location::caller());}#[track_caller]fn g() {    println!("{}", std::panic::Location::caller());    f();}#[track_caller]fn h() {    println!("{}", std::panic::Location::caller());    g();}fn calls_h() {    h(); // <-- prints this location three times, once itself, once from g(), once from f()}}

And so on.

Limitations

This information is a hint and implementations are not required to preserve it.

In particular, coercing a function with#[track_caller] to a function pointer creates a shim whichappears to observers to have been called at the attributed function’s definition site, losing actualcaller information across virtual calls. A common example of this coercion is the creation of atrait object whose methods are attributed.

Theinstruction_set attribute

Theinstruction_setattribute specifies the instruction set that a function will use during code generation. This allows mixing more than one instruction set in a single program.

Theinstruction_set attribute uses theMetaListPaths syntax to specify a single path consisting of the architecture family name and instruction set name.

Theinstruction_set attribute may only be applied to functions withbodies —closures,async blocks,free functions,associated functions in aninherent impl ortrait impl, and associated functions in atrait definition when those functions have adefault definition .

Theinstruction_set attribute may be used only once on a function.

Theinstruction_set attribute may only be used with a target that supports the given value.

When theinstruction_set attribute is used, any inline assembly in the function must use the specified instruction set instead of the target default.

instruction_set on ARM

When targeting theARMv4T andARMv5te architectures, the supported values forinstruction_set are:

• arm::a32 — Generate the function as A32 “ARM” code.
• arm::t32 — Generate the function as T32 “Thumb” code.

If the address of the function is taken as a function pointer, the low bit of the address will depend on the selected instruction set:

• Forarm::a32 (“ARM”), it will be 0.
• Forarm::t32 (“Thumb”), it will be 1.