身份与属性

框架每帧重新执行用户 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 构建耗时与后端绘制耗时的拆分)、组件总数、当前焦点与悬停的身份。它读的是真实状态,不额外维护一套统计。


This site uses Just the Docs, a documentation theme for Jekyll.