fountain f_cache 缓存模块代码审查报告:18 项缺陷的发现、修复与验证实录
fountain f_cache 缓存模块代码审查报告:18 项缺陷的发现、修复与验证实录
导读
本文基于 fountain 仓库 .autocode/bugs/bug-cache-archived-20261006.md 这份完整的代码审查报告,系统梳理 f_cache 模块(强/弱引用堆缓存)在基线 sts/1.3.x(提交 7cd7863e)上暴露的 3 条严重、5 条中等、8 条低危、2 条待验证 缺陷,逐一还原其根因、影响面、修复方案与实测证据。读者读完后,将能:① 完整理解 HeapCache / WeakHeapCache 内部"分段并发 map + 定时淘汰 + 淘汰优先级"的运行机制与并发约定;② 掌握 size 记账、maxSize 上限、close() 资源释放等容易被忽略的坑;③ 获得一份可直接复用的"审查方法 + 探针实测 + 回归用例"实践范本。文中所有结论均以当前仓库源码(修复后状态)与测试用例为证据。
一、审查背景与方法
1.1 审查对象与基线
本次审查的靶子是 fountain 的 f_cache 模块——一个同时提供强引用缓存(HeapCache)与弱引用缓存(WeakHeapCache)的堆缓存组件。审查信息如下:
| 项 | 值 |
|---|---|
| 审查对象 | f_cache(强/弱引用堆缓存) |
| 基线 | sts/1.3.x = 7cd7863e |
| 审查分支 / worktree | review/f_cache @ .worktrees/review-f_cache |
| 审查日期 | 2026-10-05 |
| 审查方式 | 只读通读全部 8 个源文件(约 1100 行)+ std/仓库内依赖契约核对 + 临时探针实测 |
审查方式值得借鉴:只读通读保证不污染生产代码;依赖契约核对以本地官方文档为准(cangjie-coding / cangjie-doc-lookup 技能),逐一确认 LinkedBlockingQueue.remove() 的阻塞语义、ReadWriteLock 可重入、WeakRef+CleanupPolicy.DEFERRED、Timer.after 回调返回值、MapEntryView/entryView 等 std 契约;临时探针实测则用临时测试用例(跑完即删、未入库)把"读代码推断的问题"变成"可复现的失败证据"。
1.2 结论速览
| 严重度 | 条数 |
|---|---|
| 严重 | 3 |
| 中 | 5 |
| 低危 | 8 |
| 待验证 | 2 |
建议修复顺序:CACHE-1(JWT id 过期语义失效,安全相关)→ CACHE-2(maxSize 上限失效,内存风险)→ CACHE-3(size/isEmpty 失真)→ CACHE-4(段锁内跑用户代码)→ CACHE-5(线程/实例泄漏)→ CACHE-6(过期条目被"复活")→ CACHE-7(关闭后写入永不清理)→ CACHE-8(淘汰优先级偏老)。截至审查归档,18 条缺陷全部了结,用例由 1 条扩充到 27 条并全绿。
二、严重缺陷(3 条):正确性、安全与内存
三条严重缺陷全部集中在容量记账(size)与寿命参数两条主线上,且其中两条在仓库内已有真实使用点(f_data、f_orm、f_regex、f_jwt),属于"读代码能发现、跑起来立刻炸"的问题。
2.1 CACHE-1:新建键时 set(life!/dieAt) 的寿命参数被忽略
现象:HeapCache.set(key, value, life!/dieAt) 在新建键时没有使用本次调用传入的寿命,而是用了缓存级 maxLife。修复前 f_cache/src/HeapCache.cj 的 set 两个重载存在如下分支:
public func set(key: String, value: V, life!: Duration = this.maxLife, once!: Bool = false): ?V {
if (let Some(p) <- store.get(key)) {
synchronized(p.lock) {
let old = p.load()
p.store(value)
p.maxLife = life // ← 覆盖路径:life 生效 ✓
p.once = once
old
}
} else {
store.add(key, Priority<V>(key, value, maxLife, checkDuration, once)) // ← 新建路径:用的是缓存级 maxLife ✗
Option<V>.None
}
}
public func set(key: String, value: V, dieAt: DateTime): ?V {
set(key, value, life: dieAt - DateTime.now(), once: true) // ← dieAt 走 life 参数 ⇒ 新建时同样失效
}
影响是双向的:期望寿命短于 maxLife ⇒ 条目滞留过久;期望寿命长于 maxLife ⇒ 条目提前消失。默认 maxLife 为 5 s(见 f_cache/src/HeapCacheBuilder.cj 的 DEFAULT_HEAP_CACHE_MAX_LIFE),任何 life 参数在新建路径上都被它覆盖。
安全相关的真实使用点在 f_jwt/src/JwtIdCache.cj(HeapJwtIdCache 的 put 两条重载都是"新建键"路径):
public func put(id: T, expire: Duration): Unit {
cache.set(id.toString(), this, life: expire)
}
public func put(id: T, expireAt: DateTime): Unit {
cache.set(id.toString(), this, expireAt)
}
JWT id 缓存用于一次性 id(防重放)登记:若真实 token 有效期长于缓存级 maxLife,id 会提前被淘汰 ⇒ 同一 jti 可再次通过校验(重放面);反之则拒绝本应合法的请求。报告特别指出:getOrCompute 的三条重载都正确地把算出的寿命传给构造器,说明这是实现遗漏而非设计取舍。
修复(提交 3171d664):新建路径改为 Priority<V>(key, value, life, checkDuration, once)。life 的默认值就是 this.maxLife,因此不传 life 时行为不变;dieAt 重载自动恢复。修复后当前源码可见该改动已落地。
验证:新增用例 testSetLifeOnNewKey(见 f_cache/src/HeapCache_test.cj)——新建键 set(life=100ms)、已存在键同参数(对照)、新建键 set(dieAt=now+100ms),300 ms 后三者都断言不存在;checkDuration 取 30 s 以隔离定时清扫。修复前 1 PASSED / 1 FAILED,修复后 2/2 PASSED。
2.2 CACHE-2:getOrCompute 建的条目不计入 size,maxSize 上限完全失效
现象:ConcHashMap.computeIfAbsent 不记账 size。修复前 f_cache/src/ConcHashMap.cj 的该方法只是简单转发:
func computeIfAbsent(key: String, callable: () -> V): V {
segment(key).computeIfAbsent(key, callable)
}
而 HeapCache.getOrCompute 三条重载全部走这条路径,checkOverSize 的淘汰条件又是 store.size > maxSize ⇒ 经 getOrCompute 建立的条目永远不会参与 maxSize 淘汰;同时 remove 会对它们 decrSize ⇒ size 可变为负数,isEmpty()(size == 0)会谎报。
三处真实使用点(全部是 getOrCompute):
| 模块 | 位置 | 缓存 | 期望上限 |
|---|---|---|---|
| f_data | src/path/CacheDataPath.cj | HeapCache<DataPath>(maxLife: Duration.day, maxSize: 10000) |
≤ 10000 |
| f_orm | src/base/SqlDSL.cj | dslcache = HeapCache<ArrayList<SqlDSLPart>>(maxLife: Duration.day, maxSize: 10000) |
≤ 10000 |
| f_regex | src/RegexFromString.cj | CACHE = HeapCache<Regex>(maxLife: Duration.day, maxSize: 10000) |
≤ 10000 |
⇒ 三个缓存各自只受"1 天 + 键空间"约束,声明里的 maxSize: 10000 形同虚设:键空间大时(每条不同 SQL / 正则 / 路径都建一条)无界增长。
修复(提交 0e3d70d6):f_cache/src/SyncLinkedHashMap.cj 的 computeIfAbsent 改为 computeIfAbsentCounted(key, callable): (V, Bool)(第二个返回值表示本次是否真的新建),ConcHashMap.computeIfAbsent 在 added 时 incrSize()。两处类都是包内实现(全仓 grep 确认段级方法只有这一个调用方),公开 API 不变。
验证:testGetOrComputeAccountsSize(getOrCompute×5 ⇒ size==5、remove 一个 ⇒ size==4 且不为负)、testGetOrComputeObeysMaxSize(maxSize=2、getOrCompute×5、等 1 s ⇒ 存活数与 size 都 ≤2)。修复前 2 PASSED / 2 FAILED(size 实测 0;5 条全部存活),修复后 4/4 PASSED。
2.3 CACHE-3:add 覆盖已存在键多计 size、clear() 不归零
现象:修复前 ConcHashMap.add 无条件 incrSize(),clear() 清空各段后没有 size_.store(0):
func add(key: String, value: V): Option<V> {
let opt = segment(key).add(key, value)
incrSize() // ← 未判断 opt 是否 None(是否真的新增)
return opt
}
影响:size 只增不清 ⇒ ① HeapCache.clear() 之后 size 仍是旧值、isEmpty() 为 false;② checkOverSize 用 store.size > maxSize 判定 ⇒ 幻影计数会让真实条目被提前淘汰(刚 clear 完再写入时尤其明显);③ add 的覆盖路径虽被 HeapCache.set(先 get 再决定)绕开,但两线程同时 get=None 后都 add 的竞态下会多计。
修复(提交 14733baf):add 只在段级 add 返回 None(确为新增)时 incrSize();clear() 内 size_.store(0)(size_ 是 AtomicInt64)。destroy() 走 clear(),一并归零。当前源码 f_cache/src/ConcHashMap.cj 中两处均已按此实现。
验证:testAddOverwriteCountsOnce(同键 add×2 ⇒ size==1,再 add 一个新键 ⇒ 2)、testClearResetsSize(set×3 ⇒ 3;clear() ⇒ 0;再 set ⇒ 1;destroy() ⇒ 0)。修复前 4 PASSED / 2 FAILED,修复后 6/6 PASSED。
三、中等缺陷(5 条):并发契约、资源与淘汰语义
3.1 CACHE-4:用户代码在段写锁内执行
现象:removeIf 的谓词与 getOrCompute 的 callable 在段写锁内执行,会阻塞同段全部操作。修复前 f_cache/src/SyncLinkedHashMap.cj 的 computeIfAbsent 在 synchronized(wl) 内调用 callable()。
影响:getOrCompute 的 callable 在仓库里是昂贵操作——f_data 的 doCompile、f_regex 的正则编译、f_orm 的 cangjieLex+DSL 解析 ⇒ 一次未命中就会让该段所有键的读写(含其他线程)排队等待;removeIf 的谓词同理;若谓词/回调用另一线程回访同段会死锁(std 的 ReadWriteLock 可重入,同线程回读不死锁)。探针 P10 实测:谓词内 sleep(400 ms) 期间,同段 get = 292.87 ms,异段 get = 0.0228 ms(约 1.3 万倍差)。
修复(提交 b772f1a5,方案 C):
SyncLinkedHashMap.computeIfAbsentCounted把callable()移到段写锁之外(锁内只做"查 → 二次判定 → 写",重复计算的结果被丢弃);- 新增
removeIfOutside(读锁取快照 → 锁外跑谓词 → 写锁按 key 删,返回实际删除数);原removeIf改名removeIfLocked(谓词在写锁内,保留给定时清扫); HeapCache.checkTimeout走removeIfLocked;公开removeIf走两阶段。
契约变化(有意,已写入 f_cache/README.md「并发与约定」):① callable 在段锁外执行 ⇒ 同一键可能被并发计算多次、只有第一次的结果落库(纯计算/幂等 callable 无影响);② removeIf 是两阶段 ⇒"判定—删除"不再原子;③ 顺带写明 size 含"已过期但未清扫"条目的口径。
验证:testGetOrComputeComputesOnceWhenPresent(已存在时 callable 只被调用 1 次)、testGetOrComputeDoesNotHoldSegmentLock(callable 睡 400 ms,同段 get < 100 ms)、testRemoveIfDoesNotHoldSegmentLock。修复前 7 PASSED / 2 FAILED,修复后 9/9 PASSED。
3.2 CACHE-5:线程与实例泄漏
现象:每个 HeapCache 实例泄漏 1 个阻塞淘汰线程 + 1 条全局 atExit 强引用;WeakHeapCache 另泄漏 1 个 while(true) 清扫线程。根因链有三环:
- f_cache/src/HeapCache.cj 的
onEviction()用while (let (k, v) <- q.remove())消费淘汰队列,而 std 的LinkedBlockingQueue.remove()是阻塞出队(队列空则阻塞等待)、没有队列关闭语义 ⇒ 线程永远不会退出; ExitCallbacks.atExit(254, destroy)把每个实例注册进 f_base/src/signal.cj 的全局静态表(TreeMap<UInt16, ArrayList<() -> Unit>>,追加且从不清理)⇒ 该表强引用每个HeapCache实例 ⇒ 被应用丢弃的实例(连同它的线程)永远不会被 GC 回收;WeakHeapCache.init为每个实例 spawn 一个while (true) { removeIf; sleep(1s) }清扫线程,且没有 close/destroy 入口。
影响:长生命周期进程里反复创建缓存实例(例如按租户/按请求创建 HeapCacheStore)会累积线程与不可回收对象。
修复(提交 981e1005,后续补做 0b9d3240、fae91596):
- 两个缓存实现
Resource;alive换成closedFlag;新增内部线程句柄字段与轮询常量(HeapCache=EVICTION_POLL_INTERVAL = 100 ms;WeakHeapCache=CLEAN_INTERVAL = 1 s); - 消费线程改为"
q.remove(轮询间隔)+ 每轮检查Thread.currentThread.hasPendingCancellation",收到取消后把已入队的淘汰回调投递完再退出; - 新增
close()(置位 +Timer.cancel()+Future.cancel()+store.clear(),可重复调用)与isClosed();destroy()删除、全部调用点改close(); atExit注册改为只捕弱引用的闭包(WeakRef<HeapCache<V>>+CleanupPolicy.EAGER)⇒f_base的全局注册表不再是实例的强根,close()之后对象可被 GC 回收,"进程退出时若实例仍在 ⇒ 自动close()"的语义保持不变。
验证:testCloseStopsEvictionThread(原 testDestroyStopsEvictionThread)修复前卡满约 3.01 s 抛 TimeoutException,修复后约 0.42 ms 线程立即退出;testHeapCacheIsResource ≈100.8 ms、testWeakHeapCacheIsResource ≈1.01 s(分别对应两个线程的轮询周期)。平台相关:ExitCallbacks 整体被 @When[os != "Windows"] 包着,Windows 上 atExit 是空实现,该泄漏只在非 Windows 平台存在。
3.3 CACHE-6:once() / prolong() 可"复活"已过期条目
现象:清扫按 checkDuration 周期跑(默认 1 s),期间过期条目仍在 map 里 ⇒ get/contains 认为"不存在",而 once() 返回 true、prolong() 返回 true 并真的改变其寿命 ⇒ 同一条目在两个 API 集合里有两种存在性;prolong 还会把一个本该死掉的条目救活。
修复(提交 2e642e0b,方案 A:与 get/contains 同口径):once、prolong(key, life!, once!)、prolong(key, deathTime) 三个入口的 case Some(p) 加上 where !expired(p) 守卫 ⇒ 已过期(即使尚未被定时清扫)的条目一律按"不存在"处理,不能再被续期/复活;要续期请改用 set 重建。仓库内没有 once/prolong 的调用方(grep 确认),无下游影响。
验证:testOnceRejectsExpiredEntry、testProlongRejectsExpiredEntry —— 都是"set → set(life: 100ms) → 等 300 ms(< checkDuration)"后断言 contains、once、两个 prolong 全为 false,且续期被拒后 contains 仍为 false。修复前 12 PASSED / 2 FAILED,修复后 14/14 PASSED。
3.4 CACHE-7:关闭后再 set 的条目永不被清理
现象:修复前 destroy() 置 alive=false 并清空,但 set/get/getOrCompute 都没有 isClosed() 守卫 ⇒ 关闭之后写入的条目既没有过期清扫、也没有 maxSize 淘汰(定时器已取消)⇒ 只增不减的 map、size 永久虚高。
修复(提交 65e5bc8d,方案 A2):新增 private func ensureOpen()(关闭后抛 IllegalStateException('heap cache is closed')),HeapCache 的 16 个公开入口(get/contains/once/prolong×2/set×2/getOrDefault/getOrStore/getOrCompute×3/remove/removeIf/size/clear)全部先校验;close() 改为"置位 → Timer.cancel() → 主动 store.clear() → Future.cancel() → f.get() 等消费线程结束" ⇒ close 返回即"清理完成";回调投递抽出 notifyEviction(吞掉用户回调异常,否则消费线程会被杀死、之后淘汰全部静默失效)。WeakHeapCache 同样处理(9 个公开入口)。关闭语义已写入 README:关闭后一切操作抛 IllegalStateException(仅 isClosed/close 例外,close 可重复调用)。
验证:testOperationsAfterCloseThrow(16 个入口逐一断言抛 IllegalStateException,并验证 isClosed/close 幂等不抛)、testCloseClearsAndJoinsBeforeReturn(close 返回后 f.get(1 ms) 必须立即成功)。报告诚实标注:后一条在"修复前"那次运行是通过的(1 ms 窗口偶合 100 ms 轮询边界),因此作为修复后的保证性用例保留。仓库内使用方都不调用 close() 也不会关闭后复用实例,无下游影响。
3.5 CACHE-8:淘汰优先级的两处并发/逻辑缺陷
这是本报告最复杂的一条,包含两个子问题:
① 比较基线字段无锁读写竞争:Priority 的 lastCheckedTime、usedCountUtilLastChecked 是普通字段——定时线程在 checkOverSize 末尾批量写入(不持 p.lock),业务线程在 compare(被 PriorityQueue 调用)里无锁读取 ⇒ 无同步保证。修复:两个 getter 与 updateLastChecked(current) 都包进 synchronized(lock)(Mutex 可重入、compare 内逐个取锁不嵌套 ⇒ 无死锁面)。这是可见性/一致性问题,给不出确定性失败证据,属"同步型":只有代码层证明 + 回归用例。
② "保护新生"分支写反且含不可达分支:修复前 compare 的分支谱系与注释不符:
if (ageSub >= -1.0 && ageSub <= 1.0) {
cmp()
} else if (ageSub > 1.0) { // 保护新生
GT
} else if (age < -1.0) {
LT
} else {
cmp()
}
age = (现在 - 最后使用时间)/checkDuration在正常时钟下恒 ≥ 0 ⇒age < -1.0分支不可达(除非时钟回拨);- 注释说"保护新生",但只对
ageSub > 1.0(本对象更老)返回GT;本对象更新的一侧落到最后一个cmp()分支 ⇒ 保护逻辑不对称、疑似写反。用PriorityQueue(最小堆,add(3,1,2)后remove()= 1)钉死判定链:compare返回GT= 被保留、LT= 先淘汰。探针 P-c/P-d 实测修复前老条目存活、新条目被淘汰,与"保护新生"注释完全相反;且cmp()的第②③级otherX.compare(x)方向也偏老。
修复(三次提交:00ff79a5、21c9cf65、db3b55f6):年龄门对称化——ageSub > 1.0(本对象更老)⇒ LT(老的先淘汰);其余(本对象更新、且差超过一个生命周期)⇒ GT(留下);删掉不可达分支;cmp() ②~⑤ 四级 tie-break 全部改为与"保护新生"同向(本次周期内使用次数多者、最后使用更晚者、历史访问总量多者、出生更晚者优先保留)。语义按作者指示定为保护新生,已写入 f_cache/README.md。
既有用例 test() 的期望按新语义修正(重要,属语义变更):原断言"test2 存活、test3(最新)被淘汰"实际锁定的是"偏老"行为;修正为 test1 存活(周期内读多次)、test3 存活(更新的留下)、test2 被淘汰(更老的先走)。新增 3 条用例:testCompareProtectsNewEntryBeyondOneLifecycle(年龄差 1.5 个周期)、testCompareProtectsRecentlyUsedEntryWithinOneLifecycle(年龄差 0.2 个周期)、testEvictionInAgeGapProtectsNewEntry(端到端 maxSize=1、新旧各占一个分段)。修复前 17 PASSED / 3 FAILED,修复后 20/20 PASSED。
四、低危缺陷(8 条)与待验证项(2 条)
4.1 低危 8 条(全部已修复)
| 编号 | 问题 | 修复 |
|---|---|---|
CACHE-L1 |
ConcHashMapKeys.contains(all!) 是"任一包含"而非"全部包含"(f_cache/src/ConcHashMap.cj),且 4 个 Keys/Values 类在本仓库无使用点 |
改为"全部命中才 true"(与 std Collection.contains(all:) 一致;空集合按 vacuous truth 返回 true)。4 个类是包内可见,改语义不涉及公开 API。新增 f_cache/src/ConcHashMap_test.cj 用例。20→21 PASSED |
CACHE-L2 |
WeakHeapCache.get 的 lambda 返回值被丢弃(unused expression 编译警告);曾误判"miss 会插入空条目 ⇒ size 虚增" |
查证 std 文档:entryView 只有当回调把 value 置为非 None 时才新增条目,原实现只读不写 ⇒ 不会虚增 size,是写法/警告问题。get 改为直接 cache.get(...) 纯读取;set 去掉 try/finally 绕写法;weakRef() 补显式返回类型 |
CACHE-L3 |
WeakKey 把"键"放进弱引用(WeakRef<Box<String>>):内存紧张时键会被 GC ⇒ 值仍被强引用时条目静默消失、get 期间键可能失效 |
WeakKey 改持强引用(private let key: String),只让值保持 WeakRef<T>(CleanupPolicy.DEFERRED 不变)⇒ 隐患消除,顺带省掉每次 get/set 的两次分配;清扫线程条件简化为 v.value.isNone()。新建 f_cache/src/WeakHeapCache_test.cj(4 条)⇒ 全量 25/25 PASSED、编译警告 0 条 |
CACHE-L4 |
两处编译警告:HeapCache.cj:20 unused import 'std.env.atExit'、WeakHeapCache.cj:135 unused expression |
删掉未用 import;unused expression 由 L2 改写消除 ⇒ f_cache 自身编译警告 2 → 0 |
CACHE-L5 |
命名/文档细节:HeapCache.evicated 应为 expired 语义;README 未说明 WeakHeapCache 清扫有 1 s 延迟 |
evicated → expired(private 方法,不涉公开 API);README「并发与约定」新增 WeakHeapCache 条目 |
CACHE-L6 |
迭代一致性未文档化:SyncLinkedHashMap.iterator() 锁外创建底层迭代器、每次 next() 才取读锁;ConcHashMapIterator.next() 循环条件 cur <= m.concurrency 冗余 |
README 新增「迭代一致性」条目(弱一致);循环条件收紧为 cur < m.concurrency |
CACHE-L7 |
惰性过期与口径差:get 对已过期条目只返回 None 不摘除 ⇒ size 包含"已过期未清扫"条目(最长 checkDuration) |
文档路线:HeapCache 侧审查前已在 README 写明,本次补 WeakHeapCache 侧(值失效后最长 1 s 仍计入 size)。行为不变 |
CACHE-L8 |
用例覆盖极薄:整个模块只有 1 个用例(8.02 s,绝大部分是 sleep) |
CACHE-1~CACHE-8 修复过程中补到 20 条,随 L1~L3 再补 7 条 ⇒ 全模块 27 条全绿 |
4.2 待验证项
CACHE-V1(Priority.compare淘汰顺序是否符合设计):已了结——作者确认期望方向为保护新生,CACHE-8② 已按此重写并新增 3 条用例逐一固定。CACHE-V2(WeakRef条目在真实内存压力下的失效率):降级为观测项(作者决策,不单造压测)。理由:①CACHE-L3修复后"键被 GC 回收 ⇒ 条目静默消失"的前提已不存在;② 剩下的只有"值"被 GC 回收一种情形,而值被回收本就是弱引用缓存的正常语义;③ 仓颉无 GC 触发入口、DEFERRED策略下小规模压测不必然触发。四个使用模块各跑一遍全量用例:f_data104/104、f_regex3/3、f_jwt3/14(11 条 HMAC/密钥类 ERROR 属原有问题,主线同版本同样复现)、f_orm32/33(同一条ORMConfigTest.testPoolMaxWaiting在主线基线同样复现)⇒ 没有任何一条端到端失败与缓存行为相关。
五、模块结构与覆盖面积
5.1 f_cache 的结构
结合修复后的源码(f_cache/src),模块由两部分组成:
- 强引用缓存
HeapCache:定时线程(Timer.after自续期)+ 淘汰消费线程(每实例 1 个,按 100 ms 轮询)+ 分段并发 map; - 弱引用缓存
WeakHeapCache:std.collection.concurrent.ConcurrentHashMap+ 弱引用值(键已改强引用)+ 1 s 清扫线程; - 三个内部支撑件:
ConcHashMap:分段,段内SyncLinkedHashMap,读写锁,自维护size_(AtomicInt64);SyncLinkedHashMap:LinkedHashMap+ 读写锁;Priority:记录寿命/使用次数/出生时间,供淘汰排序(实现Comparable<Priority<V>>,见 f_cache/src/Priority.cj)。
已确认"无实例"的维度:无文件/网络/CFFI/原生内存/句柄类资源;无 std.reflect、无宏;无 ThreadLocal、无对象池。唯一的进程级静态可变状态是 f_base 的 ExitCallbacks 注册表(f_base/src/signal.cj,被 HeapCache 用来注册退出时 close())与各模块里的静态缓存实例(f_data/f_orm/f_regex 各一个)。无持久化/序列化;evictionCallback 是唯一对外回调(实测通路正常)。
5.2 仓库内使用面
| 模块 | 位置 | 用法 |
|---|---|---|
| f_data | src/path/CacheDataPath.cj | getOrCompute(DataPath 编译结果缓存,1 天 + 上限 10000) |
| f_orm | src/base/SqlDSL.cj | getOrCompute(DSL 解析结果缓存,1 天 + 上限 10000) |
| f_regex | src/RegexFromString.cj | getOrCompute(正则编译缓存,1 天 + 上限 10000) |
| f_jwt | src/JwtIdCache.cj | set(life:) / set(dieAt:)(一次性 id 防重放登记) |
| f_security | src/HeapCacheStore.cj | set 默认寿命(不受 CACHE-1 影响) |
| 聚合入口 | src/cache/cache.cj | 对外 re-export fountain::f_cache.* |
WeakHeapCache 在包外无任何使用者(用例除外)。
六、验证状态:从 1 条用例到 27 条全绿
6.1 修复前后对比
| 项 | 修复前 | 修复后 |
|---|---|---|
| 用例数 | 1(test,耗时 ≈ 8.02 s,主要是 sleep) |
27 条全绿(cjpm test --no-capture-output,SDK 1.3.0-alpha.20261001001050 / WSL Ubuntu-24.04) |
| 编译警告 | f_cache 自身 2 条 | 2 → 0 条 |
| 结论 | — | 严重 3 + 中 5 + 低危 8 全部了结(V1 已了结、V2 降级观测项) |
6.2 探针实测证据(临时用例,跑完即删)
| 探针 | 断言的现象 | 实测 |
|---|---|---|
| P1a/b/c | 新建键 set(life:) / set(dieAt:) 是否生效 |
新建 true(不生效)/已存在 false(生效)/dieAt true |
| P2a-e | getOrCompute 的 size 记账与 maxSize 淘汰 |
size=0;800 ms 后 5/5 存活;对照(set)2/5 |
| P3a/b/c | once/prolong 对已过期条目 |
contains=false;once=true;prolong=true 且复活 |
| P4 | ConcHashMapKeys.contains(all:) |
['b','a'] ⇒ true(任一命中) |
| P5 | WeakHeapCache 基本可用性 |
set→get=Some、getOrStore、remove 全部正常 |
| P6 | 淘汰回调通路(对照) | maxSize 淘汰触发回调 1 次 ✓ |
| P7/P8 | destroy() 语义 |
销毁后写入的条目过期仍计数:size=2 且不降 |
| P9a-c | ConcHashMap 记账 |
同键 add×2 ⇒ size=2;3 键 ⇒ 3;clear() 后 ⇒ 3 |
| P10 | 谓词持段写锁的阻塞面 | 同段 get 292.87 ms vs 异段 0.0228 ms |
6.3 基准与资源采样(cjpm bench + cjprof heap + /proc 探针)
基准(f_cache/src/HeapCache_bench.cj,单次运行中位数,Err% ≤ 11%):
| 用例 | 覆盖点 | Median |
|---|---|---|
benchGetHit |
命中:分段读锁 → Priority.load(含 CACHE-8 ① 新增的 p.lock) |
2.561 µs |
benchSetSameKey |
同键写:段写锁 + 覆盖 | 2.578 µs |
benchSetDistinctKeys |
不同键写:新建 Priority + size 记账 + 淘汰压力(键空间 2×maxSize) |
5.317 µs |
benchSetUnderEvictionPressure |
maxSize=1 两键交替写,定时淘汰持续竞争 |
3.925 µs |
⇒ CACHE-8 确认:① 新增的两处加锁没有给命中路径带来可见代价(2.56 µs,与"同键写"同量级);② 重写后的 compare/淘汰路径在持续竞争下无病态成本(3.9 µs)。过程说明:benchSetDistinctKeys 首版用无界键空间导致 OOM 崩溃,属基准设计问题(改 i % 2000 有界后通过),不是产品缺陷。
资源采样三连验证:
CACHE-4:修复后同段get延迟从 292.87 ms 降到 55 µs(约 5300 倍),与异段回到同一量级;CACHE-5:连续 50 轮 create+close 后线程数持平(10 线程,修复前每实例泄漏 1~2 个线程,50 轮至少 +75);cjprof heap -t快照里线程栈全是 unittest 框架自己的,没有缓存的定时器/消费/清扫线程;CACHE-2/CACHE-3:maxSize=1000的缓存经getOrCompute灌 20 000 个键 ⇒size记账跟得上真实条目数(修复前恒为 0)、静置 3 s 后size收口到 1000(上限生效)、RSS 从 95 696 kB 回落到 80 948 kB。
剩余未做:长稳压力(线程/实例累积速率)——已按"观测项 + 四模块端到端"方式结项。
七、审查方法沉淀与经验教训
7.1 方法论要点
- 只读通读 + 依赖契约核对:对 std 的
LinkedBlockingQueue.remove()阻塞语义、ReadWriteLock可重入性、WeakRef+CleanupPolicy.DEFERRED、Timer.after回调返回值等逐一核对官方文档,避免把"库的行为"误判为"自己的 bug"; - 探针实测代替静态猜测:每一条严重/中等问题都用临时探针给出"修复前失败、修复后通过"的成对证据(日志存于
/tmp/cache*_before/after.log); - 已排除的假设单独记录(避免后续重复怀疑):
removeIf谓词同线程回读同段不会死锁(ReadWriteLock可重入);淘汰回调不会丢(P6);WeakHeapCache基本读写正常(P5);Priority.compare第一层语义与现有用例一致,因此CACHE-8只列"疑似写反/不可达分支 + 无锁读取",不下"淘汰顺序错误"的结论; - 诚实标注证据强度:同步型问题(依赖并发时序,如
CACHE-8①)明确标注"只有代码层证明 + 回归用例";无 GC 触发入口的问题(如CACHE-5②)标注"无确定性用例可钉,验收 = 代码层论证 + 全量用例绿";偶合通过的用例(testCloseClearsAndJoinsBeforeReturn)诚实说明不作修复前失败证据。
7.2 对使用者的直接启示
- 用
getOrCompute缓存昂贵计算结果时,callable 应保持纯计算/幂等,不要在回调里做有副作用的操作(它可能在段锁外被并发执行多次,只有第一次的结果落库); size与get/contains口径不同:size会包含"已过期但未清扫"(最长一个checkDuration)和"值已失效但未清扫"(WeakHeapCache最长 1 s)的条目;HeapCache/WeakHeapCache都持有常驻内部线程,用完务必close():close()会主动清空、取消定时器、等内部线程结束(最长阻塞 100 ms / 1 s),之后任何操作抛IllegalStateException;进程退出时f_base的ExitCallbacks会自动close()(注册项持弱引用,不会钉住实例);- 淘汰顺序"保护新生":年龄差超过一个
checkDuration时直接淘汰更老的;一个周期内则比较使用次数、最后使用时间,更多/更晚者优先保留; - 已过期的条目无法通过
once/prolong复活,续期请用set重建。
复现命令(在对应 worktree 内):
source cangjie.sh后进入f_cache目录执行cjpm test --no-capture-output(基线 1/1,修复后 27/27)、cjpm bench(4 条基准)。本文所涉源码、测试与 README 均位于 f_cache 目录,聚合入口见 src/cache/cache.cj。