GraalVM Truffle DSL 编写指南：面向部分求值与 Native Image 的节点实现规范

本文是 GraalVM Truffle 语言实现框架（Truffle DSL）的实战指南，聚焦于 Truffle DSL 节点代码的编写规范与底层原理。文章以仓库内 truffle/docs/DSLGuidelines.md 为核心骨架，并结合 truffle/docs/DSLNodeObjectInlining.md、truffle/docs/DSLWarnings.md 及 DSL 注解处理器的真实源码，深入讲解如何写出既利于部分求值（PE）、又不会膨胀 Native Image 体积的高质量解释器节点代码。读完本文，你将掌握 Truffle DSL 节点编写的七条核心准则、内联节点（@GenerateInline）的完整迁移路径，以及如何利用 DSL 警告系统在编译期持续优化节点实现。

总则：PE 代码重复最小化与 Native Image 尺寸最小化

Truffle 语言解释器的节点代码有两条全局性的高层准则，其余具体规则几乎都由它们推导而来。

准则一：在部分求值（PE）过程中最小化代码重复。

PE 是 Truffle 运行时编译（guest compilation）的基础：编译期从 RootNode.execute(...) 出发，通过偏特化（partial evaluation）将解释器代码中与具体类型、常量相关的部分折叠为高效机器码。代码重复会让 PE 过程反复探索相同的调用路径，增加编译负担。与此同时，PE 还受到 主机编译（host compilation） 的影响：Truffle 的 host inlining 阶段会在 JIT（HotSpot）或 AOT（Native Image）编译解释器时，尽可能内联"运行时可编译"的代码路径，其遵循与 PE 相似的规则。因此，代码重复会同时伤害这两种编译路径。

准则二：解释器代码总量尽可能少，以最小化 Native Image 尺寸。

这条准则对运行时代码和 PE 代码都适用，但对 PE 代码更为关键，原因有三：

1. Native Image 会对 PE 代码进行 AOT 编译；
2. host inlining 会显著放大 AOT 编译产出的代码量；
3. Native Image 还必须为所有 PE 代码保留序列化的 Graal IR 图，供运行时编译使用。

需要强调的是，原文档明确指出：这些只是 guideline（准则），并非必须严格遵守的教条。真正重要的是理解每条准则背后的推理逻辑（reasoning），并据此在具体场景中权衡取舍。

避免为微小差异使用继承（Avoid subclassing for minor changes）

反例

假设有两个节点 Node1 和 Node2，它们继承了同一个基类 MyBaseNode，仅通过覆写 doOther 方法产生微小差异：

abstract class MyBaseNode extends Node {
  abstract int execute(Object o);

  @Specialization(guards = "arg == 0")
  int doZero(int arg) { /* ... */ }

  @Specialization(guards = "arg != 0")
  int doInt(int arg) { /* ... */ }

  @Specialization
  int doOther(Object o) { throw new AbstractMethodError(); }
}

abstract class Node1 extends MyBaseNode {
  @Specialization
  @Override
  final int doOther(Object o) { return 42; }
}

abstract class Node2 extends MyBaseNode {
  @Specialization
  @Override
  final int doOther(Object o) { return -1; }
}

为什么这是反模式：Native Image 二进制体积

Truffle DSL 注解处理器会为每个节点生成多个 execute 与 executeAndSpecialize 方法。由于 Node1 与 Node2 各自继承了 MyBaseNode 的全部特化逻辑，生成的方法中会包含大量相同的代码。而 Native Image 并不会对重复代码做去重，这些重复的机器码、IR 图都会被真实地写入二进制产物，直接推高体积。

解决方案一：用子节点委托（delegation）替代继承

把差异部分抽取为一个独立的 @Child 节点，由基类在 doOther 中委托调用：

abstract class MyNodeHandleOther extends Node {
    abstract int execute(Object o);
}

abstract class MyNode extends Node {
  @Child MyNodeHandleOther otherHandler;

  MyNode(MyNodeHandleOther otherHandler) {
      this.otherHandler = otherHandler;
  }

  abstract int execute(Object o);

  @Specialization(guards = "arg == 0")
  int doZero(int arg) { /* ... */ }

  @Specialization(guards = "arg != 0")
  int doInt(int arg) { /* ... */ }

  @Specialization
  int doOther(Object o) {
      return otherHandler.execute(o);
  }
}

解决方案二：公共特化下沉到内联节点

如果公共代码只有一个 @Specialization，或者存在一个简单高效的 guard 能覆盖所有公共特化，则把公共 @Specialization 移到内联节点中，原"子类"只保留一个委托特化：

@GenerateCached(false)
@GenerateInline
abstract class MyCommonNode extends Node {
  abstract int execute(Node node, Object o);

  @Specialization(guards = "arg == 0")
  int doZero(int arg) { /* ... */ }

  @Specialization(guards = "arg != 0")
  int doInt(int arg) { /* ... */ }
}

abstract class Node1 extends Node {
    abstract int execute(Object o);

    @Specialization
    int doInts(int o,
               @Cached MyCommonNode node) {
        return node.execute(this, o);
    }

    @Specialization
    int doOther(Object o) { return 42; }
}

// Node2 依此类推

@GenerateInline 是 Truffle 23.0 引入的注解，指示 DSL 生成节点的内联版本（详见后文"配套机制：Node Object Inlining"一节）；@GenerateCached(false) 则用于在只使用内联版本时关闭缓存版本生成，进一步节省 Java 代码体积。

避免重复的 Specialization（Avoid duplicated Specializations）

反例

不要编写方法体（几乎）相同的多个 @Specialization——包括那些只是"委托到同一个 helper 方法"的特化：

abstract class MyNode extends Node {
  abstract void execute(Object o);

  @Specialization
  void doObj1(MyObject1 o) { helper(o); }

  @Specialization
  void doObj2(MyObject2 o) { helper(o); }

  void helper(Object o) { /* some code */ }

  // ... 更多 @Specializations
}

为什么：PE 眼中的代码重复，而非开发者眼中的代码重复

这里要消除的是 PE 过程看到的重复，而不是开发者眼中的重复。把公共代码抽到 helper 方法并不会帮助 PE，因为 PE 会对每一个调用单独探索（explores every call separately）。

以 host inlining 为例，假设 Node#execute 被完全内联，其成本约为（省略部分细节）：

size(Node#execute) + size(Node#doIt1) + size(Node#doIt2) + 2 * size(Node#helper)

helper 被调用了两次，就要被展开两次——重复是真实存在的。

解决方案：合并特化 + 用内联节点承载被合并的条件

具体合并手法因场景而异，没有放之四海而皆准的方案。通用建议是：尝试合并包含代码重复的 @Specialization，并创建一个内联节点来 profile 原本由"多个特化"隐式 profile 的条件分支：

@GenerateInline
@GenerateCached(false)
abstract class GuardNode extends Node {
  abstract boolean execute(Node inliningTarget, Object o);

  @Specialization
  static boolean doObj1(MyObject1 o) { return true; }

  @Specialization
  static boolean doObj2(MyObject2 o) { return true; }

  @Fallback
  static boolean doFallback(Object o) { return false; }
}

abstract class MyNode extends Node {
  abstract void execute(Object o);

  @Specialization(guards = "guardNode.execute(this, o)", limit = "1")
  void doObj(Object o,
             @Cached GuardNode guardNode) { helper(o); }

  // ...其他 @Specializations
}

注意权衡：如果该 guard 需要被多个特化使用，或被生成的 fallback guard 复用，那么 guard 逻辑本身也会像特化内部逻辑一样被重复展开。guard 通常比较简单，这种重复往往可以接受，但需要开发者自行评估利弊。

避免对 helper 方法/节点的重复调用（Avoid duplicated calls to helper methods/nodes）

反例

@Specialization
void doDefault(boolean b, Object o) {
  if (b) {
    helper.execute(o, 42);
  } else {
    helper.execute(o, -1);
  }
}

为什么：PE 过程中的代码重复

PE 必须分别探索两个分支中的 helper.execute 调用，即使 Graal 编译器在后续阶段有可能做去重，代价也已经付出。

解决方案：尽量提取公共调用（common-out）

  int num = b ? 42 : -1;
  helper.execute(o, num);

将调用参数先统一计算，再执行一次调用，从源头消除重复展开。

不要混用 @Shared 与非 @Shared 的内联节点/Profile

反例

当 Truffle DSL 为 @Specialization 生成"数据类（data-class）"时，避免在同一个 @Specialization 中混用 @Shared 与普通的内联节点/profile：

@GenerateInline(false)
class MyNode extends Node {
  // ...
  @Specialization
  void doIt(...,
      @Bind("this") Node node,
      /* 更多 @Cached 参数，使得 DSL 生成 data-class */
      @Exclusive @Cached InlinedBranchProfile b1,
      @Shared @Cached InlinedBranchProfile b2)

为什么：解释器执行效率下降

以示例为例：非共享的内联 profile 的数据存放在生成的 data-class 对象中，而共享的内联 profile 的数据存放在 MyNode 实例中。但两个 profile 接收到的 node 参数都是 data-class 实例，于是共享 profile 必须调用 node.getParent() 才能访问存放在 MyNode 中的数据。一般地，这类内联节点/profile 可能需要沿着 parent 指针链多次遍历才能找到自己的数据，解释器热路径因此变慢。

适用范围说明：此规则不涉及任何非内联节点——非内联节点之间、以及它们与内联节点之间的混用是允许的。约束仅限于：同一个 @Specialization 中使用的内联节点，应当要么全部 @Shared，要么全部 @Exclusive。

解决方案

• 将 @Shared 节点/profile 改为 @Exclusive；
• 或重构代码使共享不再必要。注意：@Shared 的使用（不限于内联节点）往往正是 重复 @Specialization 的信号，重构特化即可根治；
• 如果共享带来的内存占用收益超过了可能的解释器性能损失，可以忽略本准则；
• 通用兜底方案：把代码拆成两个节点——外层节点只持有共享的内联节点/profile，内层节点只持有非共享的。外层节点可以执行公共逻辑，并把共享节点连同其 inlining target 节点一起转发给内层节点。这个方案牺牲少量代码可读性，换取解释器性能与内存占用两全。

避免未使用的大型内联节点（Avoid unused large inline nodes）

反例

不要内联只在罕见执行路径上使用的大型节点：

@Specialization
void doObject(Object arg,
    @Bind("this") Node inliningTarget,
    @Cached LargeInlineNode n) {

    if (arg == null) {
        // 罕见情况
        n.execute(inliningTarget, ...);
    }
}

为什么：运行时内存占用

LargeInlineNode 的所有字段都会被内联进调用方节点（或特化数据类），显著抬高其内存占用，而多数执行根本用不到这些字段。

解决方案

• 对解释器中不敏感的性能路径：改用惰性初始化节点模式（lazily initialized nodes with DSL inlining），只在条件真正触发时才实例化；
• 对解释器中性能敏感的热路径：
  • 内存增长如果被性能收益覆盖，可以接受；
  • 若适用，使用手写的惰性初始化 @Child 字段模式；
  • 尽可能重构代码，避免这种"为罕见路径内联大节点"的局面。

惰性初始化模式的具体实现（LazyRaiseNode 包装节点）可参考 NodeInliningAndLazyInitExample.java 与 truffle/docs/DSLNodeObjectInlining.md 中的完整示例，后文还会展开。

避免同时生成 cached、uncached、inline 三种变体

@GenerateCached、@GenerateUncached、@GenerateInline 分别让 DSL 生成节点的缓存、非缓存与内联版本。如果条件允许，应避免三种变体同时存在，因为这会直接扩大 PE 代码的总体占用（PE 代码的 footprint），与"最小化 Native Image 尺寸"的总则相悖。合理做法是：确定节点在实际使用中只需要哪种形态，然后通过 @GenerateCached(false) / @GenerateUncached(false) / @GenerateInline(false) 显式关闭其余变体。

配套机制：DSL 警告与注解处理器选项

上述准则并非只能靠人工记忆——Truffle DSL 注解处理器从 23.0 版本开始会产生大量针对性警告，用于引导开发者走向更好的 DSL 用法。理解这套警告系统，是落实全部准则的工程前提。

警告的抑制方式

方式	说明
-Atruffle.dsl.SuppressAllWarnings=true	javac 处理器选项，抑制 Truffle DSL 的全部警告
-Atruffle.dsl.SuppressWarnings=truffle-inlining,truffle-neverdefault	javac 处理器选项，按 key 抑制特定警告
@SuppressWarnings("truffle-inlining")	源码注解，按 key 抑制（与 Java 警告抑制方式一致）
@SuppressPackageWarnings	包级注解，抑制整个包的 Truffle DSL 警告
-J-Dtruffle.dsl.SuppressWarnings=...	通过 Java 系统属性配置注解处理器

关于 CI 的实践建议：如果语言项目在 CI 中启用了"警告即错误"的严格检查，建议在 Java 编译命令行中添加 -Atruffle.dsl.SuppressAllWarnings=true。原因在于：Truffle DSL 新增警告消息被视为兼容性变更，这会无预警地打破依赖新警告的 CI 检查。与此同时，应优先抑制特定警告而非全部警告（@SuppressWarnings("truffle-inlining") 优于 @SuppressWarnings("truffle")），以便保留其余警告的指导价值。

完整的警告 key 列表

原文档给出的 key 包括：

• all：Java 编译器或 Truffle DSL 发出的所有警告
• truffle：Truffle DSL 发出的所有警告
• truffle-sharing：DSL 建议在缓存值之间共享时发出
• truffle-inlining：DSL 建议使用节点对象内联时发出
• truffle-neverdefault：缓存初始化器应标记为"永远没有默认值"时发出
• truffle-limit：建议指定特化 limit 但未指定时发出
• truffle-static-method：DSL 建议使用 static 修饰符时发出
• truffle-unused：DSL 属性或注解无效、建议删除时发出
• truffle-abstract-export：Truffle library 的抽象消息未被导出时发出
• truffle-assumption：与到达 @Fallback 特化的特化一起使用 assumption 特性时发出
• truffle-guard：guard 使用了 @Idempotent 或 @NonIdempotent 方法可能对生成代码更有利的方法时发出

以上列表可以在处理器源码 TruffleSuppressedWarnings.java 中得到印证。从源码看，实际支持的 key 还包含 truffle-unexpected-result-rewrite、truffle-splitting、deprecation、truffle-interpreted-performance、truffle-force-cached、truffle-hide-builtin 等（见该文件中 ALL_KEYS 常量的定义）。

抑制机制的实现细节（来自源码分析）：TruffleSuppressedWarnings.isSuppressed 在判断一个元素是否被抑制时，会沿元素的封闭链向上遍历（e.getEnclosingElement()），只要方法、类或包中任意一级声明了匹配的 key 即视为被抑制。这意味着在类上写 @SuppressWarnings("truffle-inlining") 可以覆盖其全部特化方法，而包级注解可以覆盖整个包。

处理器选项与 mx 构建

从 TruffleProcessorOptions.java 的源码注释可以看到，在 mx 构建体系中传参的方式是：

mx build -A-Atruffle.dsl.SuppressAllWarnings=true

该文件还暴露了其他处理器选项（均以 truffle.dsl. 为前缀）：

• GenerateSpecializationStatistics：生成特化统计信息
• GenerateSlowPathOnly / GenerateSlowPathOnlyFilter：仅生成慢路径（及过滤器）
• CacheSharingWarningsEnabled：是否启用缓存共享警告（默认在未开启 slow path only 时启用）
• StateBitWidth：限制特化状态位宽（会与默认位宽取较小值）
• PrintTimings：打印注解处理器耗时
• AdditionalAssertions：生成额外断言

内联建议警告的典型形态

在节点对象内联场景中，DSL 会输出类似下面的警告，指引你添加 @GenerateInline(true)，这正是"避免重复 Specialization""避免未使用的大型内联节点"等准则落地时的自动助手：

This node is a candidate for node object inlining. The memory footprint is estimated to be reduced from 20 to 1 byte(s). Add @GenerateInline(true) to enable object inlining for this node or @GenerateInline(false) to disable this warning. Also, consider disabling cached node generation with @GenerateCached(false) if all usages will be inlined. This warning may be suppressed using @SuppressWarnings("truffle-inlining").

配套机制：Node Object Inlining 实战

@GenerateInline（23.0 引入）是落实多条准则的关键工具：它指示 DSL 生成节点的内联版本，工作方式与 @GenerateCached、@GenerateUncached 生成缓存/非缓存版本类似。默认情况下 DSL 不生成内联版本。节点内联是降低节点内存占用的简单手段，且常常同时提升解释器执行速度。完整的原理与 API 兼容性讨论见 truffle/docs/DSLNodeObjectInlining.md。

从零开始：一个带内联的求和节点

以"计算两个值绝对值和"的 AddAbsNode/AbsNode 为例。初始（无内联）版本：

public abstract class AddAbsNode extends Node {

    abstract long execute(Object left, Object right);

    @Specialization
    long add(long left, long right,
                    @Cached AbsNode leftAbs,
                    @Cached AbsNode rightAbs) {
        return leftAbs.execute(left) + rightAbs.execute(right);
    }
    // ...
}

public abstract class AbsNode extends Node {

    abstract long execute(long value);

    @Specialization(guards = "v >= 0")
    long doInt(long v) {
        return v;
    }

    @Specialization(guards = "v < 0")
    long doLong(long v) {
        return -v;
    }
}

执行一次后的压缩内存占用（按 Footprint = headerCount * 12 + pointerCount * 4 + primitiveByteSize 估算）：

AbsNodeGen = object header
   + Node field for Node.parent
   + int field for state

AddAbsNodeGen = object header
   + Node field for Node.parent
   + int  field for state
   + Node field for @Cached AbsNode leftAbs
   + Node field for @Cached AbsNode rightAbs

Footprint = 3 * 12 + 5 * 4 + 12 = 68 bytes

迁移第一步：让 AbsNode 可内联

按警告建议为 AbsNode 添加 @GenerateInline 后，DSL 会报编译错误，要求所有非 final 的 execute 方法把 Node 类型作为第一个参数：

Error generating code for @GenerateInline: Found non-final execute method without a node parameter execute(long). Inlinable nodes
 must use the Node type as the first parameter after the optional frame for all non-final execute methods. A valid signature for an
 inlinable node is execute([VirtualFrame frame, ] Node node, ...).

原因：内联节点变成单例，不再拥有自己的状态字段，状态改由 execute 参数传入。修正后（特化方法建议改为 static）：

@GenerateInline
public abstract class AbsNode extends Node {

    abstract long execute(Node node, long value);

    @Specialization(guards = "v >= 0")
    static long doInt(long v) {
        return v;
    }

    @Specialization(guards = "v < 0")
    static long doLong(long v) {
        return -v;
    }

}

注意：Node 参数对特化方法来说是可选的，但通常需要它来转发给被传递内联的子节点。

迁移第二步：调用方传入 this

AddAbsNode 需要在调用处传入 this：

public abstract static class AddAbsNode extends Node {

    abstract long execute(long left, long right);

    @Specialization
    long add(long left, long right,
                    @Cached AbsNode leftAbs,
                    @Cached AbsNode rightAbs) {
        return leftAbs.execute(this, left) + rightAbs.execute(this, right);
    }
    // ...
}

此时 DSL 会对每个 @Cached AbsNode 参数发出内联建议警告，按提示为缓存参数开启内联：

    @Specialization
    long add(long left, long right,
                    @Cached(inline = true) AbsNode leftAbs,
                    @Cached(inline = true) AbsNode rightAbs) {
        return leftAbs.execute(this, left) + rightAbs.execute(this, right);
    }

至此 AbsNode 已被内联进 AddAbsNode，占用降为：

AddAbsNodeGen = object header
   + Node field for Node.parent
   + int  field for state

Footprint = 1 * 12 + 1 * 4 + 4 = 20 bytes

即从 68 字节降到 20 字节。

迁移第三步：级联内联与 alwaysInlineCached

由于 AddAbsNode 的所有缓存节点都已内联，DSL 会建议 AddAbsNode 自身也可内联。继续为它添加 @GenerateInline 并改造 execute 签名。随后，在需要组合多层的场景中，可以用 @GenerateCached(alwaysInlineCached = true) 一次性为所有缓存节点开启内联，避免逐处书写 @Cached(inline=true)：

@GenerateCached(alwaysInlineCached = true)
public abstract static class Add4AbsNode extends Node {

    abstract long execute(long v0, long v1, long v2, long v3);

    @Specialization
    long doInt(long v0, long v1, long v2, long v3,
                    @Cached AddAbsNode add0,
                    @Cached AddAbsNode add1,
                    @Cached AddAbsNode add2) {
        long v;
        v = add0.execute(this, v0, v1);
        v = add1.execute(this, v, v2);
        v = add2.execute(this, v, v3);
        return v;
    }

}

状态位宽的估算规则

计算级联内联后的占用，需要理解每个节点需要多少"状态位（state bits）"来追踪激活的特化。这一计算与实现相关、可能变化，但经验法则是：DSL 为每个声明的特化需要 1 位；隐式类型转换（implicit casts）、replace 规则、@Fallback 以及多实例特化都可能进一步增加位需求。

本例中，每个 AddAbsNode 需要 5 位（两个 AbsNode 各 2 位 + AddAbsNode 自身特化 1 位）；Add4AbsNode 使用 3 个 AddAbsNode 实例并有 1 个特化，共需 3 * 5 + 1 = 16 位，低于 32，故生成代码只需一个 int 字段：

Footprint = 1 * 12 + 1 * 4 + 4 = 20 bytes

对比完全不做对象内联时的 Add4AbsNode：

Footprint = 1 * 12 + 4 * 4 + 4 + 3 * 68 = 236 bytes

内存占用从 236 字节降到 20 字节。除了内存收益，纯解释器执行也可能更快（省去节点字段读取、缓存局部性更好）；而经 PE 编译后，cached 与 uncached 版本预期性能一致。

收尾：关闭不再需要的变体

当 AbsNode/AddAbsNode 不再以缓存版本使用时，用 @GenerateCached(false) 关闭缓存版本生成以节省 Java 代码体积；关闭后 alwaysInlineCached 属性可省略（只有内联版本时节点会被自动内联）。最终形态：

@GenerateInline
@GenerateCached(false)
public abstract static class AbsNode extends Node {

    abstract long execute(Node node, long value);

    @Specialization(guards = "v >= 0")
    static long doInt(long v) {
        return v;
    }

    @Specialization(guards = "v < 0")
    static long doLong(long v) {
        return -v;
    }

}

@GenerateInline
@GenerateCached(false)
public abstract static class AddAbsNode extends Node {

    abstract long execute(Node node, long left, long right);

    @Specialization
    static long add(Node node, long left, long right,
                    @Cached AbsNode leftAbs,
                    @Cached AbsNode rightAbs) {
        return leftAbs.execute(node, left) + rightAbs.execute(node, right);
    }
    // ...
}

@GenerateCached(alwaysInlineCached = true)
@GenerateInline(false)
public abstract static class Add4AbsNode extends Node {

    abstract long execute(long v0, long v1, long v2, long v3);

    @Specialization
    long doInt(long v0, long v1, long v2, long v3,
                    @Cached AddAbsNode add0,
                    @Cached AddAbsNode add1,
                    @Cached AddAbsNode add2) {
        long v;
        v = add0.execute(this, v0, v1);
        v = add1.execute(this, v, v2);
        v = add2.execute(this, v, v3);
        return v;
    }
}

其中 Add4AbsNode 上显式写了 @GenerateInline(false) 来抑制 DSL 的继续内联建议——这说明显式关闭也是一种合法的、有意的选择。

这套示例的可运行版本可在 Truffle 单元测试中找到：NodeInliningExample1_1.java（无内联）、NodeInliningExample1_2.java（部分内联）、NodeInliningExample1_3.java（完全内联）。

多实例特化（Advanced Inline Cache）与正确传参

对于可能多实例的特化（inline cache），需要用 @Bind("this") Node node 绑定内联目标节点，并配合 limit、unroll 展开内联缓存。完整示例可参考 NodeInliningExample2_3.java，其测试通过 ObjectSizeEstimate 断言 SumArrayNode 执行后总占用为 20 字节（对比未内联时的 120 字节）。该例中的核心节点：

@ImportStatic(AbstractArray.class)
public abstract static class SumArrayNode extends Node {

    abstract int execute(Object v0);

    @Specialization(guards = {"kind != null", "kind.type == array.getClass()"}, limit = "2", unroll = 2)
    static int doDefault(Object array,
                    @Bind("this") Node node,
                    @Cached("resolve(array)") ArrayKind kind,
                    @Cached GetStoreNode getStore) {
        Object castStore = kind.type.cast(array);
        int[] store = getStore.execute(node, castStore);
        int sum = 0;
        for (int element : store) {
            sum += element;
            TruffleSafepoint.poll(node);
        }
        return sum;
    }

    static Class<?> getCachedClass(Object array) {
        if (array instanceof AbstractArray) {
            return array.getClass();
        }
        return null;
    }
}

传参的三个典型场景（这是最容易犯错的地方，DSL 会在编译期尽力拦截，但运行时仍可能出错）：

1. 内联节点链：对内联节点来说，把自己也用内联节点的场景下，只需沿 Node 动态参数一路传递即可（如上文的 leftAbs.execute(node, left)）。
2. 多实例缓存节点：必须用 @Bind("this") Node node 访问内联目标节点，典型如上述 SumArrayNode。
3. 导出的 library 消息：this 已被保留为接收者（receiver）值，此时改用 $node。例如：

    @ExportLibrary(ExampleArithmeticLibrary.class)
    static class ExampleNumber {

        final long value;

        /* ... */

        @ExportMessage
        final long abs(@Bind Node node,
                       @Cached InlinedConditionProfile profile) {
            if (profile.profile(node, this.value >= 0)) {
                return  this.value;
            } else {
                return  -this.value;
            }
        }

    }

内联节点的限制

节点对象内联支持任意深度的嵌套，但存在三条硬性限制：

• 节点类或父类上不得有实例字段；
• 节点不得使用 @NodeField 或 @NodeChild；
• 内联节点的使用不得递归。

手动实现可内联节点/Profile 与 API 兼容性

可内联的节点或 profile 也可以手动实现：类必须实现一个名为 inline 的静态方法。绝大多数可内联的 Truffle profile 使用自定义内联实现，可参考 InlinedBranchProfile.java 与 InlinedIntValueProfile.java。尽可能优先使用 DSL 生成的节点，手动实现需格外小心。

API 兼容性是内联节点的重要话题：TruffleString API 大量使用 DSL 节点。由于内联方法的签名取决于特化所需的状态位（state bits），对特化的任何改动都可能是 API 不兼容变更。为在稳定 API 边界上支持内联，建议手动声明一个转发到生成内联方法的 inline 方法，并用 @RequiredField(value = StateField.class, bits = 32) 预留位宽：

@GenerateInline
@GenerateUncached
@GeneratePackagePrivate
public abstract static class APINode extends Node {

    abstract long execute(Node node, long value);

    @Specialization(guards = "v >= 0")
    static long doInt(long v) {
        return v;
    }

    @Specialization(guards = "v < 0")
    static long doLong(long v) {
        return -v;
    }

    public static APINode inline(@RequiredField(value = StateField.class, bits = 32) InlineTarget target) {
        return APINodeGen.inline(target);
    }

    public static APINode create() {
        return APINodeGen.create();
    }

    public static APINode getUncached() {
        return APINodeGen.getUncached();
    }
}

@GeneratePackagePrivate 用于避免暴露任何生成的 public 代码。兼容性规则总结：

• 兼容变更：此前节点没有 inline 方法；或所需位空间减少且其余字段不变。
• 不兼容变更：向既有 inline 方法新增或移除 @RequiredField 注解；所需位宽增加。

若特化所需的位或字段超出预留容量，注解处理器会报错；少于预留容量则不会报错——这正是"跨稳定 API 边界使用节点内联"的安全基础。DSL 会校验 @RequiredField 与父节点状态规范是否匹配，不兼容时发出警告。对于引用类型的必需字段，生成签名可能因公共缓存子节点类型变化而不兼容，因此需要稳定内联 API 时，应优先手写 inline(InlineTarget) 方法，并把 ReferenceField 固定到稳定的公共父类型（如 Node.class）。

惰性初始化节点与内联

针对"只在罕见条件下使用的大节点"，DSL 内联还提供了优雅的惰性初始化方案。经典问题：RaiseErrorNode 总被实例化，但只有当 doSomeWork 返回 null 时才真正用到。旧做法是手写惰性 @Child 字段（需 CompilerDirectives.transferToInterpreterAndInvalidate() + insert(...)），缺点是特化无法 static 且无法生成 uncached 变体。新的做法是构造一个内联包装节点按需初始化目标节点：

@GenerateInline
@GenerateUncached
@GenerateCached(false)
public abstract static class LazyRaiseNode extends Node {
    public final RaiseErrorNode get(Node node) {
        return execute(node);
    }

    abstract RaiseErrorNode execute(Node node);

    @Specialization
    static RaiseErrorNode doIt(@Cached(inline = false) RaiseErrorNode node) {
        return node;
    }
}

@GenerateInline(false)
@GenerateUncached
public abstract static class LazyInitExample extends Node {
    abstract void execute(Object value);

    @Specialization
    void doIt(Object value,
              @Cached LazyRaiseNode raiseError) {
        Object result = doSomeWork(value);
        if (result == null) {
            raiseError.get(this).execute(value, "Error: doSomeWork returned null");
        }
    }
}

除非 LazyRaiseNode.execute 被调用，否则包装器的代价只是一个引用字段 + 父节点状态位中的 1 位，与惰性 @Child 字段方案相当。完整源码见 NodeInliningAndLazyInitExample.java。注意：目前该惰性初始化模式无法被 host inlining 完全内联，因此不建议用于解释器的热代码路径——这与 truffle/docs/DSLGuidelines.md 中"避免未使用的大型内联节点"一节的建议恰好互补。

小结：一份可落地的检查清单

把全部准则汇总为开发与评审时的自查清单：

1. 总则：始终追问"这段代码在 PE 中会被展开几次？"以及"它会让 Native Image 多出多少代码/IR 图？"；
2. 继承：仅为微小差异而继承节点时，改用 @Child 委托或内联公共节点；
3. 特化重复：方法体几乎相同的多个 @Specialization 应合并，用内联 guard 节点承载被合并的分支条件；
4. 调用重复：同一 helper 的多分支调用尽量提取公共参数、合并为单次调用；
5. 共享一致性：同一特化中的内联节点要么全 @Shared，要么全 @Exclusive，必要时拆分为内外两层节点；
6. 大节点内联：罕见路径上的大节点不要内联，改用惰性初始化包装；
7. 变体最小化：按实际使用情况用 @GenerateCached(false) / @GenerateUncached(false) / @GenerateInline(false) 关闭不需要的节点变体；
8. 善用警告：把 truffle-inlining、truffle-sharing 等 DSL 警告当作编译期导师，用 @SuppressWarnings 精确抑制而非全局关闭，并为 CI 配置好 -Atruffle.dsl.SuppressAllWarnings=true 兜底；
9. API 边界：跨稳定 API 边界使用内联时，手写 inline 方法并预留 @RequiredField 位宽。

这些准则的全部源码依据均可在本仓库中直接查阅：DSLGuidelines.md、DSLNodeObjectInlining.md、DSLWarnings.md、TruffleSuppressedWarnings.java、TruffleProcessorOptions.java，以及 truffle/src/com.oracle.truffle.api.dsl.test/ 下的系列内联示例测试。