04-代码生成

译文 · 基于 The Rust Reference

原文链接: https://doc.rust-lang.org/reference/attributes/codegen.html

r[attributes.codegen]

代码生成

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

r[attributes.codegen.inline]

inline 属性

r[attributes.codegen.inline.intro] *inline 属性*建议是否将被标注函数的代码副本放入调用者中，而不是生成对该函数的调用。

1
2
3
4
5
6
7
8

#[inline]
pub fn example1() {}

#[inline(always)]
pub fn example2() {}

#[inline(never)]
pub fn example3() {}

注意 rustc 在认为值得时会自动内联函数。请谨慎使用此属性，因为关于内联哪些函数的不当决策会拖慢程序。

r[attributes.codegen.inline.syntax] inline 属性的语法为：

@root InlineAttribute ->
      `inline` `(` `always` `)`
    | `inline` `(` `never` `)`
    | `inline`

r[attributes.codegen.inline.allowed-positions] inline 属性只能应用于带有函数体的函数——闭包、异步块、自由函数、固有 impl 或 trait impl 中的关联函数，以及 trait 定义 中带有默认定义的关联函数。

注意 rustc 会忽略其他位置上的使用，但会对其发出 lint。将来这可能变成错误。

注意 尽管该属性可以应用于闭包和异步块，但其用处有限，因为我们尚不支持在表达式上使用属性。

1 2 3

// 我们允许在语句上使用属性。 #[inline] || (); // OK #[inline] async {}; // OK

1 2	// 我们尚不允许在表达式上使用属性。 let f = #[inline] || (); // 错误

r[attributes.codegen.inline.duplicates] 对同一函数多次使用 inline 时，仅第一次生效。

注意 rustc 会对第一次之后的使用发出 lint。将来这可能变成错误。

r[attributes.codegen.inline.modes] inline 属性支持下列模式：

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

注意 无论何种形式，该属性都只是提示。编译器可以忽略它。

r[attributes.codegen.inline.trait] 当 inline 应用于 trait 中的函数时，它仅作用于默认定义的代码。

r[attributes.codegen.inline.async] 当 inline 应用于异步函数或异步闭包时，它仅作用于所生成 poll 函数的代码。

注意 更多细节见 Rust issue #129347。

r[attributes.codegen.inline.externally-exported] 若函数通过 no_mangle 或 export_name 对外导出，则忽略 inline 属性。

r[attributes.codegen.cold]

cold 属性

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

1
2

#[cold]
pub fn example() {}

r[attributes.codegen.cold.syntax] cold 属性使用 [MetaWord] 语法。

r[attributes.codegen.cold.allowed-positions] cold 属性只能应用于带有函数体的函数——闭包、异步块、自由函数、固有 impl 或 trait impl 中的关联函数，以及 trait 定义 中带有默认定义的关联函数。

注意 rustc 会忽略其他位置上的使用，但会对其发出 lint。将来这可能变成错误。

注意 尽管该属性可以应用于闭包和异步块，但其用处有限，因为我们尚不支持在表达式上使用属性。

r[attributes.codegen.cold.extern-custom] cold 属性不能应用于 extern "custom" 函数。

1
2
3
4
5

#[cold] // 错误：不允许。
#[unsafe(naked)]
unsafe extern "custom" fn f() {
    core::arch::naked_asm!("ret")
}

r[attributes.codegen.cold.duplicates] 对同一函数多次使用 cold 时，仅第一次生效。

注意 rustc 会对第一次之后的使用发出 lint。将来这可能变成错误。

r[attributes.codegen.cold.trait] 当 cold 应用于 trait 中的函数时，它仅作用于默认定义的代码。

r[attributes.codegen.naked]

naked 属性

r[attributes.codegen.naked.intro] naked 属性阻止编译器为被标注函数发出函数序言与尾声——即裸函数。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# #[cfg(target_arch = "x86_64")] {
/// 将给定数字加 3。
// 安全性：函数体遵守 "sysv64" 调用约定，
// 履行签名，并且不会落入。
#[unsafe(naked)]
pub extern "sysv64" fn add_n(number: u64) -> u64 {
    core::arch::naked_asm!(
        "add rdi, {}",
        "mov rax, rdi",
        "ret",
        const 3,
    )
}
# }

注意 裸函数的汇编代码通常不遵循编译器所知的任何 ABI 的调用约定。此类函数应声明为 [extern "custom" 函数][items.fn.extern.custom]。

r[attributes.codegen.naked.syntax] naked 属性使用 [MetaWord] 语法。

r[attributes.codegen.naked.allowed-positions] naked 属性只能应用于自由函数、固有 impl 或 trait impl 中的关联函数，以及 trait 定义 中带有默认定义的关联函数。

r[attributes.codegen.naked.duplicates] 对同一函数多次使用 naked 时，仅第一次生效。

注意 rustc 会对第一次之后的使用发出 lint。

r[attributes.codegen.naked.unsafe] naked 属性必须用 [unsafe][attributes.safety] 标记，因为函数体必须遵守该函数的调用约定、履行其签名，并且要么返回要么发散（即不得落入汇编代码末尾之后）。

r[attributes.codegen.naked.body] 函数体必须恰好由一次 naked_asm! 宏调用构成。

r[attributes.codegen.naked.prologue-epilogue] 编译器不为裸函数发出序言或尾声：naked_asm! 调用中的汇编代码构成其全部函数体。

r[attributes.codegen.naked.call-stack] 进入时，汇编代码可以假定调用栈与寄存器状态按该函数的签名和调用约定是有效的。

r[attributes.codegen.naked.no-duplication] 除在单态化多态函数时外，编译器不得复制该汇编代码。

注意 该保证对于定义符号的裸函数很重要。

r[attributes.codegen.naked.unused-variables] 裸函数中会抑制 unused_variables lint。

r[attributes.codegen.naked.inline] inline 属性不能应用于裸函数。

r[attributes.codegen.naked.track_caller] track_caller 属性不能应用于裸函数。

r[attributes.codegen.naked.testing] 测试属性不能应用于裸函数。

r[attributes.codegen.naked.target_feature] target_feature 属性不能应用于裸函数。

r[attributes.codegen.naked.abi] 裸函数不能使用 “Rust” ABI。

r[attributes.codegen.no_builtins]

no_builtins 属性

r[attributes.codegen.no_builtins.intro] *no_builtins 属性*禁用与假定存在的库函数调用相关的某些代码模式优化。

1

#![no_builtins]

r[attributes.codegen.no_builtins.syntax] no_builtins 属性使用 [MetaWord] 语法。

r[attributes.codegen.no_builtins.allowed-positions] no_builtins 属性只能应用于 crate 根。

r[attributes.codegen.no_builtins.duplicates] 多次使用 no_builtins 属性时，仅第一次生效。

注意 rustc 会对第一次之后的使用发出 lint。

r[attributes.codegen.target_feature]

target_feature 属性

r[attributes.codegen.target_feature.intro] *target_feature 属性*可应用于函数，以便为该函数针对特定平台架构特性生成代码。它使用 [MetaListNameValueStr] 语法，仅含一个键 enable，其值为以逗号分隔的、要启用的特性名称字符串。

1
2
3

## #[cfg(target_feature = "avx2")]
#[target_feature(enable = "avx2")]
fn foo_avx2() {}

r[attributes.codegen.target_feature.arch] 每个目标架构都有一组可启用的特性。为 crate 当前未作为编译目标的架构指定特性是错误的。

r[attributes.codegen.target_feature.closures] 在标注了 target_feature 的函数内定义的闭包会从外围函数继承该属性。

r[attributes.codegen.target_feature.target-ub] 调用以当前运行平台不支持的特性编译的函数是未定义行为，除非该平台明确将其记载为安全。

r[attributes.codegen.target_feature.safety-restrictions] 除非下文平台规则另有规定，否则适用下列限制：

• 安全的 #[target_feature] 函数（以及继承该属性的闭包）只能在启用了被调用者所启用的全部 target_feature 的调用者内被安全调用。 该限制不适用于 unsafe 上下文。
• 安全的 #[target_feature] 函数（以及继承该属性的闭包）只能在启用了被强制转换者所启用的全部 target_feature 的上下文中，被强制转换为安全函数指针。 该限制不适用于 unsafe 函数指针。

隐式启用的特性也包含在此规则中。例如，带 sse2 的函数可以调用标注了 sse 的函数。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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

r[attributes.codegen.target_feature.fn-traits] 带有 #[target_feature] 属性的函数永不实现 Fn 系列 trait，不过从外围函数继承特性的闭包会实现。

r[attributes.codegen.target_feature.allowed-positions] #[target_feature] 属性不允许用于下列位置：

• [main 函数][crate.main]
• [panic_handler 函数][panic.panic_handler]
• 安全的 trait 方法
• trait 中的安全默认函数

r[attributes.codegen.target_feature.inline] 标注了 target_feature 的函数不会被内联到不支持给定特性的上下文中。#[inline(always)] 属性不得与 target_feature 属性一起使用。

r[attributes.codegen.target_feature.availability]

可用特性

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

r[attributes.codegen.target_feature.cfg-only] 本列表中标记为 “(cfg only)” 的目标特性名称只能与 [target_feature][cfg.target_feature] 条件编译选项一起使用，不能与 target_feature 属性一起使用。

r[attributes.codegen.target_feature.x86]

x86 或 x86_64

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

r[attributes.codegen.target_feature.aarch64]

aarch64

在此平台上，#[target_feature] 函数的使用遵循[上述限制][attributes.codegen.target_feature.safety-restrictions]。

这些特性的更多文档见 ARM Architecture Reference Manual，或 developer.arm.com 上的其他资料。

注意 若使用下列特性对，应同时标记为启用或禁用：

• paca 与 pacg，LLVM 目前将二者实现为同一特性。

r[attributes.codegen.target_feature.loongarch]

loongarch

在此平台上，#[target_feature] 函数的使用遵循[上述限制][attributes.codegen.target_feature.safety-restrictions]。

r[attributes.codegen.target_feature.riscv]

riscv32 或 riscv64

在此平台上，#[target_feature] 函数的使用遵循[上述限制][attributes.codegen.target_feature.safety-restrictions]。

这些特性的更多文档见其各自的规范。许多规范记载于 RISC-V ISA Manual、version 20250508，或托管在 RISC-V GitHub Account 上的其他手册中。

r[attributes.codegen.target_feature.wasm]

wasm32 或 wasm64

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

r[attributes.codegen.target_feature.s390x]

s390x

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

这些特性的更多文档见 z/Architecture Principles of Operation 第 1 章的 “Additions to z/Architecture” 一节。

r[attributes.codegen.target_feature.info]

补充信息

r[attributes.codegen.target_feature.remark-cfg] 关于根据编译期设置有选择地启用或禁用代码编译，参见 target_feature 条件编译选项。注意该选项不受 target_feature 属性影响，仅由为整个 crate 启用的特性驱动。

r[attributes.codegen.target_feature.remark-rt] 可在运行时使用标准库中的平台特定宏检查某特性是否启用，例如 is_x86_feature_detected 或 is_aarch64_feature_detected。

注意 rustc 为每个目标和 CPU 启用一组默认特性。可用 -C target-cpu 标志选择 CPU。可用 -C target-feature 标志为整个 crate 启用或禁用个别特性。

r[attributes.codegen.track_caller]

track_caller 属性

r[attributes.codegen.track_caller.allowed-positions] track_caller 属性可应用于任何使用 "Rust" ABI 的函数，入口点 fn main 除外。

r[attributes.codegen.track_caller.traits] 应用于 trait 声明中的函数和方法时，该属性适用于所有实现。若 trait 提供带有该属性的默认实现，则该属性也适用于覆盖实现。

r[attributes.codegen.track_caller.extern] 应用于 extern 块中的函数时，该属性也必须应用于任何被链接的实现，否则会导致未定义行为。应用于提供给 extern 块使用的函数时，extern 块中的声明也必须带有该属性，否则会导致未定义行为。

r[attributes.codegen.track_caller.behavior]

行为

将该属性应用于函数 f，使 f 内的代码能够获得导致 f 被调用的“最顶层”被跟踪调用的 Location 提示。在观察点，实现的行为如同从 f 的栈帧向上遍历，找到最近的未标注函数 outer 的栈帧，并返回 outer 中被跟踪调用的 Location。

1
2
3
4

#[track_caller]
fn f() {
    println!("{}", std::panic::Location::caller());
}

注意 core 提供 [core::panic::Location::caller] 以观察调用者位置。它封装了由 rustc 实现的 [core::intrinsics::caller_location] 编译器内建函数（intrinsic）。

注意 由于所得 Location 只是提示，实现可以提前停止向上遍历栈。重要注意事项见限制。

示例

当 f 由 calls_f 直接调用时，f 中的代码观察到其在 calls_f 内的调用点：

1
2
3
4
5
6
7

## #[track_caller]
## fn f() {
##     println!("{}", std::panic::Location::caller());
## }
fn calls_f() {
    f(); // <-- f() 会打印此位置
}

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

## #[track_caller]
## fn f() {
##     println!("{}", std::panic::Location::caller());
## }
#[track_caller]
fn g() {
    println!("{}", std::panic::Location::caller());
    f();
}

fn calls_g() {
    g(); // <-- g() 会将此位置打印两次，一次来自自身，一次来自 f()
}

当 g 由另一个带该属性的函数 h 调用，而 h 又由 calls_h 调用时，f、g 和 h 中的代码都观察到 h 在 calls_h 内的调用点：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

## #[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(); // <-- 会将此位置打印三次，一次来自自身，一次来自 g()，一次来自 f()
}

以此类推。

r[attributes.codegen.track_caller.limits]

限制

r[attributes.codegen.track_caller.hint] 该信息只是提示，实现不必保留它。

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

注意 上述函数指针垫片是必要的，因为 rustc 在代码生成上下文中通过向函数 ABI 追加一个隐式参数来实现 track_caller，但这对于间接调用将是不健全的，因为该参数不是函数类型的一部分，且给定的函数指针类型可能指向带有或不带有该属性的函数。创建垫片可对函数指针的调用者隐藏该隐式参数，从而保持健全性。

r[attributes.codegen.instruction_set]

instruction_set 属性

r[attributes.codegen.instruction_set.intro] *instruction_set 属性*指定函数在代码生成期间将使用的指令集。这允许在同一程序中混合使用多种指令集。

1
2
3
4
5

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

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

r[attributes.codegen.instruction_set.syntax] instruction_set 属性使用 [MetaListPaths] 语法指定由架构族名称与指令集名称组成的单一路径。

r[attributes.codegen.instruction_set.allowed-positions] instruction_set 属性只能应用于带有函数体的函数——闭包、异步块、自由函数、固有 impl 或 trait impl 中的关联函数，以及 trait 定义 中带有默认定义的关联函数。

注意 rustc 会忽略其他位置上的使用，但会对其发出 lint。将来这可能变成错误。

注意 尽管该属性可以应用于闭包和异步块，但其用处有限，因为我们尚不支持在表达式上使用属性。

r[attributes.codegen.instruction_set.duplicates] instruction_set 属性在同一函数上只能使用一次。

r[attributes.codegen.instruction_set.target-limits] instruction_set 属性只能用于支持给定值的目标。

r[attributes.codegen.instruction_set.inline-asm] 使用 instruction_set 属性时，函数中的任何内联汇编都必须使用指定的指令集，而不是目标默认指令集。

r[attributes.codegen.instruction_set.arm]

ARM 上的 instruction_set

以 ARMv4T 和 ARMv5te 架构为目标时，instruction_set 支持的值为：

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

若将该函数的地址取为函数指针，则地址的最低位取决于所选指令集：

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