代码生成属性

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

inline 属性

inline 属性 建议是将带属性函数的代码副本放置在调用者中，还是生成对函数的调用。

inline 属性的语法如下：

inline 属性只能应用于具有函数体的函数 — 闭包、async 块、自由函数、固有 impl 或 trait impl 中的关联函数，以及具有默认定义时 trait 定义中的关联函数。

只有第一次在函数上使用 inline 才有效。

inline 属性支持以下模式：

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

当 inline 应用于 trait 中的函数时，它仅适用于默认定义的代码。

当 inline 应用于 async 函数 或 async 闭包 时，它仅适用于生成的 poll 函数的代码。

如果函数通过 no_mangle 或 export_name 外部导出，则 inline 属性被忽略。

cold 属性

cold 属性 建议带属性的函数不太可能被调用，这可能帮助编译器生成更好的代码。

cold 属性使用 MetaWord 语法。

cold 属性只能应用于具有函数体的函数。

只有第一次在函数上使用 cold 才有效。

当 cold 应用于 trait 中的函数时，它仅适用于默认定义的代码。

naked 属性

naked 属性 阻止编译器为带属性的函数生成函数序言和尾声。

函数体必须恰好由一个 naked_asm! 宏调用组成。

不会为带属性的函数生成函数序言或尾声。naked_asm! 块中的汇编代码构成裸函数的完整函数体。

naked 属性是一个 unsafe 属性。使用 #[unsafe(naked)] 标注函数附带的安全性义务是：函数体必须遵守函数的调用约定、履行其签名，并且要么返回要么发散（即不越过汇编代码的末尾而掉落）。

汇编代码可以假设在入口时调用栈和寄存器状态根据函数的签名和调用约定是有效的。

汇编代码不能被编译器复制，除非在单态化多态函数时。

unused_variables lint 在裸函数中被抑制。

inline 属性不能应用于裸函数。

track_caller 属性不能应用于裸函数。

测试属性不能应用于裸函数。

no_builtins 属性

no_builtins 属性 禁用与调用假定存在的库函数相关的某些代码模式的优化。

no_builtins 属性使用 MetaWord 语法。

no_builtins 属性只能应用于 crate 根。

只有第一次使用 no_builtins 属性才有效。

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() {
    // 在此处调用 `foo_sse` 是不安全的，因为我们必须首先确保 SSE 可用，
    // 即使目标平台默认启用了 `sse` 或作为编译器标志手动启用。
    unsafe {
        foo_sse();
    }
}

#[target_feature(enable = "sse")]
fn bar_sse() {
    // 在此处调用 `foo_sse` 是安全的。
    foo_sse();
    || foo_sse();
}

#[target_feature(enable = "sse2")]
fn bar_sse2() {
    // 在此处调用 `foo_sse` 是安全的，因为 `sse2` 隐含 `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 上找到。

loongarch

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

riscv32 或 riscv64

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

rest of RISC-V table kept same as English source

wasm32 或 wasm64

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

rest of wasm table kept same as English source

s390x

在 s390x 目标上，使用 #[target_feature] 属性的函数遵循上述限制。

rest of s390x table kept same as English source

附加信息

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

可以使用标准库中的平台特定宏在运行时检查特性是否启用，例如 is_x86_feature_detected 或 is_aarch64_feature_detected。

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

示例

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

当 f 被另一个带属性的函数 g 调用，而 g 又被 calls_g 调用时，f 和 g 中的代码观察到 g 在 calls_g 中的调用点。

限制

此信息是一个提示，实现不需要保留它。

特别地，将带有 #[track_caller] 的函数强制转换为函数指针会创建一个垫片，观察者看来它是在带属性的函数定义点被调用的，从而在虚调用中丢失实际的调用者信息。一个常见的强制转换示例是创建方法带有属性的 trait 对象。

instruction_set 属性

instruction_set 属性 指定函数在代码生成期间将使用的指令集。这允许在单个程序中混合多个指令集。

instruction_set 属性使用 MetaListPaths 语法来指定由架构族名称和指令集名称组成的单个路径。

instruction_set 属性只能应用于具有函数体的函数。

instruction_set 属性在一个函数上只能使用一次。

instruction_set 属性只能用于支持给定值的目标。

当使用 instruction_set 属性时，函数中的任何内联汇编必须使用指定的指令集而不是目标默认的指令集。

ARM 上的 instruction_set

当面向 ARMv4T 和 ARMv5te 架构时，instruction_set 的支持值为：

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

如果函数的地址被取为函数指针，地址的低位将取决于所选的指令集：

• 对于 arm::a32（“ARM”），将为 0。
• 对于 arm::t32（“Thumb”），将为 1。