代码生成属性

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

优化提示

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

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

inline 属性

inline 属性 建议在调用方放置一份被标记函数的副本，而不是生成调用函数定义位置的代码。

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

使用 inline 属性有三种方法

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

注意：#[inline] 的所有形式都是提示，语言对在调用方放置被标记函数的副本没有要求。

cold 属性

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

no_builtins 属性

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

target_feature 属性

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

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

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

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

标记为 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

#[target_feature] 可与 Wasm 平台上的安全函数和 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 除外。当应用于特征声明中的函数和方法时，该属性适用于所有实现。如果特征提供了具有该属性的默认实现，则该属性也适用于覆盖实现。

当应用于 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 似乎是在标记函数的定义位置调用的，从而在虚拟调用中丢失了实际的调用者信息。这种强制转换的一个常见示例是创建其方法已标记的特征对象。

注意：上述函数指针的 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）。
• 函数中的任何内联汇编都必须使用指定的指令集而不是目标默认指令集。