代码生成属性

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

优化提示

cold 和 inline 属性 提供了生成代码的建议，这种方式可能比没有提示时更快。这些属性只是提示，可能会被忽略。

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

inline 属性

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

注意：rustc 编译器会根据内部启发式方法自动内联函数。不正确地内联函数可能会使程序变慢，因此应谨慎使用此属性。

有三种使用 inline 属性的方法

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

注意：#[inline] 的所有形式都是提示，语言对在调用者中放置带有属性的函数的副本没有*要求*。

cold 属性

cold 属性 建议不太可能调用具有该属性的函数。

no_builtins 属性

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

target_feature 属性

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

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

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

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

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

可用特性

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

x86 或 x86_64

在此平台上执行具有不支持的特性的代码是未定义行为。因此，此平台要求 #[target_feature] 仅应用于 unsafe 函数。

aarch64

此平台要求 #[target_feature] 仅应用于 unsafe 函数。

有关这些特性的更多文档，请参阅 ARM 架构参考手册，或 developer.arm.com 上的其他内容。

注意：如果使用以下特性对，则应将它们标记为一起启用或禁用

• paca 和 pacg，LLVM 当前将其实现为一个特性。

riscv32 或 riscv64

此平台要求 #[target_feature] 仅应用于 unsafe 函数。

有关这些特性的更多文档，请参阅各自的规范。许多规范在 RISC-V ISA 手册或 RISC-V GitHub 帐户上托管的另一份手册中进行了描述。

wasm32 或 wasm64

在 Wasm 平台上，#[target_feature] 可以与安全和unsafe 函数一起使用。不可能通过 #[target_feature] 属性导致未定义行为，因为尝试使用 Wasm 引擎不支持的指令将在加载时失败，而不会有以与编译器预期不同的方式解释的风险。

附加信息

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

请参阅标准库中的 is_x86_feature_detected 或 is_aarch64_feature_detected 宏，以在这些平台上进行运行时功能检测。

注意：rustc 为每个目标和 CPU 启用了一组默认功能。可以使用 -C target-cpu 标志选择 CPU。可以使用 -C target-feature 标志为整个 crate 启用或禁用单个功能。

track_caller 属性

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

当应用于 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());
}
}

注意：core 提供了 core::panic::Location::caller 来观察调用者位置。它包装了由 rustc 实现的 core::intrinsics::caller_location 内在函数。

注意：由于生成的 Location 是一个提示，因此实现可能会提前停止其在堆栈上的遍历。有关重要注意事项，请参阅限制。

示例

当 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，对于观察者而言，该 shim 似乎是在归属函数的定义站点调用的，从而丢失了跨越虚拟调用的实际调用者信息。这种强制转换的一个常见示例是创建其方法被归属的 trait 对象。

注意：上述函数指针的 shim 是必要的，因为 rustc 通过将隐式参数附加到函数 ABI 来在代码生成上下文中实现 track_caller，但这对于间接调用是不健全的，因为该参数不是函数类型的一部分，并且给定的函数指针类型可能引用也可能不引用具有该属性的函数。shim 的创建从函数指针的调用者隐藏了隐式参数，从而保留了健全性。

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)，具体取决于指令集。
• 函数中的任何内联汇编都必须使用指定的指令集，而不是目标默认值。