《游戏引擎实现原理》1.3 引用计数、生命周期与释放

// file: src/subsys/resource/refcount.ts
// tier: L1
// verify: npx vitest run src/subsys/resource/refcount.test.ts
//
// helio 资源管线：引用计数与生命周期。
// 每个资源有一个引用计数；计数归零不立刻释放，而是挂进「待释放」队列，
// 由帧末的 collect() 统一释放——这样同一帧内的 re-entrant 释放不会踩到悬空对象，
// 也让「刚归零又被重新引用」的情况（resurrect）得以幸免。

/** 任何持有 GPU / 内存资源的对象都实现它，在 collect 时被调用。 */
export interface Disposable {
  dispose(): void;
}

interface Slot<T> {
  readonly guid: string;
  refs: number;
  readonly payload: T;
  pendingFree: boolean;
}

/**
 * 资源引用表。
 *
 * 语义对齐 shared_ptr / weak_ptr：
 *   - acquire：计数 +1，资源不存在则用工厂创建；若正等待释放则「复活」；
 *   - release：计数 -1，归零时挂入待释放队列（不立即 dispose）；
 *   - collect：帧末统一释放队列里的资源，返回释放个数；
 *   - peek：只读，不改计数，用于「看一眼还在不在」。
 */
export class ResourceTable<T extends Disposable> {
  #create: (guid: string) => T;
  #slots = new Map<string, Slot<T>>();
  #pendingFree: string[] = [];
  #disposeCalls = 0;

  constructor(create: (guid: string) => T) {
    this.#create = create;
  }

  /** 已释放的资源总数（含复活后再次释放）。 */
  get disposeCalls(): number {
    return this.#disposeCalls;
  }

  /** 引用计数 +1；资源不存在则创建，等待释放则复活。 */
  acquire(guid: string): T {
    let slot = this.#slots.get(guid);
    if (slot === undefined) {
      slot = { guid, refs: 0, payload: this.#create(guid), pendingFree: false };
      this.#slots.set(guid, slot);
    } else if (slot.pendingFree) {
      // 复活：从待释放队列里摘掉，保留原 payload。
      slot.pendingFree = false;
      const i = this.#pendingFree.indexOf(guid);
      if (i >= 0) this.#pendingFree.splice(i, 1);
    }
    slot.refs++;
    return slot.payload;
  }

  /** 引用计数 -1。归零则挂入待释放队列，返回 true；计数非法则抛错。 */
  release(guid: string): boolean {
    const slot = this.#slots.get(guid);
    if (slot === undefined) throw new Error(`release 未知资源：${guid}`);
    if (slot.refs <= 0) throw new Error(`release 计数已为 0：${guid}`);
    slot.refs--;
    if (slot.refs === 0) {
      slot.pendingFree = true;
      this.#pendingFree.push(guid);
      return true;
    }
    return false;
  }

  /** 帧末调用：释放所有待释放资源，返回释放个数。 */
  collect(): number {
    if (this.#pendingFree.length === 0) return 0;
    const batch = this.#pendingFree;
    this.#pendingFree = [];
    let n = 0;
    for (const guid of batch) {
      const slot = this.#slots.get(guid);
      if (slot === undefined || !slot.pendingFree) continue; // 中途复活
      slot.payload.dispose();
      this.#disposeCalls++;
      this.#slots.delete(guid);
      n++;
    }
    return n;
  }

  refcount(guid: string): number {
    return this.#slots.get(guid)?.refs ?? 0;
  }

  /** 资源是否存在（存活或等待释放都算存在）。 */
  has(guid: string): boolean {
    return this.#slots.has(guid);
  }

  /** 只读访问，不改引用计数。资源不存在返回 undefined。 */
  peek(guid: string): T | undefined {
    return this.#slots.get(guid)?.payload;
  }

  /** 当前仍被持有的资源（refs > 0），用于泄漏排查。 */
  leaks(): string[] {
    const out: string[] = [];
    for (const slot of this.#slots.values()) {
      if (slot.refs > 0) out.push(slot.guid);
    }
    return out.sort();
  }

  /** 待释放队列长度（尚未 collect）。 */
  get pendingCount(): number {
    return this.#pendingFree.length;
  }
}

// file: src/subsys/resource/refcount-demo.ts
// tier: B
// verify: node src/subsys/resource/refcount-demo.ts
//
// 1) 演示延迟释放：材质在 collect 里被释放时，它的 dispose 又去 release 它持有的 mesh，
//    这次 release 只是把 mesh 挂进队列，留到下一次 collect 才真正释放——避免在遍历
//    释放队列的过程中递归释放，踩到正在被处理的状态；
// 2) 量一次 acquire/release 的吞吐。

import { ResourceTable } from './refcount.ts';
import type { Disposable } from './refcount.ts';

const log: string[] = [];

class Node implements Disposable {
  readonly guid: string;
  /** 释放本节点时要级联做的事（例如释放它持有的子资源）。 */
  onDispose: (() => void) | null = null;
  constructor(guid: string) {
    this.guid = guid;
  }
  dispose(): void {
    log.push(`dispose ${this.guid}`);
    if (this.onDispose) this.onDispose();
  }
}

const table = new ResourceTable<Node>((guid) => new Node(guid));

const mesh = table.acquire('mesh.island'); // mesh refs = 1
const mat = table.acquire('material.terrain'); // 材质 refs = 1
table.acquire('material.terrain'); // 场景也持有材质，refs = 2
mat.onDispose = () => table.release('mesh.island'); // 材质释放时级联释放 mesh

log.push('--- 帧末：场景释放材质 ---');
table.release('material.terrain'); // refs = 1
table.release('material.terrain'); // refs = 0，挂入待释放队列
log.push(`待释放队列=${table.pendingCount}`);

log.push('--- collect #1 ---');
log.push(`本次释放 ${table.collect()} 个`);
log.push(`mesh 仍存活=${table.has('mesh.island')} refs=${table.refcount('mesh.island')}`);
log.push(`待释放队列=${table.pendingCount}`);

log.push('--- collect #2：mesh 现在才被释放 ---');
log.push(`本次释放 ${table.collect()} 个`);
log.push(`mesh 仍存活=${table.has('mesh.island')}`);
console.log(log.join('\n'));

// 吞吐：连续 acquire/release 同一个资源。
const N = 1_000_000;
const t0 = performance.now();
for (let i = 0; i < N; i++) {
  table.acquire('mesh.island');
  table.release('mesh.island');
}
const ms = performance.now() - t0;
table.collect();
console.log(`\nacquire+release 各 ${N} 次：${ms.toFixed(1)}ms  ${(N / (ms / 1000) / 1e6).toFixed(2)} M ops/s`);

--- 帧末：场景释放材质 ---
待释放队列=1
--- collect #1 ---
dispose material.terrain
本次释放 1 个
mesh 仍存活=true refs=0
待释放队列=1
--- collect #2：mesh 现在才被释放 ---
dispose mesh.island
本次释放 1 个
mesh 仍存活=false

acquire+release 各 1000000 次：48.0ms  20.84 M ops/s

// snippet: 复活与防 double free，摘自 src/subsys/resource/refcount.test.ts
// 归零后、collect 前重新引用 → 复活，保留原 payload
const first = table.acquire('t.c');
table.release('t.c');                 // 归零，待释放
const second = table.acquire('t.c');  // 复活
expect(second).toBe(first);           // 同一对象，没有重建
expect(table.collect()).toBe(0);      // 队列已空，不会被释放

// 计数为 0 时再 release → 抛错
table.acquire('t.b');
table.release('t.b');
expect(() => table.release('t.b')).toThrow(/计数已为 0/);