跳转到内容

std.zig.AstRlAnnotate

标准库Zig 0.17.1官方原文
源码std/zig/AstRlAnnotate.zig

第 1 行

AstRlAnnotate 是在 AstGen 之前遍历 AST 的简单处理遍,用于确定哪些表达式需要结果位置。

某些情况下,AstGen 可以选择提供结果指针,或仅使用块中的标准 break 指令。后者能够生成更高效的 ZIR 和运行期代码,但不允许发生 RLS。因此,我们希望仅在必要时提供真正的结果指针(来自分配)。

为此,需要确定哪些表达式需要结果指针。本处理遍负责分析所有可能提供结果位置的语法形式;如果子表达式以非简单方式使用该结果指针(例如通过字段指针写入),就将节点标记为需要结果位置。

字段

gpa: Allocator
arena: Allocator
tree: *const Ast
nodes_need_rl: RlNeededSet = .{}

满足以下条件的特定节点会被放入此集合:

  • if-else:任一分支消耗结果位置。
  • 带标签块:任意 break 消耗结果位置。
  • switch:任意分支消耗结果位置。
  • orelse/catch:右侧表达式消耗结果位置。
  • while/for:任意 break 消耗结果位置。
  • @as:第二个操作数消耗结果位置。
  • const:初始化表达式消耗结果位置。
  • return:返回表达式消耗结果位置。

std.zig.AstRlAnnotate.Allocator

别名

第 19 行

别名目标 std.mem.Allocator

std.zig.AstRlAnnotate.annotate

函数

第 64 行

pub fn annotate(gpa: Allocator, arena: Allocator, tree: Ast) Allocator.Error!RlNeededSet

参数

gpa: Allocator
arena: Allocator
tree: Ast

错误

OutOfMemory

std.zig.AstRlAnnotate.assert

别名

第 22 行

别名目标 std.debug.assert

std.zig.AstRlAnnotate.Ast

别名

第 18 行

别名目标 std.zig.Ast

std.zig.AstRlAnnotate.AstRlAnnotate

别名

第 17 行

别名目标 std.zig.AstRlAnnotate

std.zig.AstRlAnnotate.AutoHashMapUnmanaged

别名

第 20 行

别名目标 std.AutoHashMapUnmanaged

std.zig.AstRlAnnotate.Block

容器

第 56 行

带标签的块或循环。跳出此块时,若 break 表达式消耗了结果指针, 则应设置 consumes_res_ptr。

字段

parent: ?*Block
label: ?[]const u8
is_loop: bool
ri: ResultInfo
consumes_res_ptr: bool

std.zig.AstRlAnnotate.blockExpr

函数

第 769 行

fn blockExpr(astrl: *AstRlAnnotate, parent_block: ?*Block, ri: ResultInfo, node: Ast.Node.Index, statements: []const Ast.Node.Index) !bool

参数

astrl: *AstRlAnnotate
parent_block: ?*Block
ri: ResultInfo
node: Ast.Node.Index
statements: []const Ast.Node.Index

std.zig.AstRlAnnotate.builtinCall

函数

第 798 行

fn builtinCall(astrl: *AstRlAnnotate, block: ?*Block, ri: ResultInfo, node: Ast.Node.Index, args: []const Ast.Node.Index) !bool

参数

astrl: *AstRlAnnotate
block: ?*Block
ri: ResultInfo
node: Ast.Node.Index
args: []const Ast.Node.Index

std.zig.AstRlAnnotate.BuiltinFn

别名

第 21 行

别名目标 std.zig.BuiltinFn

std.zig.AstRlAnnotate.containerDecl

函数

第 89 行

fn containerDecl( astrl: *AstRlAnnotate, block: ?*Block, full: Ast.full.ContainerDecl, ) !void

参数

astrl: *AstRlAnnotate
block: ?*Block
full: Ast.full.ContainerDecl

std.zig.AstRlAnnotate.deinit

函数

第 85 行

fn deinit(astrl: *AstRlAnnotate, gpa: Allocator) void

参数

astrl: *AstRlAnnotate
gpa: Allocator

std.zig.AstRlAnnotate.expr

函数

第 130 行

若 rl 提供结果指针且表达式消费该指针,则返回 true。

fn expr(astrl: *AstRlAnnotate, node: Ast.Node.Index, block: ?*Block, ri: ResultInfo) Allocator.Error!bool

参数

astrl: *AstRlAnnotate
node: Ast.Node.Index
block: ?*Block
ri: ResultInfo

错误

OutOfMemory

std.zig.AstRlAnnotate.identString

函数

第 756 行

fn identString(astrl: *AstRlAnnotate, token: Ast.TokenIndex) ![]const u8

参数

astrl: *AstRlAnnotate
token: Ast.TokenIndex

std.zig.AstRlAnnotate.ResultInfo

容器

第 41 行

字段

have_type: bool

是否已知结果类型?

have_ptr: bool

是否可能具有结果指针?注意,由于它可能是推断分配, 其类型可能尚未知。

std.zig.AstRlAnnotate.ResultInfo.inferred_ptr

常量

第 50 行

ResultInfo

std.zig.AstRlAnnotate.ResultInfo.none

常量

第 48 行

ResultInfo

std.zig.AstRlAnnotate.ResultInfo.type_only

常量

第 51 行

ResultInfo

std.zig.AstRlAnnotate.ResultInfo.typed_ptr

常量

第 49 行

ResultInfo

std.zig.AstRlAnnotate.RlNeededSet

类型

第 39 行

std.zig.AstRlAnnotate.std

别名

第 16 行

别名目标 std

源码

std/zig/AstRlAnnotate.zig

//! AstRlAnnotate 是在 AstGen 之前遍历 AST 的简单处理遍,用于确定哪些表达式需要结果位置。
//!
//! 某些情况下,AstGen 可以选择提供结果指针,或仅使用块中的标准 `break` 指令。后者能够生成更高效的 ZIR 和运行期代码,但不允许发生 RLS。因此,我们希望仅在必要时提供真正的结果指针(来自分配)。
//!
//! 为此,需要确定哪些表达式需要结果指针。本处理遍负责分析所有可能提供结果位置的语法形式;如果子表达式以非简单方式使用该结果指针(例如通过字段指针写入),就将节点标记为需要结果位置。
//!
//!
//!
//!
//!
//!
//!
//!
//!

const std = @import("std");
const AstRlAnnotate = @This();
const Ast = std.zig.Ast;
const Allocator = std.mem.Allocator;
const AutoHashMapUnmanaged = std.AutoHashMapUnmanaged;
const BuiltinFn = std.zig.BuiltinFn;
const assert = std.debug.assert;

gpa: Allocator,
arena: Allocator,
tree: *const Ast,

/// 满足以下条件的特定节点会被放入此集合:
/// * if-else:任一分支消耗结果位置。
/// * 带标签块:任意 break 消耗结果位置。
/// * switch:任意分支消耗结果位置。
/// * orelse/catch:右侧表达式消耗结果位置。
/// * while/for:任意 break 消耗结果位置。
/// * @as:第二个操作数消耗结果位置。
/// * const:初始化表达式消耗结果位置。
/// * return:返回表达式消耗结果位置。
nodes_need_rl: RlNeededSet = .{},

pub const RlNeededSet = AutoHashMapUnmanaged(Ast.Node.Index, void);

const ResultInfo = packed struct {
    /// 是否已知结果类型?
    have_type: bool,
    /// 是否可能具有结果指针?注意,由于它可能是推断分配,
    /// 其类型可能尚未知。
    have_ptr: bool,

    const none: ResultInfo = .{ .have_type = false, .have_ptr = false };
    const typed_ptr: ResultInfo = .{ .have_type = true, .have_ptr = true };
    const inferred_ptr: ResultInfo = .{ .have_type = false, .have_ptr = true };
    const type_only: ResultInfo = .{ .have_type = true, .have_ptr = false };
};

/// 带标签的块或循环。跳出此块时,若 break 表达式消耗了结果指针,
/// 则应设置 `consumes_res_ptr`。
const Block = struct {
    parent: ?*Block,
    label: ?[]const u8,
    is_loop: bool,
    ri: ResultInfo,
    consumes_res_ptr: bool,
};

pub fn annotate(gpa: Allocator, arena: Allocator, tree: Ast) Allocator.Error!RlNeededSet {
    var astrl: AstRlAnnotate = .{
        .gpa = gpa,
        .arena = arena,
        .tree = &tree,
    };
    defer astrl.deinit(gpa);

    if (tree.errors.len != 0) {
        // 无法分析损坏的 AST。
        // 此时不会运行 AstGen。
        return .{};
    }

    for (tree.containerDeclRoot().ast.members) |member_node| {
        _ = try astrl.expr(member_node, null, ResultInfo.none);
    }

    return astrl.nodes_need_rl.move();
}

fn deinit(astrl: *AstRlAnnotate, gpa: Allocator) void {
    astrl.nodes_need_rl.deinit(gpa);
}

fn containerDecl(
    astrl: *AstRlAnnotate,
    block: ?*Block,
    full: Ast.full.ContainerDecl,
) !void {
    const tree = astrl.tree;
    switch (tree.tokenTag(full.ast.main_token)) {
        .keyword_struct => {
            if (full.ast.arg.unwrap()) |arg| {
                _ = try astrl.expr(arg, block, ResultInfo.type_only);
            }
            for (full.ast.members) |member_node| {
                _ = try astrl.expr(member_node, block, ResultInfo.none);
            }
        },
        .keyword_union => {
            if (full.ast.arg.unwrap()) |arg| {
                _ = try astrl.expr(arg, block, ResultInfo.type_only);
            }
            for (full.ast.members) |member_node| {
                _ = try astrl.expr(member_node, block, ResultInfo.none);
            }
        },
        .keyword_enum => {
            if (full.ast.arg.unwrap()) |arg| {
                _ = try astrl.expr(arg, block, ResultInfo.type_only);
            }
            for (full.ast.members) |member_node| {
                _ = try astrl.expr(member_node, block, ResultInfo.none);
            }
        },
        .keyword_opaque => {
            for (full.ast.members) |member_node| {
                _ = try astrl.expr(member_node, block, ResultInfo.none);
            }
        },
        else => unreachable,
    }
}

/// 若 `rl` 提供结果指针且表达式消费该指针,则返回 true。
fn expr(astrl: *AstRlAnnotate, node: Ast.Node.Index, block: ?*Block, ri: ResultInfo) Allocator.Error!bool {
    const tree = astrl.tree;
    switch (tree.nodeTag(node)) {
        .root,
        .switch_case_one,
        .switch_case_inline_one,
        .switch_case,
        .switch_case_inline,
        .switch_range,
        .for_range,
        .asm_output,
        .asm_input,
        => unreachable,

        .@"defer", .@"errdefer" => {
            _ = try astrl.expr(tree.nodeData(node).node, block, ResultInfo.none);
            return false;
        },

        .container_field_init,
        .container_field_align,
        .container_field,
        => {
            const full = tree.fullContainerField(node).?;
            const type_expr = full.ast.type_expr.unwrap().?;
            _ = try astrl.expr(type_expr, block, ResultInfo.type_only);
            if (full.ast.align_expr.unwrap()) |align_expr| {
                _ = try astrl.expr(align_expr, block, ResultInfo.type_only);
            }
            if (full.ast.value_expr.unwrap()) |value_expr| {
                _ = try astrl.expr(value_expr, block, ResultInfo.type_only);
            }
            return false;
        },
        .test_decl => {
            _ = try astrl.expr(tree.nodeData(node).opt_token_and_node[1], block, ResultInfo.none);
            return false;
        },
        .global_var_decl,
        .local_var_decl,
        .simple_var_decl,
        .aligned_var_decl,
        => {
            const full = tree.fullVarDecl(node).?;
            const init_ri = if (full.ast.type_node.unwrap()) |type_node| init_ri: {
                _ = try astrl.expr(type_node, block, ResultInfo.type_only);
                break :init_ri ResultInfo.typed_ptr;
            } else ResultInfo.inferred_ptr;
            const init_node = full.ast.init_node.unwrap() orelse {
                // 没有初始化节点,因此处理完成。
                return false;
            };
            switch (tree.tokenTag(full.ast.mut_token)) {
                .keyword_const => {
                    const init_consumes_rl = try astrl.expr(init_node, block, init_ri);
                    if (init_consumes_rl) {
                        try astrl.nodes_need_rl.putNoClobber(astrl.gpa, node, {});
                    }
                    return false;
                },
                .keyword_var => {
                    // 无论如何都会创建分配,
                    // 因此不关心结果指针是否被消耗。
                    _ = try astrl.expr(init_node, block, init_ri);
                    return false;
                },
                else => unreachable,
            }
        },
        .assign_destructure => {
            const full = tree.assignDestructure(node);
            for (full.ast.variables) |variable_node| {
                _ = try astrl.expr(variable_node, block, ResultInfo.none);
            }
            // 此处无需收集有意义的数据,因为解构始终使用 RLS
            _ = try astrl.expr(full.ast.value_expr, block, ResultInfo.none);
            return false;
        },
        .assign => {
            const lhs, const rhs = tree.nodeData(node).node_and_node;
            _ = try astrl.expr(lhs, block, ResultInfo.none);
            _ = try astrl.expr(rhs, block, ResultInfo.typed_ptr);
            return false;
        },
        .assign_shl,
        .assign_shl_sat,
        .assign_shr,
        .assign_bit_and,
        .assign_bit_or,
        .assign_bit_xor,
        .assign_div,
        .assign_sub,
        .assign_sub_wrap,
        .assign_sub_sat,
        .assign_mod,
        .assign_add,
        .assign_add_wrap,
        .assign_add_sat,
        .assign_mul,
        .assign_mul_wrap,
        .assign_mul_sat,
        => {
            const lhs, const rhs = tree.nodeData(node).node_and_node;
            _ = try astrl.expr(lhs, block, ResultInfo.none);
            _ = try astrl.expr(rhs, block, ResultInfo.none);
            return false;
        },
        .shl, .shr => {
            const lhs, const rhs = tree.nodeData(node).node_and_node;
            _ = try astrl.expr(lhs, block, ResultInfo.none);
            _ = try astrl.expr(rhs, block, ResultInfo.type_only);
            return false;
        },
        .add,
        .add_wrap,
        .add_sat,
        .sub,
        .sub_wrap,
        .sub_sat,
        .mul,
        .mul_wrap,
        .mul_sat,
        .div,
        .mod,
        .shl_sat,
        .bit_and,
        .bit_or,
        .bit_xor,
        .bang_equal,
        .equal_equal,
        .greater_than,
        .greater_or_equal,
        .less_than,
        .less_or_equal,
        .array_cat,
        => {
            const lhs, const rhs = tree.nodeData(node).node_and_node;
            _ = try astrl.expr(lhs, block, ResultInfo.none);
            _ = try astrl.expr(rhs, block, ResultInfo.none);
            return false;
        },

        .error_union, .merge_error_sets => {
            const lhs, const rhs = tree.nodeData(node).node_and_node;
            _ = try astrl.expr(lhs, block, ResultInfo.none);
            _ = try astrl.expr(rhs, block, ResultInfo.none);
            return false;
        },
        .bool_and,
        .bool_or,
        => {
            const lhs, const rhs = tree.nodeData(node).node_and_node;
            _ = try astrl.expr(lhs, block, ResultInfo.type_only);
            _ = try astrl.expr(rhs, block, ResultInfo.type_only);
            return false;
        },
        .bool_not => {
            _ = try astrl.expr(tree.nodeData(node).node, block, ResultInfo.type_only);
            return false;
        },
        .bit_not, .negation, .negation_wrap => {
            _ = try astrl.expr(tree.nodeData(node).node, block, ResultInfo.none);
            return false;
        },

        // 这些节点为叶节点,从不消耗结果位置。
        .identifier,
        .string_literal,
        .multiline_string_literal,
        .number_literal,
        .unreachable_literal,
        .asm_simple,
        .@"asm",
        .enum_literal,
        .error_value,
        .anyframe_literal,
        .@"continue",
        .char_literal,
        .error_set_decl,
        => return false,

        .builtin_call_two,
        .builtin_call_two_comma,
        .builtin_call,
        .builtin_call_comma,
        => {
            var buf: [2]Ast.Node.Index = undefined;
            const params = tree.builtinCallParams(&buf, node).?;
            return astrl.builtinCall(block, ri, node, params);
        },

        .call_one,
        .call_one_comma,
        .call,
        .call_comma,
        => {
            var buf: [1]Ast.Node.Index = undefined;
            const full = tree.fullCall(&buf, node).?;
            _ = try astrl.expr(full.ast.fn_expr, block, ResultInfo.none);
            for (full.ast.params) |param_node| {
                _ = try astrl.expr(param_node, block, ResultInfo.type_only);
            }
            return false; // TODO: 一旦向函数调用传递结果位置,此处将改变。
        },

        .@"return" => {
            if (tree.nodeData(node).opt_node.unwrap()) |lhs| {
                const ret_val_consumes_rl = try astrl.expr(lhs, block, ResultInfo.typed_ptr);
                if (ret_val_consumes_rl) {
                    try astrl.nodes_need_rl.putNoClobber(astrl.gpa, node, {});
                }
            }
            return false;
        },

        .field_access => {
            const lhs, _ = tree.nodeData(node).node_and_token;
            _ = try astrl.expr(lhs, block, ResultInfo.none);
            return false;
        },

        .if_simple, .@"if" => {
            const full = tree.fullIf(node).?;
            if (full.error_token != null or full.payload_token != null) {
                _ = try astrl.expr(full.ast.cond_expr, block, ResultInfo.none);
            } else {
                _ = try astrl.expr(full.ast.cond_expr, block, ResultInfo.type_only); // bool
            }

            if (full.ast.else_expr.unwrap()) |else_expr| {
                const then_uses_rl = try astrl.expr(full.ast.then_expr, block, ri);
                const else_uses_rl = try astrl.expr(else_expr, block, ri);
                const uses_rl = then_uses_rl or else_uses_rl;
                if (uses_rl) try astrl.nodes_need_rl.putNoClobber(astrl.gpa, node, {});
                return uses_rl;
            } else {
                _ = try astrl.expr(full.ast.then_expr, block, ResultInfo.none);
                return false;
            }
        },

        .while_simple, .while_cont, .@"while" => {
            const full = tree.fullWhile(node).?;
            const label: ?[]const u8 = if (full.label_token) |label_token| label: {
                break :label try astrl.identString(label_token);
            } else null;
            if (full.error_token != null or full.payload_token != null) {
                _ = try astrl.expr(full.ast.cond_expr, block, ResultInfo.none);
            } else {
                _ = try astrl.expr(full.ast.cond_expr, block, ResultInfo.type_only); // bool
            }
            var new_block: Block = .{
                .parent = block,
                .label = label,
                .is_loop = true,
                .ri = ri,
                .consumes_res_ptr = false,
            };
            if (full.ast.cont_expr.unwrap()) |cont_expr| {
                _ = try astrl.expr(cont_expr, &new_block, ResultInfo.none);
            }
            _ = try astrl.expr(full.ast.then_expr, &new_block, ResultInfo.none);
            const else_consumes_rl = if (full.ast.else_expr.unwrap()) |else_expr| else_rl: {
                break :else_rl try astrl.expr(else_expr, block, ri);
            } else false;
            if (new_block.consumes_res_ptr or else_consumes_rl) {
                try astrl.nodes_need_rl.putNoClobber(astrl.gpa, node, {});
                return true;
            } else {
                return false;
            }
        },

        .for_simple, .@"for" => {
            const full = tree.fullFor(node).?;
            const label: ?[]const u8 = if (full.label_token) |label_token| label: {
                break :label try astrl.identString(label_token);
            } else null;
            for (full.ast.inputs) |input| {
                if (tree.nodeTag(input) == .for_range) {
                    const lhs, const opt_rhs = tree.nodeData(input).node_and_opt_node;
                    _ = try astrl.expr(lhs, block, ResultInfo.type_only);
                    if (opt_rhs.unwrap()) |rhs| {
                        _ = try astrl.expr(rhs, block, ResultInfo.type_only);
                    }
                } else {
                    _ = try astrl.expr(input, block, ResultInfo.none);
                }
            }
            var new_block: Block = .{
                .parent = block,
                .label = label,
                .is_loop = true,
                .ri = ri,
                .consumes_res_ptr = false,
            };
            _ = try astrl.expr(full.ast.then_expr, &new_block, ResultInfo.none);
            const else_consumes_rl = if (full.ast.else_expr.unwrap()) |else_expr| else_rl: {
                break :else_rl try astrl.expr(else_expr, block, ri);
            } else false;
            if (new_block.consumes_res_ptr or else_consumes_rl) {
                try astrl.nodes_need_rl.putNoClobber(astrl.gpa, node, {});
                return true;
            } else {
                return false;
            }
        },

        .slice_open => {
            const sliced, const start = tree.nodeData(node).node_and_node;
            _ = try astrl.expr(sliced, block, ResultInfo.none);
            _ = try astrl.expr(start, block, ResultInfo.type_only);
            return false;
        },
        .slice => {
            const sliced, const extra_index = tree.nodeData(node).node_and_extra;
            const extra = tree.extraData(extra_index, Ast.Node.Slice);
            _ = try astrl.expr(sliced, block, ResultInfo.none);
            _ = try astrl.expr(extra.start, block, ResultInfo.type_only);
            _ = try astrl.expr(extra.end, block, ResultInfo.type_only);
            return false;
        },
        .slice_sentinel => {
            const sliced, const extra_index = tree.nodeData(node).node_and_extra;
            const extra = tree.extraData(extra_index, Ast.Node.SliceSentinel);
            _ = try astrl.expr(sliced, block, ResultInfo.none);
            _ = try astrl.expr(extra.start, block, ResultInfo.type_only);
            if (extra.end.unwrap()) |end| {
                _ = try astrl.expr(end, block, ResultInfo.type_only);
            }
            _ = try astrl.expr(extra.sentinel, block, ResultInfo.none);
            return false;
        },
        .deref => {
            _ = try astrl.expr(tree.nodeData(node).node, block, ResultInfo.none);
            return false;
        },
        .address_of => {
            _ = try astrl.expr(tree.nodeData(node).node, block, ResultInfo.none);
            return false;
        },
        .optional_type => {
            _ = try astrl.expr(tree.nodeData(node).node, block, ResultInfo.type_only);
            return false;
        },
        .@"try",
        .@"nosuspend",
        => return astrl.expr(tree.nodeData(node).node, block, ri),
        .grouped_expression,
        .unwrap_optional,
        => return astrl.expr(tree.nodeData(node).node_and_token[0], block, ri),

        .block_two,
        .block_two_semicolon,
        .block,
        .block_semicolon,
        => {
            var buf: [2]Ast.Node.Index = undefined;
            const statements = tree.blockStatements(&buf, node).?;
            return astrl.blockExpr(block, ri, node, statements);
        },
        .anyframe_type => {
            _, const child_type = tree.nodeData(node).token_and_node;
            _ = try astrl.expr(child_type, block, ResultInfo.type_only);
            return false;
        },
        .@"catch", .@"orelse" => {
            const lhs, const rhs = tree.nodeData(node).node_and_node;
            _ = try astrl.expr(lhs, block, ResultInfo.none);
            const rhs_consumes_rl = try astrl.expr(rhs, block, ri);
            if (rhs_consumes_rl) {
                try astrl.nodes_need_rl.putNoClobber(astrl.gpa, node, {});
            }
            return rhs_consumes_rl;
        },

        .ptr_type_aligned,
        .ptr_type_sentinel,
        .ptr_type,
        .ptr_type_bit_range,
        => {
            const full = tree.fullPtrType(node).?;
            _ = try astrl.expr(full.ast.child_type, block, ResultInfo.type_only);
            if (full.ast.sentinel.unwrap()) |sentinel| {
                _ = try astrl.expr(sentinel, block, ResultInfo.type_only);
            }
            if (full.ast.addrspace_node.unwrap()) |addrspace_node| {
                _ = try astrl.expr(addrspace_node, block, ResultInfo.type_only);
            }
            if (full.ast.align_node.unwrap()) |align_node| {
                _ = try astrl.expr(align_node, block, ResultInfo.type_only);
            }
            if (full.ast.bit_range_start.unwrap()) |bit_range_start| {
                const bit_range_end = full.ast.bit_range_end.unwrap().?;
                _ = try astrl.expr(bit_range_start, block, ResultInfo.type_only);
                _ = try astrl.expr(bit_range_end, block, ResultInfo.type_only);
            }
            return false;
        },

        .container_decl,
        .container_decl_trailing,
        .container_decl_arg,
        .container_decl_arg_trailing,
        .container_decl_two,
        .container_decl_two_trailing,
        .tagged_union,
        .tagged_union_trailing,
        .tagged_union_enum_tag,
        .tagged_union_enum_tag_trailing,
        .tagged_union_two,
        .tagged_union_two_trailing,
        => {
            var buf: [2]Ast.Node.Index = undefined;
            try astrl.containerDecl(block, tree.fullContainerDecl(&buf, node).?);
            return false;
        },

        .@"break" => {
            const opt_label, const opt_rhs = tree.nodeData(node).opt_token_and_opt_node;
            const rhs = opt_rhs.unwrap() orelse {
                // 返回 void 的 break 无需关注
                return false;
            };

            var opt_cur_block = block;
            if (opt_label.unwrap()) |label_token| {
                const break_label = try astrl.identString(label_token);
                while (opt_cur_block) |cur_block| : (opt_cur_block = cur_block.parent) {
                    const block_label = cur_block.label orelse continue;
                    if (std.mem.eql(u8, block_label, break_label)) break;
                }
            } else {
                // 没有标签——我们正在退出循环。
                while (opt_cur_block) |cur_block| : (opt_cur_block = cur_block.parent) {
                    if (cur_block.is_loop) break;
                }
            }

            if (opt_cur_block) |target_block| {
                const consumes_break_rl = try astrl.expr(rhs, block, target_block.ri);
                if (consumes_break_rl) target_block.consumes_res_ptr = true;
            } else {
                // 没有可供跳出的对应作用域——AstGen 将报告错误。
                _ = try astrl.expr(rhs, block, ResultInfo.none);
            }

            return false;
        },

        .array_type => {
            const lhs, const rhs = tree.nodeData(node).node_and_node;
            _ = try astrl.expr(lhs, block, ResultInfo.type_only);
            _ = try astrl.expr(rhs, block, ResultInfo.type_only);
            return false;
        },
        .array_type_sentinel => {
            const len_expr, const extra_index = tree.nodeData(node).node_and_extra;
            const extra = tree.extraData(extra_index, Ast.Node.ArrayTypeSentinel);
            _ = try astrl.expr(len_expr, block, ResultInfo.type_only);
            _ = try astrl.expr(extra.elem_type, block, ResultInfo.type_only);
            _ = try astrl.expr(extra.sentinel, block, ResultInfo.type_only);
            return false;
        },
        .array_access => {
            const lhs, const rhs = tree.nodeData(node).node_and_node;
            _ = try astrl.expr(lhs, block, ResultInfo.none);
            _ = try astrl.expr(rhs, block, ResultInfo.type_only);
            return false;
        },
        .@"comptime" => {
            // 若作用域已是编译期作用域,AstGen 会报错,因此可假定并非如此。
            // 这意味着不转发结果位置。
            _ = try astrl.expr(tree.nodeData(node).node, block, ResultInfo.none);
            return false;
        },
        .@"switch", .switch_comma => {
            const operand_node, const extra_index = tree.nodeData(node).node_and_extra;
            const case_nodes = tree.extraDataSlice(tree.extraData(extra_index, Ast.Node.SubRange), Ast.Node.Index);

            _ = try astrl.expr(operand_node, block, ResultInfo.none);

            var any_prong_consumed_rl = false;
            for (case_nodes) |case_node| {
                const case = tree.fullSwitchCase(case_node).?;
                for (case.ast.values) |item_node| {
                    if (tree.nodeTag(item_node) == .switch_range) {
                        const lhs, const rhs = tree.nodeData(item_node).node_and_node;
                        _ = try astrl.expr(lhs, block, ResultInfo.none);
                        _ = try astrl.expr(rhs, block, ResultInfo.none);
                    } else {
                        _ = try astrl.expr(item_node, block, ResultInfo.none);
                    }
                }
                if (try astrl.expr(case.ast.target_expr, block, ri)) {
                    any_prong_consumed_rl = true;
                }
            }
            if (any_prong_consumed_rl) {
                try astrl.nodes_need_rl.putNoClobber(astrl.gpa, node, {});
            }
            return any_prong_consumed_rl;
        },
        .@"suspend" => {
            _ = try astrl.expr(tree.nodeData(node).node, block, ResultInfo.none);
            return false;
        },
        .@"resume" => {
            _ = try astrl.expr(tree.nodeData(node).node, block, ResultInfo.none);
            return false;
        },

        .array_init_one,
        .array_init_one_comma,
        .array_init_dot_two,
        .array_init_dot_two_comma,
        .array_init_dot,
        .array_init_dot_comma,
        .array_init,
        .array_init_comma,
        => {
            var buf: [2]Ast.Node.Index = undefined;
            const full = tree.fullArrayInit(&buf, node).?;

            if (full.ast.type_expr.unwrap()) |type_expr| {
                // 显式指定类型的初始化不参与 RLS
                _ = try astrl.expr(type_expr, block, ResultInfo.none);
                for (full.ast.elements) |elem_init| {
                    _ = try astrl.expr(elem_init, block, ResultInfo.type_only);
                }
                return false;
            }

            if (ri.have_type) {
                // 始终转发类型信息
                // 若有结果指针,则使用并转发它
                for (full.ast.elements) |elem_init| {
                    _ = try astrl.expr(elem_init, block, ri);
                }
                return ri.have_ptr;
            } else {
                // 无类型初始化不消耗结果位置
                for (full.ast.elements) |elem_init| {
                    _ = try astrl.expr(elem_init, block, ResultInfo.none);
                }
                return false;
            }
        },

        .struct_init_one,
        .struct_init_one_comma,
        .struct_init_dot_two,
        .struct_init_dot_two_comma,
        .struct_init_dot,
        .struct_init_dot_comma,
        .struct_init,
        .struct_init_comma,
        => {
            var buf: [2]Ast.Node.Index = undefined;
            const full = tree.fullStructInit(&buf, node).?;

            if (full.ast.type_expr.unwrap()) |type_expr| {
                // 显式指定类型的初始化不参与 RLS
                _ = try astrl.expr(type_expr, block, ResultInfo.none);
                for (full.ast.fields) |field_init| {
                    _ = try astrl.expr(field_init, block, ResultInfo.type_only);
                }
                return false;
            }

            if (ri.have_type) {
                // 始终转发类型信息
                // 若有结果指针,则使用并转发它
                for (full.ast.fields) |field_init| {
                    _ = try astrl.expr(field_init, block, ri);
                }
                return ri.have_ptr;
            } else {
                // 无类型初始化不消耗结果位置
                for (full.ast.fields) |field_init| {
                    _ = try astrl.expr(field_init, block, ResultInfo.none);
                }
                return false;
            }
        },

        .fn_proto_simple,
        .fn_proto_multi,
        .fn_proto_one,
        .fn_proto,
        .fn_decl,
        => |tag| {
            var buf: [1]Ast.Node.Index = undefined;
            const full = tree.fullFnProto(&buf, node).?;
            const body_node = if (tag == .fn_decl) tree.nodeData(node).node_and_node[1].toOptional() else .none;
            {
                var it = full.iterate(tree);
                while (it.next()) |param| {
                    if (param.anytype_ellipsis3 == null) {
                        const type_expr = param.type_expr.?;
                        _ = try astrl.expr(type_expr, block, ResultInfo.type_only);
                    }
                }
            }
            if (full.ast.align_expr.unwrap()) |align_expr| {
                _ = try astrl.expr(align_expr, block, ResultInfo.type_only);
            }
            if (full.ast.addrspace_expr.unwrap()) |addrspace_expr| {
                _ = try astrl.expr(addrspace_expr, block, ResultInfo.type_only);
            }
            if (full.ast.section_expr.unwrap()) |section_expr| {
                _ = try astrl.expr(section_expr, block, ResultInfo.type_only);
            }
            if (full.ast.callconv_expr.unwrap()) |callconv_expr| {
                _ = try astrl.expr(callconv_expr, block, ResultInfo.type_only);
            }
            const return_type = full.ast.return_type.unwrap().?;
            _ = try astrl.expr(return_type, block, ResultInfo.type_only);
            if (body_node.unwrap()) |body| {
                _ = try astrl.expr(body, block, ResultInfo.none);
            }
            return false;
        },
    }
}

fn identString(astrl: *AstRlAnnotate, token: Ast.TokenIndex) ![]const u8 {
    const tree = astrl.tree;
    assert(tree.tokenTag(token) == .identifier);
    const ident_name = tree.tokenSlice(token);
    if (!std.mem.startsWith(u8, ident_name, "@")) {
        return ident_name;
    }
    return std.zig.string_literal.parseAlloc(astrl.arena, ident_name[1..]) catch |err| switch (err) {
        error.OutOfMemory => error.OutOfMemory,
        error.InvalidLiteral => "", // 对于无效 AST,此遍安全地返回无意义数据
    };
}

fn blockExpr(astrl: *AstRlAnnotate, parent_block: ?*Block, ri: ResultInfo, node: Ast.Node.Index, statements: []const Ast.Node.Index) !bool {
    const tree = astrl.tree;

    const lbrace = tree.nodeMainToken(node);
    if (tree.isTokenPrecededByTags(lbrace, &.{ .identifier, .colon })) {
        // 带标签的块
        var new_block: Block = .{
            .parent = parent_block,
            .label = try astrl.identString(lbrace - 2),
            .is_loop = false,
            .ri = ri,
            .consumes_res_ptr = false,
        };
        for (statements) |statement| {
            _ = try astrl.expr(statement, &new_block, ResultInfo.none);
        }
        if (new_block.consumes_res_ptr) {
            try astrl.nodes_need_rl.putNoClobber(astrl.gpa, node, {});
        }
        return new_block.consumes_res_ptr;
    } else {
        // 无标签块
        for (statements) |statement| {
            _ = try astrl.expr(statement, parent_block, ResultInfo.none);
        }
        return false;
    }
}

fn builtinCall(astrl: *AstRlAnnotate, block: ?*Block, ri: ResultInfo, node: Ast.Node.Index, args: []const Ast.Node.Index) !bool {
    _ = ri; // 目前,没有内置函数会消耗其结果位置。

    const tree = astrl.tree;
    const builtin_token = tree.nodeMainToken(node);
    const builtin_name = tree.tokenSlice(builtin_token);
    const info = BuiltinFn.list.get(builtin_name) orelse return false;
    if (info.param_count) |expected| {
        if (expected != args.len) return false;
    }
    switch (info.tag) {
        .import => return false,
        .branch_hint => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            return false;
        },
        .compile_log, .TypeOf => {
            for (args) |arg_node| {
                _ = try astrl.expr(arg_node, block, ResultInfo.none);
            }
            return false;
        },
        .as => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            return false;
        },
        .bit_cast => {
            _ = try astrl.expr(args[0], block, ResultInfo.none);
            return false;
        },
        .union_init => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            _ = try astrl.expr(args[2], block, ResultInfo.type_only);
            return false;
        },
        .min, .max => {
            for (args) |arg_node| {
                _ = try astrl.expr(arg_node, block, ResultInfo.none);
            }
            return false;
        },
        .@"export" => {
            _ = try astrl.expr(args[0], block, ResultInfo.none);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            return false;
        },
        .@"extern" => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            return false;
        },
        // 这些内置函数不接受参数,也不消耗结果指针。
        .src,
        .This,
        .EnumLiteral,
        .return_address,
        .error_return_trace,
        .frame,
        .breakpoint,
        .disable_instrumentation,
        .disable_intrinsics,
        .in_comptime,
        .panic,
        .trap,
        .c_va_start,
        => return false,
        // TODO: 这是针对 llvm/llvm-project#68409 的临时规避方案
        // Zig 跟踪问题:#16876
        .frame_address => return true,
        // 这些内置函数接受单个参数,其结果类型已知,
        // 但不会消费其结果指针。
        .sqrt,
        .sin,
        .cos,
        .tan,
        .exp,
        .exp2,
        .log,
        .log2,
        .log10,
        .floor,
        .ceil,
        .trunc,
        .round,
        .size_of,
        .bit_size_of,
        .align_of,
        .compile_error,
        .set_eval_branch_quota,
        .int_from_bool,
        .int_from_error,
        .error_from_int,
        .from_backing_int,
        .embed_file,
        .error_name,
        .set_runtime_safety,
        .Tuple,
        .wasm_memory_size,
        .splat,
        .set_float_mode,
        .type_info,
        .work_item_id,
        .work_group_size,
        .work_group_id,
        => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            return false;
        },
        // 这些内置函数接受单个不带结果信息的参数,
        // 并且不消耗其结果指针。
        .int_from_ptr,
        .int_from_enum,
        .abs,
        .tag_name,
        .type_name,
        .Frame,
        .int_from_float,
        .float_from_int,
        .ptr_from_int,
        .enum_from_int,
        .backing_int,
        .float_cast,
        .int_cast,
        .truncate,
        .error_cast,
        .ptr_cast,
        .align_cast,
        .addrspace_cast,
        .const_cast,
        .volatile_cast,
        .clz,
        .ctz,
        .pop_count,
        .byte_swap,
        .bit_reverse,
        => {
            _ = try astrl.expr(args[0], block, ResultInfo.none);
            return false;
        },
        .div_exact,
        .div_floor,
        .div_ceil,
        .div_trunc,
        .mod,
        .rem,
        => {
            _ = try astrl.expr(args[0], block, ResultInfo.none);
            _ = try astrl.expr(args[1], block, ResultInfo.none);
            return false;
        },
        .shl_exact, .shr_exact => {
            _ = try astrl.expr(args[0], block, ResultInfo.none);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            return false;
        },
        .bit_offset_of,
        .offset_of,
        .has_decl,
        .has_field,
        .field,
        .FieldType,
        => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            return false;
        },
        .field_parent_ptr => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.none);
            return false;
        },
        .wasm_memory_grow => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            return false;
        },
        .reduce => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.none);
            return false;
        },
        .add_with_overflow, .sub_with_overflow, .mul_with_overflow, .shl_with_overflow => {
            _ = try astrl.expr(args[0], block, ResultInfo.none);
            _ = try astrl.expr(args[1], block, ResultInfo.none);
            return false;
        },
        .atomic_load => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.none);
            _ = try astrl.expr(args[2], block, ResultInfo.type_only);
            return false;
        },
        .atomic_rmw => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.none);
            _ = try astrl.expr(args[2], block, ResultInfo.type_only);
            _ = try astrl.expr(args[3], block, ResultInfo.type_only);
            _ = try astrl.expr(args[4], block, ResultInfo.type_only);
            return false;
        },
        .atomic_store => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.none);
            _ = try astrl.expr(args[2], block, ResultInfo.type_only);
            _ = try astrl.expr(args[3], block, ResultInfo.type_only);
            return false;
        },
        .mul_add => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            _ = try astrl.expr(args[2], block, ResultInfo.type_only);
            return false;
        },
        .call => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.none);
            _ = try astrl.expr(args[2], block, ResultInfo.none);
            return false;
        },
        .memcpy, .memmove => {
            _ = try astrl.expr(args[0], block, ResultInfo.none);
            _ = try astrl.expr(args[1], block, ResultInfo.none);
            return false;
        },
        .memset => {
            _ = try astrl.expr(args[0], block, ResultInfo.none);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            return false;
        },
        .shuffle => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.none);
            _ = try astrl.expr(args[2], block, ResultInfo.none);
            _ = try astrl.expr(args[3], block, ResultInfo.none);
            return false;
        },
        .select => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.none);
            _ = try astrl.expr(args[2], block, ResultInfo.none);
            _ = try astrl.expr(args[3], block, ResultInfo.none);
            return false;
        },
        .Int => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            return false;
        },
        .Pointer => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            _ = try astrl.expr(args[2], block, ResultInfo.type_only);
            _ = try astrl.expr(args[3], block, ResultInfo.type_only);
            return false;
        },
        .Fn => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            _ = try astrl.expr(args[2], block, ResultInfo.type_only);
            _ = try astrl.expr(args[3], block, ResultInfo.type_only);
            return false;
        },
        .Struct => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            _ = try astrl.expr(args[2], block, ResultInfo.type_only);
            _ = try astrl.expr(args[3], block, ResultInfo.type_only);
            _ = try astrl.expr(args[4], block, ResultInfo.type_only);
            return false;
        },
        .Union => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            _ = try astrl.expr(args[2], block, ResultInfo.type_only);
            _ = try astrl.expr(args[3], block, ResultInfo.type_only);
            _ = try astrl.expr(args[4], block, ResultInfo.type_only);
            return false;
        },
        .Enum => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            _ = try astrl.expr(args[2], block, ResultInfo.type_only);
            _ = try astrl.expr(args[3], block, ResultInfo.type_only);
            return false;
        },
        .SpirvType => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            return false;
        },
        .Vector => {
            _ = try astrl.expr(args[0], block, ResultInfo.type_only);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            return false;
        },
        .prefetch => {
            _ = try astrl.expr(args[0], block, ResultInfo.none);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            return false;
        },
        .c_va_arg => {
            _ = try astrl.expr(args[0], block, ResultInfo.none);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            return false;
        },
        .c_va_copy => {
            _ = try astrl.expr(args[0], block, ResultInfo.none);
            return false;
        },
        .c_va_end => {
            _ = try astrl.expr(args[0], block, ResultInfo.none);
            return false;
        },
        .cmpxchg_strong, .cmpxchg_weak => {
            _ = try astrl.expr(args[0], block, ResultInfo.none);
            _ = try astrl.expr(args[1], block, ResultInfo.type_only);
            _ = try astrl.expr(args[2], block, ResultInfo.type_only);
            _ = try astrl.expr(args[3], block, ResultInfo.type_only);
            _ = try astrl.expr(args[4], block, ResultInfo.type_only);
            return false;
        },
    }
}