For now, this reference is a best-effort document. We strive for validity and completeness, but are not yet there. In the future, the docs and lang teams will work together to figure out how best to do this. Until then, this is a best-effort attempt. If you find something wrong or missing, file an issue or send in a pull request.

Code generation attributes

The following attributes are used for controlling code generation.

Optimization hints

The cold and inline attributes give suggestions to generate code in a way that may be faster than what it would do without the hint. The attributes are only hints, and may be ignored.

Both attributes can be used on functions. When applied to a function in a trait, they apply only to that function when used as a default function for a trait implementation and not to all trait implementations. The attributes have no effect on a trait function without a body.

The inline attribute

The inline attribute suggests that a copy of the attributed function should be placed in the caller, rather than generating code to call the function where it is defined.

Note: The rustc compiler automatically inlines functions based on internal heuristics. Incorrectly inlining functions can make the program slower, so this attribute should be used with care.

There are three ways to use the inline attribute:

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

The cold attribute

The cold attribute suggests that the attributed function is unlikely to be called.

The no_builtins attribute

The no_builtins attribute may be applied at the crate level to disable optimizing certain code patterns to invocations of library functions that are assumed to exist.

The target_feature attribute

The target_feature attribute may be applied to an unsafe function to enable code generation of that function for specific platform architecture features. It uses the MetaListNameValueStr syntax with a single key of enable whose value is a string of comma-separated feature names to enable.

#[target_feature(enable = "avx2")]
unsafe fn foo_avx2() {}

Each target architecture has a set of features that may be enabled. It is an error to specify a feature for a target architecture that the crate is not being compiled for.

It is undefined behavior to call a function that is compiled with a feature that is not supported on the current platform the code is running on.

Functions marked with target_feature are not inlined into a context that does not support the given features. The #[inline(always)] attribute may not be used with a target_feature attribute.

Available features

The following is a list of the available feature names.

x86 or x86_64
Feature Implicitly Enables Description
aes sse2 AES — Advanced Encryption Standard
avx sse4.2 AVX — Advanced Vector Extensions
avx2 avx AVX2 — Advanced Vector Extensions 2
bmi1 BMI1 — Bit Manipulation Instruction Sets
bmi2 BMI2 — Bit Manipulation Instruction Sets 2
fma avx FMA3 — Three-operand fused multiply-add
fxsr fxsave and fxrstor — Save and restore x87 FPU, MMX Technology, and SSE State
lzcnt lzcnt — Leading zeros count
pclmulqdq sse2 pclmulqdq — Packed carry-less multiplication quadword
popcnt popcnt — Count of bits set to 1
rdrand rdrand — Read random number
rdseed rdseed — Read random seed
sha sse2 SHA — Secure Hash Algorithm
sse SSE — Streaming SIMD Extensions
sse2 sse SSE2 — Streaming SIMD Extensions 2
sse3 sse2 SSE3 — Streaming SIMD Extensions 3
sse4.1 sse3 SSE4.1 — Streaming SIMD Extensions 4.1
sse4.2 sse4.1 SSE4.2 — Streaming SIMD Extensions 4.2
ssse3 sse3 SSSE3 — Supplemental Streaming SIMD Extensions 3
xsave xsave — Save processor extended states
xsavec xsavec — Save processor extended states with compaction
xsaveopt xsaveopt — Save processor extended states optimized
xsaves xsaves — Save processor extended states supervisor

Additional information

See the target_feature conditional compilation option for selectively enabling or disabling compilation of code based on compile-time settings. Note that this option is not affected by the target_feature attribute, and is only driven by the features enabled for the entire crate.

See the is_x86_feature_detected macro in the standard library for runtime feature detection on the x86 platforms.

Note: rustc has a default set of features enabled for each target and CPU. The CPU may be chosen with the -C target-cpu flag. Individual features may be enabled or disabled for an entire crate with the -C target-feature flag.