代码生成属性

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

inline 属性

*inline [属性]*建议是否应将属性函数代码的副本放置在调用者中，而不是生成对函数的调用。

inline 属性的语法是：

inline 属性只能应用于具有主体的函数 — 闭包、异步块、自由函数、固有实现或 trait 实现中的关联函数，以及当这些函数具有默认定义时 trait 定义中的关联函数。

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

inline 属性支持以下模式：

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

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

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

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

cold 属性

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

cold 属性使用 MetaWord 语法。

cold 属性只能应用于具有主体的函数 — 闭包、异步块、自由函数、固有实现或 trait 实现中的关联函数，以及当这些函数具有默认定义时 trait 定义中的关联函数。

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

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

naked 属性

*naked [属性]*阻止编译器为属性函数发出函数序言和尾声 — 裸函数。

naked 属性使用 MetaWord 语法。

naked 属性只能应用于自由函数、固有实现或 trait 实现中的关联函数，以及当这些函数具有默认定义时 trait 定义中的关联函数。

只有函数上的第一次使用 naked 才有效果。

naked 属性必须用 unsafe 标记，因为主体必须尊重函数的调用约定、维护其签名，并且要么返回要么发散（即不会穿透汇编代码末尾）。

函数主体必须恰好包含一个 naked_asm! 宏调用。

编译器不为裸函数发出序言或尾声：naked_asm! 调用中的汇编代码构成其整个主体。

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

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

unused_variables lint 在裸函数中被抑制。

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

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

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

[target_feature 属性]不能应用于裸函数。

裸函数不能使用 “Rust” ABI。

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() {
    // Calling `foo_sse` here is unsafe, as we must ensure that SSE is
    // available first, even if `sse` is enabled by default on the target
    // platform or manually enabled as compiler flags.
    unsafe {
        foo_sse();
    }
}

#[target_feature(enable = "sse")]
fn bar_sse() {
    // Calling `foo_sse` here is safe.
    foo_sse();
    || foo_sse();
}

#[target_feature(enable = "sse2")]
fn bar_sse2() {
    // Calling `foo_sse` here is safe because `sse2` implies `sse`.
    foo_sse();
}
}
}

具有 #[target_feature] 属性的函数从不实现 Fn 系列 trait，但从封闭函数继承功能的闭包除外。

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

• the main function
• panic_handler function
• 安全 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] 函数遵循上述限制。

有关这些功能的进一步文档可在各自的规范中找到。许多规范在 RISC-V ISA 手册、[版本 20250508] 或 [RISC-V GitHub 账户]上托管的其他手册中描述。

wasm32 或 wasm64

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

s390x

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

有关这些功能的进一步文档可在 z/Architecture Principles of Operation 第 1 章的“Additions to z/Architecture“部分找到。

附加信息

有关基于编译时设置选择性启用或禁用代码编译的信息，请参阅 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 中的调用位置：

#![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] 的函数强制转换为函数指针会创建一个垫片，在观察者看来就像在属性函数的定义位置被调用一样，在虚拟调用中丢失了实际的调用者信息。这种强制转换的常见示例是创建其方法被属性化的 trait 对象。

instruction_set 属性

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

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

instruction_set 属性只能应用于具有主体的函数 — 闭包、异步块、自由函数、固有实现或 trait 实现中的关联函数，以及当这些函数具有默认定义时 trait 定义中的关联函数。

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。