Code generation - The Rust Reference
Keyboard shortcuts Press ← or → to navigate between chapters Press S or / to search in the book Press ? to show this help Press Esc to hide this help The Rust Reference [attributes .codegen] Code generation attributes [attributes .codegen .intro] The following attributes are used for controlling code generation. [attributes .codegen .inline] The inline attribute [attributes .codegen .inline .intro] The inline attribute suggests whether a copy of the attributed function’s code should be placed in the caller rather than generating a call to the function.
Example #![allow(unused)] fn main() { #[inline] pub fn example1() {} #[inline(always)] pub fn example2() {} #[inline(never)] pub fn example3() {} } Note rustc automatically inlines functions when doing so seems worthwhile. Use this attribute carefully as poor decisions about what to inline can slow down programs. [attributes .codegen .inline .syntax] The syntax for the inline attribute is: Syntax InlineAttribute → inline ( always ) | inline ( never ) | inline [attributes .codegen .inline .allowed-positions] The inline attribute may only be applied to functions with bodies — closures , async blocks , free functions , associated functions in an inherent impl or trait impl , and associated functions in a trait definition when those functions have a default definition .
Note rustc ignores use in other positions but lints against it. This may become an error in the future. Note Though the attribute can be applied to closures and async blocks , the usefulness of this is limited as we do not yet support attributes on expressions. #![allow(unused)] fn main() { // We allow attributes on statements. #[inline] || (); // OK #[inline] async {}; // OK } #![allow(unused)] fn main() { // We don't yet allow attributes on expressions. let f = #[inline] || (); // ERROR } [attributes .codegen .inline .duplicates] Only the first use of inline on a function has effect.
Note rustc lints against any use following the first. This may become an error in the future. [attributes .codegen .inline .modes] The inline 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. Note In every form the attribute is a hint. The compiler may ignore it. [attributes .codegen .inline .trait] When inline is applied to a function in a trait , it applies only to the code of the default definition . [attributes .codegen .inline .async] When inline is applied to an async function or async closure , it applies only to the code of the generated poll function.
Note For more details, see Rust issue #129347 . [attributes .codegen .inline .externally-exported] The inline attribute is ignored if the function is externally exported with no_mangle or export_name . [attributes .codegen .cold] The cold attribute [attributes .codegen .cold .intro] Tests Tests with this rule: tests/codegen-llvm/cold-attribute.rs The cold attribute suggests that the attributed function is unlikely to be called which may help the compiler produce better code.
Example #![allow(unused)] fn main() { #[cold] pub fn example() {} } [attributes .codegen .cold .syntax] The cold attribute uses the MetaWord syntax. [attributes .codegen .cold .allowed-positions] The cold attribute may only be applied to functions with bodies — closures , async blocks , free functions , associated functions in an inherent impl or trait impl , and associated functions in a trait definition when those functions have a default definition .
Note rustc ignores use in other positions but lints against it. This may become an error in the future. Note Though the attribute can be applied to closures and async blocks , the usefulness of this is limited as we do not yet support attributes on expressions. [attributes .codegen .cold .extern-custom] The cold attribute may not be applied to an extern "custom" function . #![allow(unused)] fn main() { #[cold] // ERROR: Not allowed. #[unsafe(naked)] unsafe extern "custom" fn f() { core::arch::naked_asm!("ret") } } [attributes .codegen .cold .duplicates] Only the first use of cold on a function has effect.
Note rustc lints against any use following the first. This may become an error in the future. [attributes .codegen .cold .trait] Tests Tests with this rule: tests/codegen-llvm/cold-attribute.rs When cold is applied to a function in a trait , it applies only to the code of the default definition . [attributes .codegen .naked] The naked attribute [attributes .codegen .naked .intro] The naked attribute prevents the compiler from emitting a function prologue and epilogue for the attributed function — a naked function .
Example #![allow(unused)] fn main() { #[cfg(target_arch = "x86_64")] { /// Adds 3 to the given number. // SAFETY: The body respects the "sysv64" calling convention, // upholds the signature, and does not fall through. #[unsafe(naked)] pub extern "sysv64" fn add_n(number: u64) -> u64 { core::arch::naked_asm!( "add rdi, {}", "mov rax, rdi", "ret", const 3, ) } } } Note The assembly code of a naked function often does not follow the calling convention of any ABI known to the compiler.
Such a function should be declared as an extern "custom" function . [attributes .codegen .naked .syntax] The naked attribute uses the MetaWord syntax. [attributes .codegen .naked .allowed-positions] The naked attribute may only be applied to free functions , associated functions in an inherent impl or trait impl , and associated functions in a trait definition when those functions have a default definition . [attributes .codegen .naked .duplicates] Only the first use of naked on a function has effect.
Note rustc lints against any use following the first. [attributes .codegen .naked .unsafe] The naked attribute must be marked with unsafe because 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). [attributes .codegen .naked .body] Tests Tests with this rule: tests/ui/asm/naked-functions/naked-functions.rs The function body must consist of exactly one naked_asm! macro invocation. [attributes .codegen .naked .prologue-epilogue] The compiler emits no prologue or epilogue for a naked function: the assembly code in the naked_asm! invocation constitutes its entire body. [attributes .codegen .naked .call-stack] On entry the assembly code may assume that the call stack and register state are valid per the function’s signature and calling convention. [attributes .codegen .naked .no-duplication] The compiler may not duplicate the assembly code except when monomorphizing a polymorphic function.
Note This guarantee matters for naked functions that define symbols. [attributes .codegen .naked .unused-variables] The unused_variables lint is suppressed in naked functions. [attributes .codegen .naked .inline] Tests Tests with this rule: tests/ui/asm/naked-functions/inline.rs The inline attribute cannot be applied to a naked function. [attributes .codegen .naked .track_caller] The track_caller attribute cannot be applied to a naked function. [attributes .codegen .naked .testing] Tests Tests with this rule: tests/ui/asm/naked-functions/testattrs.rs The testing attributes cannot be applied to a naked function. [attributes .codegen .naked .target_feature] The target_feature attribute cannot be applied to a naked function. [attributes .codegen .naked .abi] A naked function cannot use the “Rust” ABI . [attributes .codegen .no_builtins] The no_builtins attribute [attributes .codegen .no_builtins .intro] The no_builtins attribute disables optimization of certain code patterns related to calls to library functions that are assumed to exist.
Example #![allow(unused)] #![no_builtins] fn main() { } [attributes .codegen .no_builtins .syntax] The no_builtins attribute uses the MetaWord syntax. [attributes .cod
The rest of this page is on the live site.