代码生成属性

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

优化提示

cold 和 inline 属性 给出一些编译建议，期望生成更快的代码。 但仅是提示，可能会被编译器忽略。

这两个属性可应用于 函数 。 当应用于 trait 中的函数时，仅适用于作为 trait 实现的默认函数，而不是所有 trait 实现。 这些属性对于没有函数体的 trait 函数没有效果。

inline 属性

• inline 属性* 建议将函数副本放置于调用者中，而不是在相应位置生成调用该函数的代码。

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

有三种使用 inline 属性的方式:

• #[inline] 建议 进行内联展开。
• #[inline(always)] 建议 总是进行内联展开。
• #[inline(never)] 建议 永远不进行内联展开。

注意: 无论形式如何， #[inline] 都仅是提示，对于是否将带有该属性的函数副本放置在调用者中，并不作 强制 。

cold 属性

cold 属性 表示带有该属性的函数不太可能被调用。

no_builtins 属性

no_builtins 属性 可以用于禁用优化特定的代码模式以调用预期存在的库函数。 该属性可以在 crate 级别应用。

target_feature 属性

target_feature 属性 可以应用于函数，以启用为特定平台架构特性生成该函数的代码。 它使用带有单个 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 当前将它们实现为一个特性。

wasm32 或 wasm64

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

附加信息

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 被另一个带有 track_caller 属性的函数 g 直接调用，而 g 又被 calls_g 调用时， f 和 g 中的代码都可以观察到 calls_g 中调用 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 被另一个有 track_caller 属性的函数 h 直接或间接调用时 (例如 h 被 calls_h 调用) ，则 f 、 g 和 h 中的代码都会观察到 calls_h 中 h 的调用位置。 也就是说，调用链中最深的有 track_caller 属性的函数的调用位置会传递到所有下层函数:

#![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] 的函数转换为函数指针会创建一个外壳函数，对于观察者来说，该外壳函数似乎是在函数定义的位置被调用的，从而在虚拟调用之间丢失了实际的调用者信息。 这种转换的常见例子是创建一个具有方法的 trait 对象，并将其进行标注。

注意: 函数指针的上述外壳函数是必要的，因为 rustc 在代码生成上实现 track_caller 通过将一个隐式参数附加到函数 ABI 上，但是这对于间接调用是非安全的， 因为该参数不是函数类型的一部分，给定的函数指针类型可能引用一个没有该属性的函数或具有该属性的函数。创建外壳函数隐藏了函数指针调用者的隐式参数，从而保持了安全性。

instruction_set 属性

可以将 instruction_set 属性应用于函数，以启用针对目标体系结构支持的特定指令集的代码生成。 它使用 MetaListPath 语法和一个由架构和指令集组成的路径，指定如何为在单个程序中使用多个指令集的体系结构生成代码。

对于 ARMv4 和 ARMv5te 架构的目标，以下值可用:

• arm::a32 - 使用 ARM 编码.
• arm::t32 - 使用 Thumb 编码.

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

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