deeplearning4j op-codegen 的 Mixin 继承机制:ADR 0008 设计与实现剖析
deeplearning4j op-codegen 的 Mixin 继承机制:ADR 0008 设计与实现剖析
导读
本篇文章基于 deeplearning4j 仓库中 op-codegen 子项目的架构决策记录 ADR 0008 Inheritance,系统讲解 ND4J/SameDiff 操作(Op)定义 DSL 中用于消除重复、显式表达 Op 间关系的 Mixin 混入机制。你会掌握:为什么在 DSL 中要引入 Mixin 而非传统单继承、useMixin 的完整语义与可用选项、命名冲突的裁决规则,以及结合 OpBuilder.kt、Op.kt 和 Mixins.kt 的源码级实现细节,从而具备直接阅读、理解和扩展 op 定义的能力。
背景与动机:为什么 Op 定义需要"继承"
在 op-codegen 项目的 DSL 中,大量 Op 具有相似接口:所有 transform 类操作都接收单个输入,其中一部分还要接收额外参数;所有 pairwise 类操作都接收两个输入,依此类推。在引入 Mixin 机制之前,这些 Op 的文档常常是"复制粘贴 + 少量修改"的产物。
这种复制粘贴式的定义方式带来两个核心问题:
- 维护成本爆炸:后续任何修改,本应只改一处,却必须同步修改所有被复制过的地方,任何遗漏都会造成定义漂移;
- 关系隐式化:Op 之间的相似性完全靠人工维护,代码本身不表达任何结构关系,读者无法从定义中看出"哪些 Op 共享同一套输入输出契约"。
而 DSL 的设计原则是:尽可能显式(explicit),同时减少重复与样板代码(见 README 的 DSL 说明)。
项目早期曾非正式地加入过一个简单的继承机制:允许定义抽象基类 Op,新 Op 可以在定义自身属性前"拷贝"基类的任意部分。但该方案存在两个硬伤:
- 无法多继承:一个 Op 只能基于一个基类;
- 无法直接访问基类的字段:引用其参数非常不便。
正是这些缺陷直接促成了 ADR 0008 的正式决策。
决策:显式的 Mixin 混入机制
核心概念
ADR 0008(状态:ACCEPTED,由 Alex Black 与 Paul Dubs 于 2019 年 11 月 29 日和 12 月 2 日讨论确定)正式引入一种显式的 Mixin 机制:
Mixin("name") { ... }可以定义任意 Op 的任意组成部分,但它本身不是一个 Op 定义。Mixin 可以在顶层(top-level)定义,因此可以被跨命名空间(namespace)复用。
在 Op 上下文内通过 useMixin(mixinReference, ...options...) 将 Mixin 混入 Op,其效果相当于把 Mixin 中的所有定义就地复制到当前 Op 中(除非通过选项另行配置)。
两条关键语义:
- 如果
useMixin(ref)是 Op 定义中的第一行,其行为与旧的继承机制完全一致(等价于"先继承基类,再写自己的属性"); useMixin(ref)返回一个 holder 对象,可用来引用 Mixin 中定义的参数。
useMixin 可用选项
| 选项 | 默认值 | 含义 |
|---|---|---|
keepInputs |
true |
是否带入 Mixin 中定义的输入(Input) |
keepArgs |
true |
是否带入 Mixin 中定义的参数(Arg) |
keepOutputs |
true |
是否带入 Mixin 中定义的输出(Output) |
keepSignatures |
true |
是否带入 Mixin 中定义的方法签名(Signature) |
keepDoc |
true |
是否带入 Mixin 中的文档(Doc) |
keepConstraints |
true |
是否带入 Mixin 中的约束(Constraint) |
说明:ADR 正文列出上述六个选项;实际实现中(OpBuilder.kt)还额外提供了
keepConfigs(默认true),用于控制是否带入 Mixin 中引用的配置对象(Config),可视为对 ADR 决策的实现扩展。
命名冲突规则:最后定义者获胜
如果在多个 Mixin 之间、或 Mixin 与 Op 定义之间存在命名冲突,则最后定义的一方获胜(the last definition wins)。这一规则在后续"语义细节"一节中有更细致的展开。
实战示例:用 Mixin 定义 indexAccum 并派生 firstIndex
ADR 0008 给出了一个完整的实战示例,它同时演示了 Mixin 定义、混入选项、holder 引用和 Signature 组合。这也是仓库中真实存在的模式(见 Mixins.kt 中的 indexAccum 与 Math.kt 中的 firstIndex)。
第一步:在顶层定义可复用的 indexAccum Mixin
val indexAccum = Mixin("indexAccum"){
legacy = true
javaPackage = "org.nd4j.linalg.api.ops.impl.indexaccum"
val input = Input(NUMERIC, "in") { description = "Input variable" }
val keepDims = Arg(BOOL, "keepDims") { description = "If true: keep the dimensions that are reduced on (as length 1). False: remove the reduction dimensions"; defaultValue = false }
val dims = Arg(INT, "dimensions"){ count = AtLeast(1); description = "Dimensions to reduce over. If dimensions are not specified, full array reduction is performed" }
Output(NUMERIC, "output"){ description = "Reduced array of rank (input rank - num dimensions)" }
Signature(input, dims)
AllParamSignature(withOutput = false)
}
要点解析:
- Mixin 定义了 transform/reduce 类 Op 的"通用骨架":一个数值输入
in、可选参数keepDims、归约维度参数dimensions、输出output,以及两条预置签名; legacy = true与javaPackage会被混入方继承(源码中通过legacyWasSet/javaPackageWasSet标记位实现,详见下文实现剖析);- 注意
Signature(input, dims)与AllParamSignature(withOutput = false)都定义在 Mixin 内部,通过keepSignatures选项控制是否带入具体 Op。
第二步:在命名空间内用 useMixin 派生具体 Op
Namespace("math"){
Op("firstIndex") {
val idxAccum = useMixin(indexAccum, keepSignatures=false)
var c = Arg(CONDITION, "condition") { description = "Condition to check on input variable" }
Signature(idxAccum.input("in"), c, idxAccum.arg("dimensions"))
Signature(idxAccum.input("in"), c, idxAccum.arg("keepDims"), idxAccum.arg("dimensions"))
Doc(Language.ANY, DocScope.ALL){
"""
First index reduction operation.
Returns a variable that contains the index of the first element that matches the specified condition (for each
slice along the specified dimensions)
Note that if keepDims = true, the output variable has the same rank as the input variable,
with the reduced dimensions having size 1. This can be useful for later broadcast operations (such as subtracting
the mean along a dimension).
Example: if input has shape [a,b,c] and dimensions=[1] then output has shape:
keepDims = true: [a,1,c]
keepDims = false: [a,c]
""".trimIndent()
}
}
}
要点解析:
useMixin(indexAccum, keepSignatures=false):跳过 Mixin 中的两条预置签名,因为firstIndex需要额外接收condition参数,签名必须重新组合;useMixin返回的 holder(此处变量名恰为idxAccum)可链式引用 Mixin 内定义的参数:idxAccum.input("in")、idxAccum.arg("dimensions")、idxAccum.arg("keepDims"),从而在不重复定义的前提下自由拼装新签名;- 两条
Signature分别对应(in, condition, dimensions)与(in, condition, keepDims, dimensions)两种重载——这正是面向不支持默认参数的 Java 语言生成多个重载方法的依据; firstIndex自身只需要定义与 Mixin 不同的部分(condition参数 + 自己的文档),输入、输出、keepDims、dimensions全部来自 Mixin。
源码级实现剖析
useMixin 的真实实现
OpBuilder.kt 中 Op.useMixin 的实现如下(节选核心逻辑):
fun Op.useMixin(mixin: Mixin,
keepArgs: Boolean = true,
keepInputs: Boolean = true,
keepOutputs: Boolean = true,
keepConstraints: Boolean = true,
keepSignatures: Boolean = true,
keepDocs: Boolean = true,
keepConfigs: Boolean = true
) {
if(mixin.legacyWasSet){ legacy = mixin.legacy }
if(mixin.javaPackageWasSet){ javaPackage = mixin.javaPackage }
if (keepArgs) { args.addOrReplaceAll(mixin.args) }
if (keepInputs) { inputs.addOrReplaceAll(mixin.inputs) }
if (keepOutputs) { outputs.addOrReplaceAll(mixin.outputs) }
if (keepConstraints) { constraints.addAll(mixin.constraints) }
if (keepSignatures) { signatures.addAll(mixin.signatures) }
if (keepDocs) { doc.addAll(mixin.doc) }
if (keepConfigs) { configs.addOrReplaceAll(mixin.configs) }
}
从实现可以确认三个事实:
- 选项默认值全部为
true,与 ADR 描述一致; - 标量属性(
legacy、javaPackage)通过WasSet标记位拷贝:只有当 Mixin 显式设置过这些属性时才覆盖当前 Op 的值,这避免了"混入一个未设置 javaPackage 的 Mixin 把 Op 已配置的包名清空"的隐患(标记位定义见 Op.kt); - 列表类成员(inputs/args/outputs/configs)使用
addOrReplaceAll:同名参数以混入方为准替换现有项,不同名参数直接追加——这正是"最后定义者获胜"规则的实现基础。
"最后定义者获胜"的底层逻辑
Op.kt 中定义了 addOrReplace 与 addOrReplaceAll:
fun <T: Parameter> MutableList<T>.addOrReplace(param: T){
val found = this.find { it.name() == param.name() }
if(found != null){
this.replaceAll { if(it.name() == param.name()){ param } else { it } }
}else{
this.add(param)
}
}
即:按名称(name())匹配,同名即替换,异名即追加。因此"最后定义者获胜"完全由执行顺序决定:
useMixin在 Op 定义前部调用 → Op 后续同名定义覆盖 Mixin;useMixin在 Op 定义后部调用 → Mixin 覆盖 Op 先前的定义。
例如假设 javaPackage 同时在 Op 与 Mixin 中定义:
// 情形一:Op 中的定义获胜
Op("foo"){
useMixin(exampleMixin) // mixin 先混入
javaPackage = "some.example.package" // op 后定义,覆盖
}
// 情形二:Mixin 中的定义获胜
Op("foo"){
javaPackage = "some.example.package" // op 先定义
useMixin(exampleMixin) // mixin 后混入,覆盖
}
输入、参数、输出的同名替换逻辑与此完全一致。
Mixin 的组合:Mixin 内部再 useMixin
Mixin 本身也是"Op 的一部分"的载体,因此在 Mixin 内部同样可以使用 useMixin 来组合其他 Mixin(对应实现见 OpBuilder.kt 中的 Mixin.useMixin,参数与 Op.useMixin 完全一致)。
这一点在仓库的 Mixins.kt 中有大量真实用例:
val transform = Mixin("transform"){
legacy = true
Input(DataType.NUMERIC, "x") { description = "Input variable" }
Output(DataType.NUMERIC, "output"){ description = "Output variable" }
}
val transformStrict = Mixin("transformStrict"){
useMixin(transform) // 组合基础 transform
javaPackage = "org.nd4j.linalg.api.ops.impl.transforms.strict"
}
val transformBool = Mixin("transformBool"){
useMixin(transform)
javaPackage = "org.nd4j.linalg.api.ops.impl.transforms.bool"
}
这里 transformStrict、transformBool、transformFloating、transformSame 等各自以 transform 为基础,仅差异化 javaPackage,形成了清晰的 Mixin 分层结构。归约类同样如此:reduceFloating、reduceSame、reduceLong 都 useMixin(reduce),并各自指向不同的 legacy 包名。
Op 构造参数形式的等价写法
除了在 Op 体内调用 useMixin,DSL 还提供了一种声明式简写——在 Op(name, mixin, ...) 构造参数中直接传入 Mixin(OpBuilder.kt):
fun NamespaceOps.Op(name: String,
extends: Mixin,
keepArgs: Boolean = true,
keepInputs: Boolean = true,
keepOutputs: Boolean = true,
keepConstraints: Boolean = true,
keepSignatures: Boolean = true,
keepDocs: Boolean = true,
block: (Op.() -> Unit)? = null): Op {
return this.Op(name) {
useMixin(extends, keepArgs = keepArgs, keepInputs = keepInputs,
keepOutputs = keepOutputs, keepConstraints = keepConstraints,
keepSignatures = keepSignatures, keepDocs = keepDocs)
if (block != null) { this.block() }
}
}
它等价于"将 useMixin(mixin, ...options...) 作为 Op 定义的第一行"。由于该形式只能混入单个 Mixin,当需要同时复用多个 Mixin 时仍应在 Op 体内多次调用 useMixin。
仓库中的真实用法,如 Math.kt 的 firstIndex 与 lastIndex(均以 indexAccum 为基、关闭签名继承后自定义签名):
Op("firstIndex", indexAccum, keepSignatures=false) {
var c = Arg(CONDITION, "condition") { description = "Condition to check on input variable" }
Signature(this.inputs.get(0), c, this.args.get(1)) // in, condition, dimensions
Signature(this.inputs.get(0), c, this.args.get(0), this.args.get(1)) // in, condition, keepDims, dimensions
...
}
以及 Math.kt 中的 iamax / iamin(直接以 indexAccumCustom 为基,仅补充文档),体现"同一个 Mixin 派生多个 Op、每个 Op 只写差异部分"的典型用法。
一个 Op 混入多个 Mixin
Mixin 带来的真正能力是多继承。一个 Op 可以在体内多次调用 useMixin,叠加多个 Mixin 的输入、参数、输出与文档。例如 Math.kt 中的多处 useMixin(broadcastingDoc),就是在 Op 定义中混入一个只包含广播语义文档的 Mixin(定义见 Mixins.kt),从而让分散的二元运算 Op 共享同一份"支持 NumPy 广播规则"的说明文字——这是旧的单继承机制完全做不到的。
语义细节与使用注意事项
Mixin 能定义什么、不能定义什么
Mixin 几乎可以定义 Op 的所有组成部分:Input、Arg、Output、Constraint、Signature、Doc、Config,以及标量属性 legacy、javaPackage。唯一不能在 Mixin 中配置的是 Op 的 name、libnd4jName 和 javaOpClass——它们是具体 Op 的身份标识,必须由使用方决定。从 Op.kt 的 Mixin 数据类定义可以印证:Mixin 只有 inputs/outputs/args/constraints/signatures/doc/configs 与 legacy、javaPackage 字段,没有 Op 名称类字段。
作用域
Mixin 定义在顶层即可跨命名空间复用(仓库正是将全部通用 Mixin 集中放在 mixins/Mixins.kt 单一文件中,供 Math.kt、Random.kt、CNN.kt 等各命名空间文件共同 import)。如果某个 Mixin 仅服务于单个命名空间,也可以放在该命名空间上下文内定义。
混入顺序决定"最后一刻"的属性值
由于标量属性(legacy、javaPackage)的拷贝使用"仅在 WasSet 时覆盖"的语义、而列表成员使用按名替换,混入顺序对最终 Op 定义有实际影响。建议遵循"先混入公共基础,再覆盖差异"的书写顺序,以保持可读性。
影响与权衡(Consequences)
ADR 0008 明确列出该决策的收益与代价:
优势(Advantages)
- 支持多继承:一个 Op 可以同时混入多个 Mixin,摆脱了旧机制单基类的限制;
- 跨命名空间共享:Mixin 可定义在顶层,同一份定义可被不同命名空间下的多个 Op 复用;
- 参数显式可访问:通过
useMixin返回的 holder(或 Mixin 引用本身),可以显式引用 Mixin 中定义的输入、参数、输出与配置,组合签名时无需重新声明。
劣势(Disadvantages)
- 需要改造既有用法:旧的基于抽象基类的继承用法需要迁移到新的 Mixin 语法上(仓库中已通过
Op(name, mixin, ...)构造参数形式与useMixin无缝衔接)。
关联阅读
- ADR 0005:Optional parameters and signatures——Mixin 中
Signature多签名的设计动机; - ADR 0006:Op specific enums——
Arg使用 ENUM 类型时的相关约定; - ADR 0007:Configuration objects——
Config与useConfig/useMixin(keepConfigs=...)的关系; - op-codegen README(DSL 全量描述)——Mixin、Op、Input、Arg、Output、Signature、Doc、Constraint 的完整 DSL 参考。
总结
ADR 0008 以一份正式架构决策的形式,为 op-codegen 的操作定义 DSL 确立了 Mixin 混入机制:它以"定义即复制、按名替换、最后定义者获胜"为核心语义,配合 keepInputs/keepArgs/keepOutputs/keepSignatures/keepDoc/keepConstraints(实现中另有 keepConfigs)六个可关闭的混入维度,既完整覆盖了旧继承机制的"基于抽象基类派生 Op"场景,又解锁了多继承、跨命名空间复用与显式参数引用三项新能力。这一设计直接服务于项目的根本目标——为 ND4J 与 SameDiff(乃至未来的 Python/Swift 等语言)生成一致、统一、可维护的 Op API,其落地实现可在 Mixins.kt(Mixin 库)、Math.kt(混入使用)与 OpBuilder.kt(机制实现)中直接阅读验证。