GraalVM Truffle Bytecode DSL 短路操作指南：用 @ShortCircuitOperation 实现 &&、|| 与真值合并语义

短路径求值（short-circuit evaluation）是几乎所有脚本语言与表达式语言的基础语义：Java 的 &&、Python 的 or、JS 的 ?? 都在满足某个条件时提前终止后续操作数的求值。在 GraalVM Truffle 的 Bytecode DSL 中，这一能力由 @ShortCircuitOperation 注解提供——它允许你在自动生成的字节码解释器中声明一条"短路指令"，只需给出操作名、AND/OR 运算符和可选的布尔转换器，生成器便会自动编排操作数的逐一求值、提前退出与结果产生逻辑。读完本文，你将掌握 @ShortCircuitOperation 的全部四个运算符语义（返回原值 / 返回转换值）、布尔转换器（booleanConverter）的三种声明方式与约束，并能参照 SimpleLanguage 的真实用法为自己的语言实现 &&、||、空值合并等短路操作。

一、背景：为什么需要短路操作

Bytecode DSL 中普通的操作（operation）是贪心（eager）求值的：指令执行时，所有子操作（操作数）都会先被完整求值，然后才轮到操作本身执行。这种模型无法直接表达短路语义——例如 Java 的 a && b，当 a 为 false 时，b 根本不应该被求值（包括其中的副作用、抛出的异常等）。

许多语言都定义了这种"只求值部分操作数、遇到特定条件提前终止"的运算符。为此，Bytecode DSL 提供了 @ShortCircuitOperation 注解（位于 com.oracle.truffle.api.bytecode 包），用于声明短路操作。一个短路操作实现 AND 或 OR 语义：OR 逐个执行子操作直到遇到第一个 true，AND 逐个执行子操作直到遇到第一个 false。

短路操作是 Bytecode DSL 众多特性（快速化 quickening、装箱消除、序列化、插桩等，参见 Bytecode DSL 简介）中的一环，它在生成器中会被编译为真正的字节码指令，因此每个操作数都可以通过指令间的控制流实现"按需求值"。

二、@ShortCircuitOperation 注解全解（源码级）

从源码 ShortCircuitOperation.java 可以看到，该注解（@since 24.2）是 SOURCE 保留期、作用在类（ElementType.TYPE）上，并且是 @Repeatable 的——也就是说一个根节点类可以同时声明多个不同的短路操作，只要名字不冲突即可：

@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
@Repeatable(Repeat.class)
public @interface ShortCircuitOperation {
    String name();

    enum Operator { AND_RETURN_VALUE, AND_RETURN_CONVERTED, OR_RETURN_VALUE, OR_RETURN_CONVERTED }

    Operator operator();

    Class<?> booleanConverter() default void.class;

    String javadoc() default "";
}

各属性含义如下：

属性	说明
name	操作名，必填。生成器会据此在 Builder 中生成 beginXxx / endXxx 方法对（例如 name = "BoolOr" 会产生 beginBoolOr() / endBoolOr()）。
operator	必填，取自 ShortCircuitOperation.Operator 枚举。它同时决定两件事：使用 AND 还是 OR 语义，以及最终产生原始操作数值还是转换后的 boolean 值。
booleanConverter	可选（默认 void.class）。一个节点（Node）或操作（Operation）类，用于把每个操作数值强制转换（coerce）为 boolean 后再参与真假判断。不提供时，操作数本身必须已经是 boolean。
javadoc	可选，为生成的解释器提供操作文档说明。

Operator 枚举的四种取值定义了全部语义组合：

运算符	终止条件	产生的结果
AND_RETURN_VALUE	直到某个操作数转成 false	返回最后一个被求值的操作数的原始值
AND_RETURN_CONVERTED	直到某个操作数转成 false	返回最后一个操作数转换后的 boolean 值
OR_RETURN_VALUE	直到某个操作数转成 true	返回最后一个被求值的操作数的原始值
OR_RETURN_CONVERTED	直到某个操作数转成 true	返回最后一个操作数转换后的 boolean 值

注解的 Javadoc 还指出一个实用的代数性质：通过 De Morgan 变换可以在 AND 与 OR 之间互相转化（!convert(A) || !convert(B) || ... 等价于 !(convert(A) && convert(B) && ...)），所以改变 operator 并反转结果即可复用同一套转换逻辑。

三、基本示例：定义一个返回原值的 BoolOr

在不提供 booleanConverter 的情况下，短路操作的每个操作数都必须是 boolean，以便与 false/true 直接比较。下面在根节点类上用 @ShortCircuitOperation 声明一个简单的短路操作 BoolOr：

@GenerateBytecode(...)
@ShortCircuitOperation(
    name = "BoolOr",
    operator = ShortCircuitOperation.Operator.OR_RETURN_VALUE
)
public abstract class MyBytecodeRootNode extends RootNode implements BytecodeRootNode { ... }

BoolOr 使用 OR_RETURN_VALUE 运算符：按顺序执行操作数，直到遇到第一个 true，然后把这个 true 原值作为结果返回。用伪代码表示其语义：

if (boolean) child_1.execute() == true:
    return true

if (boolean) child_2.execute() == true:
    return true

# ... more children

return child_n.execute()

这里有几个重要的行为细节（源码注释与测试均有印证）：

• 每个操作数被强制转换为 boolean 进行比较。因此，如果某个操作数不是 boolean，会在比较时抛出 ClassCastException；如果操作数为 null，则抛出 NullPointerException。
• 最后一个操作数不会与 true/false 比较，因此也不做强制转换。这意味着即使最后一个操作数不是 boolean（例如整数 0），短路操作也会原样返回它，不会抛异常。正如测试注释所写："The last operand is not checked, since it is not used in a comparison."
• 保证最后一个操作数产出 boolean（或在消费它的操作中妥善处理非 boolean 结果）是语言实现方的责任——生成器不会替你检查。

四、布尔转换器：自定义"真值"与"假值"语义

有时操作数本就不是 boolean，或者语言有自己的真值（truthy / falsy）定义。例如 Python 的 or 运算符返回第一个"非假值"操作数：0、""、None 视为假值，42、"hello" 视为真值。这时可以给 @ShortCircuitOperation 提供 booleanConverter，用它把每个操作数强制转换为 boolean 后再做比较，而返回结果时仍可保留原始值。

4.1 模拟 Python 的 or：FalsyCoalesce

假设项目中已经存在一个把任意值转换为 boolean 的 CoerceToBoolean 操作。用它声明一个 FalsyCoalesce 操作，即可模拟 Python 的 or——返回第一个"非假值"操作数：

@GenerateBytecode(...)
@ShortCircuitOperation(
    name = "FalsyCoalesce",
    operator = ShortCircuitOperation.Operator.OR_RETURN_VALUE,
    booleanConverter = CoerceToBoolean.class
)
public abstract class MyBytecodeRootNode extends RootNode implements BytecodeRootNode { ... }

该声明表示：FalsyCoalesce 按顺序执行子操作，产生第一个能转换为 true 的操作数。伪代码如下：

value_1 = child_1.execute()
if CoerceToBoolean(value_1) == true:
    return value_1

value_2 = child_2.execute()
if CoerceToBoolean(value_2) == true:
    return value_2

# ... more children

return child_n.execute()

注意 FalsyCoalesce 返回的是原始操作数值（value_1、value_2……），而不是转换后的 boolean——这正是 OR_RETURN_VALUE 与 OR_RETURN_CONVERTED 的区别。同理，AND 家族也有 AND_RETURN_VALUE 与 AND_RETURN_CONVERTED 两种返回语义。

4.2 返回转换后的 boolean：CoerceAnd

如果希望短路操作产出转换后的 boolean 值（例如 Java 风格、类型固定的 && 结果），应使用 _RETURN_CONVERTED 变体。下面用 CoerceToBoolean 转换操作数并返回转换值的 CoerceAnd：

@GenerateBytecode(...)
@ShortCircuitOperation(
    name = "CoerceAnd",
    operator = ShortCircuitOperation.Operator.AND_RETURN_CONVERTED,
    booleanConverter = CoerceToBoolean.class
)
public abstract class MyBytecodeRootNode extends RootNode implements BytecodeRootNode { ... }

CoerceAnd 按顺序执行子操作，直到某个操作数转换为 false 为止，最后返回最后执行的那个操作数的转换后 boolean 值：

if CoerceToBoolean(child_1.execute()) == false:
    return false

if CoerceToBoolean(child_2.execute()) == false:
    return false

# ... more children

return CoerceToBoolean(child_n.execute())

注意与 BoolOr（无转换器）的区别：这里每个被求值的操作数（包括最后一个）都要经过 CoerceToBoolean，因为 _RETURN_CONVERTED 语义需要最后一次转换结果作为返回值。

4.3 booleanConverter 的约束与三种声明方式

从源码注释（ShortCircuitOperation.java）可以确认 converter 类的两条硬性约束：

• 所有 specialization 必须返回 boolean；
• 所有 specialization 只能接收单个动态操作数（single dynamic operand）。

converter 类有三种声明方式，均可被识别（引用 ShortCircuitTest.java 中的测试实现）：

1. 声明为 @Operation 内部类（如测试中的 BooleanConverterOperation）：与其他普通操作完全一致；
2. 普通类（如测试中的 BooleanConverterNonOperation）：虽然不标注 @Operation，但会经过与 @Operation 相同的校验流程，视为隐式操作；
3. @OperationProxy 代理类（如测试中的 BooleanConverterOperationProxy，配合 @OperationProxy.Proxyable）：当 converter 是 Node 子类时使用。

此外，测试注释明确指出：多个短路操作可以复用同一个 converter，而不会引入重复操作——converter 会被去重处理，只生成一份实例。

五、源码实证：测试如何验证短路语义

仓库中 ShortCircuitTest.java 是短路操作最直接的测试证据。它在一个根节点类上同时声明了 6 个短路操作，覆盖全部四种运算符与两种 converter 形态：

@ShortCircuitOperation(name = "ObjectAnd", operator = Operator.AND_RETURN_VALUE, booleanConverter = BytecodeNodeWithShortCircuit.BooleanConverterOperation.class)
@ShortCircuitOperation(name = "ObjectOr",  operator = Operator.OR_RETURN_VALUE,  booleanConverter = BooleanConverterOperationProxy.class)
@ShortCircuitOperation(name = "BoolAnd",   operator = Operator.AND_RETURN_CONVERTED, booleanConverter = BytecodeNodeWithShortCircuit.BooleanConverterNonOperation.class)
@ShortCircuitOperation(name = "BoolOr",    operator = Operator.OR_RETURN_CONVERTED,  booleanConverter = BytecodeNodeWithShortCircuit.BooleanConverterNonOperation.class)
@ShortCircuitOperation(name = "BoolAndNoConversion", operator = Operator.AND_RETURN_VALUE)
@ShortCircuitOperation(name = "BoolOrNoConversion",  operator = Operator.OR_RETURN_VALUE)

测试用例验证的关键行为包括：

• ObjectAnd（AND_RETURN_VALUE + 转换器）：true && 123 && foo -> foo（真值继续，返回原始值）、true && 0 && foo -> 0（遇到假值 0 提前终止并返回 0）；单操作数时 foo -> foo、0 -> 0。
• BoolAnd（AND_RETURN_CONVERTED）：true && 123 && foo -> true、true && 0 && foo -> false，即返回的是转换后的 boolean 而非原始值。
• BoolAndNoConversion（AND_RETURN_VALUE、无转换器）：0 && true 抛 ClassCastException、null && true 抛 NullPointerException；而 true && 0 -> 0——最后一个操作数 0 不做比较、原样返回，完美印证了第四节所说的"最后操作数不检查"规则。
• ObjectOr / BoolOr / BoolOrNoConversion：分别验证 OR 语义下"返回第一个真值原始操作数"（false || 0 || foo -> foo、false || 123 || foo -> 123）与"返回转换 boolean"（false || 123 || foo -> true）的差异，以及无转换器时的 ClassCastException / NullPointerException 行为。

测试还通过 @GenerateBytecodeTestVariants 同时跑了"基础配置"与"启用快速化 + 装箱消除（boolean.class、int.class）"两种生成配置，说明短路操作与 Bytecode DSL 的优化特性可以共存。

六、实战案例：SimpleLanguage 中的 SLAnd 与 SLOr

短路操作并非玩具特性——GraalVM 自带的 SimpleLanguage（SL）的字节码实现就真实使用了它。SLBytecodeRootNode.java（com.oracle.truffle.sl.bytecode 包）中声明了 SL 语言自己的逻辑与、逻辑或指令：

@OperationProxy(SLToBooleanNode.class)
...
@ShortCircuitOperation(name = "SLAnd", booleanConverter = SLToBooleanNode.class, operator = Operator.AND_RETURN_CONVERTED)
@ShortCircuitOperation(name = "SLOr",  booleanConverter = SLToBooleanNode.class, operator = Operator.OR_RETURN_CONVERTED)
public abstract class SLBytecodeRootNode extends SLRootNode implements BytecodeRootNode { ... }

这是非常典型的语言级用法，值得模仿：

• converter 复用现有 AST 节点：SLToBooleanNode 本来就是 SL 中把任意值转换为 boolean 的节点（定义了"真值/假值"规则），通过 @OperationProxy 声明后直接作为 booleanConverter 使用，语义与 SL 语言规范完全一致；
• _RETURN_CONVERTED 变体：SL 的 &&、|| 在类型系统（SLTypes）中表现为 boolean 结果，因此选用 AND_RETURN_CONVERTED / OR_RETURN_CONVERTED，保证短路表达式的结果类型与其他布尔表达式一致；
• 一条根节点声明两处使用：@Repeatable 让同一个字节码根节点同时拥有 SLAnd 与 SLOr 两条指令，而 SLToBooleanNode 被两条指令复用，未产生重复操作。

若想在自定义语言中实现"空值合并"（null-coalescing，如 someArray or [] 这种返回原始值的语义），只需按第四节 FalsyCoalesce 的写法改用 OR_RETURN_VALUE 即可——这正是 OR_RETURN_VALUE 注解 Javadoc 中特别点名的用途。

七、使用要点速查

1. 选对运算符：需要返回"最后一个操作数的原值"用 AND_RETURN_VALUE / OR_RETURN_VALUE（适合真值合并、空值合并）；需要固定 boolean 结果用 AND_RETURN_CONVERTED / OR_RETURN_CONVERTED（适合 &&、||）。
2. 操作数类型：不配 booleanConverter 时操作数必须是 boolean，非 boolean / null 操作数（除最后一个外）会抛 ClassCastException / NullPointerException；最后一个操作数不检查、原样返回。
3. converter 约束：只能有返回 boolean、接收单个动态操作数的 specialization；可用 @Operation、普通类或 @OperationProxy 声明，多个短路操作可安全复用同一 converter。
4. 一条根节点可声明多个短路操作（@Repeatable），生成器会自动生成对应的 beginXxx / endXxx Builder 方法对。
5. 语言实现责任：_RETURN_VALUE 语义下，保证最后一个操作数的类型被后续消费操作正确处理，是语言实现方（而非生成器）的职责。

若想继续深入 Bytecode DSL 的其他能力，可依次阅读 UserGuide.md（完整用户指南）、Optimization.md（快速化与装箱消除等优化）、RuntimeCompilation.md（运行时编译），以及 Bytecode DSL 简介 中列出的入门教程（GettingStarted.java、ParsingTutorial.java 等，位于 truffle/src/com.oracle.truffle.api.bytecode.test）。