身份与属性
框架每帧重新执行用户 DSL,因此”上一次写的组件”与”这一次写的组件”之间没有对象连续性。要在两次执行之间保留状态(输入框里的文字、滚动位置、动画进度),就必须有一个跨帧稳定的键。
KotlinMCUI 用一条身份链(DslId)作为这个键,并用”本帧是否被读到”作为存活判据。
身份链
DslId 是一条不可变、可结构共享的单向链表:每个节点携带一个任意对象与指向父节点的引用,+ 追加一节。因为节点不可变,派生身份不会复制整条链。
关键性质:
- 结构相等:两个独立构造出来的相同链条互相
equals。这样即使 DSL 重新执行、重新拼接身份,键依然命中。 - 哈希缓存:哈希是”父哈希 * 31 + 自身哈希”,首次计算后缓存。身份链会被当作 map 键反复使用,缓存避免了每帧重复递归。
- 有序可迭代:从叶子向根遍历,因此
size(深度)与topElement都很便宜。
令人惊讶的一点:== 不能区分 NaN 哨兵
Measure 是 value class,其自动生成的 equals 走 Double.compare。对 Double.compare 来说所有 NaN 彼此相等,因此
Measure.AUTO == Measure.AUTO_MIN // true
Measure.AUTO == Double.NaN.px // true
判断”是哪种自动尺寸”只能靠 isAutoMin 或直接看位模式,不能靠 ==。身份比较本身不涉及 Measure,但任何把尺寸塞进身份或缓存键的代码都要注意这一点。
用 lambda 的 ::class 当键
用户写:
Column {
Button { }
Button { }
}
两个 Button{ } 没有显式 id,但它们必须被区分开,否则状态会串。框架利用了一个 JVM 事实:每个 lambda 字面量都编译成独立的类。因此 function::class 就是一个”声明位置”的稳定标识——同一处代码每帧得到同一个 Class 对象,不同处代码得到不同的。
这就是约定:
- 带 lambda 参数的函数:
id: Any? = null,内部取id ?: function::class; - 不带 lambda 参数的函数:
id: Any放在最后,于是ColorRect(modifier, color) { }里的{ }正好落进id槽,充当声明位置标识。
第二种写法看起来像”多写了一个空 lambda”,实际是在借用这个机制,不是笔误。(正式文档有说明,但它确实容易被误读为冗余代码。)
副作用是:把某个调用点的 lambda 提取成变量、内联,或者跨调用点复制,都会改变身份,进而丢失焦点、悬停与 local{} 状态。改动 UI 结构时需要注意这一点。
需要”按键值区分”而不是”按位置区分”时,用 forEachWithId { }——它把元素本身追加进身份;元素自身 equals 不可靠时,用 refId 把它包成按引用比较的键。
属性作用域
存活判据是”本帧被读到”
每个属性条目带一个帧戳。一帧完整结束后遍历映射,丢弃帧戳不等于当前帧号的条目,并对每个被丢弃的条目调用清理回调。
于是局部属性的生命周期规则变得极其简单:DSL 这一帧没有读到它,它就被回收。不需要显式 dispose,也不需要 diff 算法——用户代码写 if (show) { ... },show 变假时其中的状态自然消失。
清理只在整帧成功(构建完成且绘制返回)后发生。构建或绘制中途抛错时,这一帧没有走完所有旧声明,未访问不等于已经删除:旧的 local 条目和被失败帧新建的条目都保留,交由下一次成功帧的扫描或 Screen/Root 关闭来回收。这样失败帧不会因为遍历中断而释放上一张完整帧仍在使用的状态,但也不承诺回滚用户代码已经产生的副作用;已经提交的绘制像素无法撤回。
四种作用域
边界只有四种,寿命一档比一档长:帧 → 屏 → 根 → 进程。
| 作用域 | 边界 | 键 | 清理 |
|---|---|---|---|
local | 帧 | 当前身份 + 传入 key | 每帧扫描未访问项 |
stable | 屏 | 当前身份 + 传入 key | 从不扫描,Screen 关闭时统一释放 |
session | 根 | 仅传入 key(不带身份前缀) | root.close() 时执行清理并清空 |
static | 进程 | 仅传入 key | 永不释放 |
session 与 static 的键都是裸 key,所以它们是按名字寻址的:session("x") 在同一个根上的任何屏、任何组件、任何声明点都指向同一个槽(A 屏设、B 屏读);static("x") 则是全进程。两者的类型契约一样——同一个 key 必须是同一个类型,读错会抛 ClassCastException。
local / stable 的 key 只是本声明点的子键,不会跨声明点共享;想按名字共享只能用 session 或 static。
| 作用域 | 释放时机 |
|---|---|
local | 某一完整帧未被读到,帧末回收;失败帧不扫描 |
stable | 声明它的 Screen 关闭时统一释放 |
session | 所在根 close() 时 |
static | 不释放(进程级) |
四种作用域上注册的清理动作(dispose { })都会在各自被释放时执行:local 在帧末,stable 在屏关闭时,session 在根关闭时,static 不会执行。清理动作是普通 lambda,不携带额外上下文,因此可以在任何 DSL 位置注册。
协程随属性走
不变量:条目的 scope 非空 ⇔ 该条目拥有这个 scope。 条目只在一种死法下拥有 scope——逐条死;一起死的条目自身不持有 scope,scope 由整条生命周期持有。
local:条目逐个死。 未被读到的条目在帧末单独清理,所以每个属性持有自己的SupervisorJob(兄弟协程互不连坐),条目被清时 cancel 它自己的。该 Job 的父级是声明它的 Screen 的 Job,Screen Job 又是 Root 会话 Job 的子级。stable:整屏一起死。 条目共享一个由 Screen 持有的 scope,Screen 关闭时统一 cancel,所以单独替换一个cached条目不会连坐兄弟。session/static:按根或进程释放。session直接用根已有的sessionScope(根关闭时取消);static使用一个显式的进程 scope,父级和调度器都不来自任何 Root 或 Screen,因此不会绑定第一个创建者。单独清理一个共享条目不会 cancel 整个生命周期 scope。
Screen 关闭时先清条目再 cancel 它的 Job;这个取消同样会到达尚未发布的 local 初始化协程,即使它的条目还没进入 map。初始化失败只取消本次新建、尚未发布的 local/stable scope,不会取消已发布的兄弟;用户的普通副作用不承诺回滚。
val ticker = local { launch { while(true) { tick(); delay(16) } } } // 随这一帧的声明存活
local { launch { … } } 只在这个属性被读到的帧里活着;stable { … } 活到屏关闭;session/static 同理按各自的边界。独立访问器 local.coroutineScope / stable.coroutineScope 也是普通条目:local 的条目持有自己的 scope、帧末不再被读到就随条目取消;stable 的条目只负责”被读取才存活”的帧戳,返回的是该屏共享的 scope。session/static 的访问器不是条目,直接返回 Root/进程已有的 scope:共享map不会因为某个Screen或Root取过scope而增加一个身份键,关闭后仍按各自所有者判断可用性(Root关闭后该Root的session访问器失败,static的进程scope与页面无关但仍拒绝已关闭界面的声明路径)。
需要“不随属性死”的协程,请显式用更大的作用域(根的、进程的)。local/stable/session 默认在根的会话线程执行;static 使用 Dispatchers.Default,操作 UI 时必须投递回所属 Root。
static 的映射挂在 DslDataStore 伴生对象上,是全进程唯一的一份,且键不含身份前缀——这正是”不同 mod 用相同 id 会互相命中”的来源,被有意用于跨 mod 通信。
session 的映射则挂在根上(DslRoot 持有),一个根一份,屏创建时就绑定到它所在的那个根——所以后端必须用属于该根的 Screen 工厂建屏。两份映射都是并发容器:一个进程可以有多根在不同线程渲染。
共享槽的创建和替换是一个按 key 的协议,而不是”先 get 再 init 再 put”:同名并发调用只有一个初始化块运行,所有调用者拿到同一个槽;初始化抛异常不会留下占位,下一次访问可重试;cached 的替换初始化失败时旧槽仍在 map 中且未被清理;初始化块递归访问同名 key 会得到明确的递归错误。递归guard按线程和存储map身份记录:同一共享map的另一个Scope视图访问同名key同样算递归,不同Root的map用相同key则互不冲突。guard只在初始化期间存在,随最后一个初始化从ThreadLocal移除。local/stable 仍是每屏单线程路径,不为此加全局锁。
共享槽以写入共享map为提交点。初始化块返回时的复查发生在提交前,提交后 static 归进程、session 归Root:创建者的Screen(对static也包括Root)关闭不会回滚一个已发布且可能已被其他调用者取得的槽;只有session的实际所有者Root关闭仍会移除并丢弃刚发布的槽,避免关闭竞态把工作留在已关闭Root的表中。
单个属性值的引用读写有跨线程可见性;这不把任意用户对象变成线程安全。共享槽里放可变对象时,跨线程的复合修改仍需用户同步;也不承诺跨多个 key 或跨 IO 的原子操作。static/session动画器的多字段状态由该动画器自己的锁保持一致,local/stable动画不使用该锁。
Screen 或 Root 关闭后,从保留的 PropertyLifeScope 再做 property、cached(包括缓存命中的快速路径)、coroutineScope 或 dispose 都会在分配/改表前失败。初始化块内关闭所属界面时,初始化返回后会重新检查,未发布的资源被丢弃。
条目的形态
属性的最小单位是一个带帧戳的可读写值,外加一个清理钩子。之上衍生出几种:
- 普通属性:
property(id) { 初值 },只在不存在时调用初始化块; - 声明式语法糖:作用域对象本身可调用,于是既能写
var a by local { 1 },也能只写local { startAnimation() }当作”进入作用域并初始化”的语句; - 带键缓存:
cached(key, id) { 计算 },键不变就复用,键变化时重建并清理旧值。文档明确建议只用于昂贵计算(如格式化),轻量计算不值得; - 动画:见下。
初始化块以 DslExecuteContext 为额外上下文,所以初始化期间可以启动协程、关闭界面——这是刻意设计:初始化只发生一次,正适合放置”副作用”。
动画
动画值实现为一种特殊的属性,其读值不是直接返回存储值,而是根据帧起始时间在一段区间内插值。
动画器只保存一个内部时钟,不持有创建它的 PropertyLifeScope、Screen 或调度器:
local/stable用所属 Screen 的帧起始时间;session用所属 Root 的时钟:一个真实 Root 帧开始时取一次时间,该帧内的多个 Screen 复用同一时刻;没有 Root 帧包裹的直接 Screen 帧(例如离线渲染/测试)才自行推进它;static用进程单调时钟,与任何 Root 或 Screen 无关。
因此 session 动画在创建它的 Screen 关闭后仍会随同一 Root 的新 Screen 推进,static 动画跨 Root 仍然有效。共享动画器的开始值、目标、时间和帧内记忆是一组状态,由一个per-animator锁串行化;local/stable动画仍是单屏无锁路径。这只保护框架自己的动画字段,不保护用户 Interpolatable 对象的内部可变状态。
local/stable/session读值用帧起始时间,同一帧内记忆结果;static使用当前进程单调时间,不承诺帧内恒定;- 赋值时先把”当前插值结果”记为起点,再设定终点与起始时间,因此中途改变目标会从当前位置平滑续接,不会跳变;
- 目标值与当前目标相同则直接返回,避免重复触发。
两个入口的语义不同:
| 入口 | 可写 | 行为 |
|---|---|---|
animatable | 是 | 由赋值驱动,赋值后从旧值过渡到新值 |
autoAnimate | 否(只读) | 每次读到都重新求值目标,因此表达式一变化就开始过渡 |
autoAnimate 可以给一个初始值。省略时首帧的起点就是目标值本身,于是首帧不会从占位值跳一下。帧内记忆是按帧起始时间做的,所以”目标每帧重算”不会导致同一帧内多次插值。
同一帧内改变目标之后再次读取,拿到的是新区间的起点(即改变前的值),而不是改目标之前缓存的结果——写入会使帧内记忆失效。时长为零时直接返回目标值,不进入插值,因此不会出现 0 / 0。
协程
每个属性都属于一个受管理的协程作用域,初始化块执行前作用域已就绪。local/stable/session 使用根的会话调度器;static 使用 Dispatchers.Default。
作用域按属性边界建立:local 每个属性各自新建并持有;stable 每个 Screen 懒创建一个共享 scope;session 直接使用根已有的 sessionScope;static 使用进程内唯一的 scope,不绑定任何界面。local/stable 的 scope 都挂在 Screen Job 下,Screen 或 Root 关闭都能到达未发布的初始化协程。规则见上一节。
这带来一条容易踩的规则:
// 正确:作用域每帧都被读到,因此一直存活
val scope = local.coroutineScope
Button {}.clickable { scope.launch { /* ... */ } }
// 错误:只在事件回调里取用,回调执行时机不确定,
// 而该属性在其他帧没有被读到,会被当作过期项回收
Button {}.clickable { local.coroutineScope.launch { /* 下一帧就被销毁 */ } }
事件装饰器提供的回调本身就带 CoroutineScope 接收者,并用同样机制维持作用域,所以最常见的情况(在 clickable 里 launch)是安全的。
launch 的代码默认运行在渲染线程上(static 使用独立的进程调度器)。耗时工作必须显式切到 IO 调度器,把结果写回属性,由渲染线程消费。槽的发布是安全的,但共享槽里的可变对象不会因此自动获得线程安全,复合读写仍需用户同步。
属性组合子
StableRO / StableRW 是最小接口(读 / 读写),并通过 getValue / setValue 运算符支持委托语法。注意这套运算符是对属性值定义的扩展,因此
var value by prop // prop 是 StableRW,value 是普通局部变量
而不是只对类成员生效。常用组合子包括读取映射(remapGet)、写入映射(remapSet)、读写双向映射(remap)、读取/写入副作用(onGet / onSet)。类型双向转换(如 Float 属性映射为 Double 滑块)就靠 remap 完成。
反射属性也可以提升:KMutableProperty0<V>.property 得到 StableRW<V>,这让大量已存在的配置字段可以直接接进 DSL。
帧与调试
数据存储对象每帧推进一个帧号,记录帧起始时间,并始终完成耗时统计;只有整帧成功时才清理过期局部属性。帧号以 ULong.MAX_VALUE 起始,第一次自增回绕到 0——这不是怪癖而是”首帧号为 0”的实现手段。构建在 buildFinish 回调前失败时,dslRenderTimeMs 记录本次构建已用时间,不会沿用上一帧的值。
调试叠层从同一处取数:各作用域的存活条目数、帧率与帧耗时(含 DSL 构建耗时与后端绘制耗时的拆分)、组件总数、当前焦点与悬停的身份。它读的是真实状态,不额外维护一套统计。