代码生成属性

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

inline属性

inline 属性 建议是将所修饰函数代码的副本放置在调用者中，而不是生成对函数的调用。

inline 属性的 语法格式 如下：

inline 属性只能应用于带有 函数体 的函数——闭包、异步块、自由函数、固有实现 或 特型实现 中的 关联函数，以及 特型定义 中带有 默认定义 的关联函数。

inline 在函数上的首次使用才生效。

inline 属性支持以下模式：

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

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

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

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

cold属性

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

cold 属性使用 MetaWord 语法格式。

cold 属性只能应用于带有 函数体 的函数——闭包、异步块、自由函数、固有实现 或 特型实现 中的 关联函数，以及 特型定义 中带有 默认定义 的关联函数。

cold 在函数上的首次使用才生效。

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

naked属性

naked 属性 阻止编译器为所修饰的函数发出函数序言和函数尾声。

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

不会为所修饰的函数生成函数序言或函数尾声。naked_asm! 块中的汇编代码构成了裸函数的完整函数体。

naked 属性是一个 不安全 属性。使用 #[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 特型 家族，尽管从封闭函数继承 特性 的闭包会实现。

#[target_feature] 属性不允许在以下位置使用：

• 主函数
• 恐慌处理器函数
• 安全的 特型 方法
• 特型 中安全的默认函数

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

可用的特性

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

x86或x86_64

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

aarch64

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

有关这些 特性 的更多文档可以在 ARM Architecture Reference Manual 或 developer.arm.com 上的其他位置找到。

loongarch

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

riscv32或riscv64

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

有关这些 特性 的更多文档可以在它们各自的规范中找到。许多规范在 RISC-V ISA Manual，version 20250508，或 RISC-V GitHub Account 上的另一本手册中描述。

wasm32或wasm64

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

s390x

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

有关这些 特性 的更多文档可以在 z/Architecture Principles of Operation 的第 1 章“对 z/Architecture 的补充”部分中找到。

附加信息

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

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

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

示例

当 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 在观察者看来是在所修饰函数的定义点被调用，从而在虚拟调用中丢失实际的调用者信息。这种强制转换的一个常见示例是创建其方法带有属性 的 特型 对象。

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。