Define icon UI event delivery task (T-607)
This commit is contained in:
@@ -0,0 +1,100 @@
|
||||
---
|
||||
id: T-607
|
||||
title: 建立图标后台结果的 UI 线程事件投递
|
||||
phase: 2
|
||||
deps: [T-606]
|
||||
status: TODO
|
||||
created: 2026-07-17
|
||||
issue: null
|
||||
context_ref: null
|
||||
claim_branch: null
|
||||
work_branch: null
|
||||
write_paths:
|
||||
- docs/tasks/T-607.md
|
||||
- core/application/
|
||||
- core/catalog/
|
||||
- app-modern/cmd/softbox/
|
||||
- app-modern/ui/gio/
|
||||
- app-win7/cmd/softbox/
|
||||
- app-win7/ui/gio/
|
||||
- docs/api.md
|
||||
- docs/routes.md
|
||||
- docs/04-architecture.md
|
||||
- docs/05-coding-rules.md
|
||||
- docs/review/phase2-review.md
|
||||
- docs/00-ai-start-here.md
|
||||
- docs/06-tasks.md
|
||||
- docs/current-state.md
|
||||
---
|
||||
|
||||
## 问题 / 背景
|
||||
|
||||
T-606 已关闭图标缓存的全局锁 convoy、远端响应无界读取和内存无上限问题,但 `IconCache.Load` 仍没有生产调用者。modern/win7 的 `AppShell.ApplyIcon` 会直接写 `shell.icons` map,Layout 同时读取该 map;当前只有同 goroutine 测试调用,所以尚未发生数据竞争。
|
||||
|
||||
正式图标后台加载若从 worker goroutine 直接调用 `ApplyIcon`,既会产生 map race,也违反 Gio 的 UI 更新模型。现有两个 `main.run` 只处理 window event,尚未把 `application.Runtime.Events()` 转成可唤醒窗口并由 Frame/UI goroutine 应用的事件流。Catalog 更新或相同 app 的新图标请求还可能使迟到结果过期;若只依靠 T-606 的 `SetItems` 剪枝,旧结果会在剪枝后把已删除或已换图标的 app 重新写回内存。
|
||||
|
||||
本任务先冻结并实现后台结果到 UI 的线程契约,让后续真实 HTTP 图标源和惰性调度只能复用该通道,不能绕过 application event 直接修改 Gio 状态。
|
||||
|
||||
## 方案
|
||||
|
||||
1. 在 `core/application` 增加图标事件类型与强类型 payload:
|
||||
- 至少区分 ready 与 failed,并纳入 `EventType.Valid()` 白名单。
|
||||
- 事件身份包含 `RequestID`、`AppID`、`IconRef` 与 DPI;ready payload 携带后台已解码的标准库 `image.Image`,不得携带 Gio 类型。
|
||||
- failed payload 提供稳定、可诊断且不包含敏感 URL/query 的失败信息;失败不伪装为成功或静默吞掉。
|
||||
- 提供统一构造/发布入口并校验空 ID、非法 `sha256:` 引用、非法 DPI、nil image 和 payload 类型,避免生产者各自拼装 `any`。
|
||||
2. 在 `core/catalog` 增加可注入的后台结果发布用例:
|
||||
- 接受已经完整确定的 `IconFetchRequest`、AppID/RequestID 和 application event publisher,在调用方提供的后台 context 中执行 `IconCache.Load` 与 `DecodeIcon`。
|
||||
- 成功发布 ready;加载、校验或解码失败发布 failed;事件发布失败显式返回/报告,不得改变 T-606 的缓存可信性语义。
|
||||
- 用例本身不创建无限 goroutine或无界 worker 队列;并发/生命周期由上层调度者和 context 控制。
|
||||
- 继续使用 T-606 的流式 Fetcher 合约,不新增图标 URL/CDN 规则。
|
||||
3. 为 modern/win7 建立相同的 application event relay:
|
||||
- 后台 pump 只接收事件、放入有界线程安全 inbox 并请求 `Window.Invalidate`;两个仓库锁定的 Gio 版本都明确允许并发调用 Invalidate,但 pump 不得调用 `ApplyIcon`、`paint.NewImageOp` 或修改 shell/model。
|
||||
- inbox 使用 FIFO、lossless backpressure:满队列时等待 UI drain 或 context/relay 关闭,不得静默丢 ready/failed;成功入队后必须请求重绘。
|
||||
- Gio Frame/UI goroutine 非阻塞 drain inbox,通过 `ApplyEvent` 校验强类型 payload 后调用 `ApplyIcon`;非图标事件不得因 T-607 被破坏或误判为图标事件。
|
||||
- window 销毁、runtime 关闭和 context 取消时 relay 可确定退出,不泄漏 goroutine,不在关闭后自旋或永久阻塞。
|
||||
4. 在两个 `AppShell` 中记录每个 app 最新期望与已应用的图标身份或等价 generation:
|
||||
- 只有 AppID 仍存在、`IconRef`/DPI 仍匹配且 RequestID 仍是最新请求时才应用 ready 结果。
|
||||
- 新请求覆盖旧请求;Catalog 删除 app、图标引用变化或请求取消后,迟到 ready/failed 均被丢弃。相同 AppID 的 `IconRef` 变化还必须清除旧 ImageOp/已应用身份,不能继续显示上一版图标。
|
||||
- failed 只保留与当前 IconRef/DPI 匹配的既有可信图标,否则保持占位状态,并结束对应 pending 状态;不得让旧失败覆盖新请求状态。
|
||||
5. 补 core 与双 Gio 的线程边界测试:
|
||||
- fake publisher/loader 证明 Load 和 Decode 不在 UI apply 路径执行,ready/failed 身份与错误传播正确。
|
||||
- 后台 submit 后 shell 尚未变化;只有 UI drain/ApplyEvent 后图标 map 才更新并触发重绘请求。
|
||||
- 覆盖删除 app、IconRef 变化并清理旧 ImageOp、同 app 新请求覆盖旧请求、非法 payload、满队列 backpressure、失败、取消与关闭 relay。
|
||||
- 使用 channel/barrier 等确定性同步;若环境支持 race detector则执行并记录,否则记录真实工具链限制。
|
||||
6. 同步事件协议、架构、路由和编码规则,明确 `ApplyIcon`/`ApplyEvent` 是 UI goroutine-only,后台唯一入口是 application event。
|
||||
|
||||
## 验收要点
|
||||
|
||||
- `EventIconReady`/`EventIconFailed` 是有效 application event,强类型 payload 不 import Gio,非法事件身份或 payload 被稳定拒绝。
|
||||
- 后台图标用例调用现有 `IconCache.Load` 与 `DecodeIcon`,成功/失败均发布带 RequestID、AppID、IconRef、DPI 的对应事件;发布失败可观察且 context 取消能及时结束。
|
||||
- modern/win7 后台 relay 收到事件时只入队并请求 invalidate,不会直接改变 `shell.icons`;Frame/UI goroutine drain 后才创建 `paint.ImageOp`。
|
||||
- relay 使用有界 FIFO 队列和可取消的 lossless backpressure,满队列不静默丢事件;window/runtime 退出后无 goroutine 泄漏、死锁或 busy loop。
|
||||
- 已删除 app、IconRef/DPI 已变化、RequestID 已被新请求取代的迟到 ready/failed 均被忽略;不会在 `SetItems` 剪枝后重新插入旧图标。相同 AppID 的 IconRef 变化会清除旧 ImageOp,直到新图标就绪前显示占位。
|
||||
- 图标失败保留可用的既有图标或占位状态,错误可诊断;非法 payload 不 panic、不污染 UI 状态。
|
||||
- 两个 Gio 适配器使用同一事件语义但不互相 import,modern Gio v0.10.1 与 win7 Gio v0.6.0 的 workspace 隔离保持不变。
|
||||
- Layout 路径继续无磁盘、网络、哈希和图片解码;`ApplyIcon` 文档与测试明确 UI goroutine-only,不通过给 map 加锁把后台直写合法化。
|
||||
- Go 1.20.14 + `GOWORK=off` 下 `go vet ./...`、`go test -count=1 ./...` 通过。
|
||||
- modern 根 workspace 与 win7 独立 workspace 的 UI/cmd 测试及 Windows amd64 构建通过;`./scripts/verify_phase0.ps1` 全绿。
|
||||
- `python scripts/validate_agent_context.py`、`python scripts/validate_harness_governance.py` 与提交前差异检查通过。
|
||||
|
||||
## 边界（不改什么）
|
||||
|
||||
- 不决定 `sha256:` 图标引用到 URL、CDN 路径或 DPI 变体的发布协议,不增加 Catalog 字段,不实现具体 HTTP `IconFetcher`。
|
||||
- 不在 Layout 中启动网络/磁盘 IO;不实现按 viewport 预取、滚动取消、优先级或完整生产调度策略,本任务只建立可复用的后台结果发布与 UI 投递通道。
|
||||
- 不把 `ApplyIcon` 改成可从任意 goroutine 调用的线程安全 API,不以 mutex 掩盖错误线程归属。
|
||||
- 不补 Phase 2 后续完整适配器交互契约矩阵,不修改 `VisibleItems` 快照 API,不拆分 `shell.go`;这些继续按审核顺序另立任务。
|
||||
- 不修改 T-606 的内存 LRU、磁盘缓存安全策略或 Fetcher 读取上限,不处理 `ErrIconCacheUnsafe` 自动隔离。
|
||||
- 不处理 ZIP 中央目录预扫描、断电耐久、Catalog 签名向量或 T-302 安装整合。
|
||||
- 不升级 Go/Gio 或合并 modern/win7 workspace,不修改、提交或删除用户的 `soft_quay.code-workspace`。
|
||||
|
||||
## 协作约束
|
||||
|
||||
- 按仓库当前规则由单 Agent 串行执行,不启动子 Agent。
|
||||
- 本任务只允许修改 frontmatter 中的 `write_paths`;若接线需要新增图标 URL/清单协议或从后台直接触碰 Gio 状态,必须停止并记录,不得在 T-607 内扩大边界。
|
||||
- T-607 完成、完整验证并提交前,不落成或领取 Phase 2 审核顺序中的后续任务。
|
||||
|
||||
## 执行记录
|
||||
|
||||
- 2026-07-17:根据 `docs/review/phase2-review.md` 交叉复核定稿的第二优先级整改落成任务;现有全局最大任务为 T-606,因此取 T-607,依赖已完成的 T-606。
|
||||
- 2026-07-17:任务冻结后台 Load/Decode→application event→有界 relay/Invalidate→Gio UI drain/ApplyEvent 的线程边界;真实 URL 映射、viewport 调度、适配器全量契约、VisibleItems 快照和文件拆分继续按审核顺序串行处理。
|
||||
- 2026-07-17:用两个隔离 workspace 的本地 `go doc gioui.org/app.Window.Invalidate` 核对 Gio v0.10.1 与 v0.6.0,两者都明确 Invalidate 可并发调用;因此只允许后台 relay 调 Invalidate,所有 shell/ImageOp 更新仍限定在 UI goroutine。
|
||||
Reference in New Issue
Block a user