代码生成属性

以下 属性 用于控制代码生成。

优化提示

cold 和 inline 属性 提供生成代码的建议，可能比没有这些提示时生成得更快。这些属性仅为提示，可能会被忽略。

这两个属性都可以用于 函数。当应用于 trait 中的函数时，它们仅在该函数用作 trait 实现的默认函数时生效，而不是应用于所有 trait 实现。这些属性对没有函数体的 trait 函数没有影响。

inline 属性

inline 属性 建议将带有该属性的函数副本放置在调用者处，而不是生成代码去调用函数定义位置的代码。

使用 inline 属性有三种方式

• #[inline] 建议 执行内联扩展。
• #[inline(always)] 建议 始终执行内联扩展。
• #[inline(never)] 建议 永远不要执行内联扩展。

cold 属性

cold 属性 建议带属性的函数不太可能被调用。

no_builtins 属性

no_builtins 属性 可以应用于 crate 级别，以禁用将某些代码模式优化为调用假定存在的库函数。

target_feature 属性

target_feature 属性 可应用于函数，以针对特定的平台架构特性启用该函数的代码生成。它使用 MetaListNameValueStr 语法，其中只有一个键 enable，其值是逗号分隔的要启用的特性名称字符串。

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

每个 目标架构 都有一组可以启用的特性。为 crate 未编译的目标架构指定特性是错误的。

在带有 target_feature 注解的函数中定义的闭包会继承包含函数的属性。

调用一个使用当前代码运行平台不支持的特性编译的函数是 未定义行为，除非 平台明确说明这是安全的。

除非下述平台规则另有规定，否则以下限制适用

• 安全的 #[target_feature] 函数（以及继承该属性的闭包）只能在启用了被调用方所有 target_feature 特性的调用方中安全地调用。此限制不适用于 unsafe 上下文。
• 安全的 #[target_feature] 函数（以及继承该属性的闭包）只能在启用了被强制转换方所有 target_feature 特性的上下文中被强制转换为 安全的 函数指针。此限制不适用于 unsafe 函数指针。

隐式启用的特性也包含在此规则中。例如，一个 sse2 函数可以调用标记有 sse 的函数。

#![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();
}
}
}

带有 #[target_feature] 属性的函数 永远不会 实现 Fn 系列 trait，尽管从包含函数继承特性的闭包会实现。

#[target_feature] 属性不允许用于以下位置

• main 函数
• panic_handler 函数
• 安全的 trait 方法
• trait 中安全的默认函数

标记有 target_feature 的函数不会被内联到不支持指定特性的上下文中。#[inline(always)] 属性不能与 target_feature 属性一起使用。

可用特性

以下是可用特性名称的列表。

x86 或 x86_64

在此平台上执行使用不支持特性编译的代码是未定义行为。因此，在此平台上使用 #[target_feature] 函数需遵循上述限制。

aarch64

在此平台上，#[target_feature] 函数的使用遵循上述限制。

有关这些特性的更多文档可在 ARM 架构参考手册 或 developer.arm.com 的其他位置找到。

riscv32 或 riscv64

在此平台上，#[target_feature] 函数的使用遵循上述限制。

这些特性的更多文档可在其各自的规范中找到。许多规范在 RISC-V ISA 手册 或托管在 RISC-V GitHub 账户 上的其他手册中描述。

wasm32 或 wasm64

在 Wasm 平台上，安全的 #[target_feature] 函数始终可以在安全上下文中使用。通过 #[target_feature] 属性导致未定义行为是不可能的，因为尝试使用 Wasm 引擎不支持的指令会在加载时失败，不会出现与编译器预期不同的解释风险。

附加信息

关于根据编译时设置选择性地启用或禁用代码编译，请参阅 target_feature 条件编译选项。请注意，此选项不受 target_feature 属性的影响，仅由整个 crate 启用的特性驱动。

对于这些平台上的运行时特性检测，请参阅标准库中的 is_x86_feature_detected 或 is_aarch64_feature_detected 宏。

track_caller 属性

除了入口点 fn main 外，track_caller 属性可以应用于任何具有 "Rust" ABI 的函数。

当应用于 trait 声明中的函数和方法时，该属性适用于所有实现。如果 trait 提供了带有该属性的默认实现，则该属性也适用于覆盖实现。

当应用于 extern 块中的函数时，该属性也必须应用于任何链接的实现，否则会导致未定义行为。当应用于可供 extern 块使用的函数时，extern 块中的声明也必须具有该属性，否则会导致未定义行为。

行为

将此属性应用于函数 f 允许 f 中的代码获取导致 f 被调用的“最顶层”被追踪调用的 Location 的提示。在观察点，实现的行为就像它从 f 的栈帧向上追溯，以找到最近的 未带属性 函数 outer 的栈帧，并返回 outer 中被追踪调用的 Location。

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

示例

当 f 直接由 calls_f 调用时，f 中的代码观察到其在 calls_f 中的调用点。

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

当 f 由另一个带有属性的函数 g 调用，而 g 又由 calls_g 调用时，f 和 g 中的代码都观察到 g 在 calls_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()
}
}

当 g 由另一个带有属性的函数 h 调用，而 h 又由 calls_h 调用时，f、g 和 h 中的所有代码都观察到 h 在 calls_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()
}
}

依此类推。

限制

此信息仅为提示，不要求实现保留它。

特别是，将带有 #[track_caller] 的函数强制转换为函数指针会创建一个垫片（shim），该垫片对于观察者来说看起来像是在带属性函数的定义处被调用，从而在虚拟调用中丢失了实际的调用方信息。这种强制转换的一个常见例子是创建其方法带有此属性的 trait 对象。

instruction_set 属性

instruction_set 属性 可以应用于函数，以控制该函数将为其生成哪个指令集。

这允许在支持它的 CPU 架构上，在单个程序中混合使用多种指令集。

它使用 MetaListPath 语法，以及由架构家族名称和指令集名称组成的路径。

在不支持 instruction_set 属性的目标上使用它是编译错误。

在 ARM 平台

对于 ARMv4T 和 ARMv5te 架构，支持以下内容

• arm::a32 — 将函数生成为 A32 “ARM” 代码。
• arm::t32 — 将函数生成为 T32 “Thumb” 代码。

#[instruction_set(arm::a32)]
fn foo_arm_code() {}

#[instruction_set(arm::t32)]
fn bar_thumb_code() {}

使用 instruction_set 属性具有以下效果

• 如果函数的地址被当作函数指针，地址的最低位将根据指令集设置为 0 (arm) 或 1 (thumb)。
• 函数中的任何内联汇编必须使用指定的指令集，而不是目标的默认指令集。