《游戏引擎实现原理》5.3 内存标签、预算与泄漏检测

// file: src/core/memory-tags.ts
// tier: L1
// verify: npx vitest run src/core/memory-tags.test.ts
//
// helio 内核：内存标签、预算与泄漏检测。
// 每个分配都要挂一个「它属于哪个子系统」的标签，跟踪器按标签汇总
// 当前/峰值占用、比对预算；再用「分配计数快照对比」在帧末抓漏。

export const MemoryTag = {
  Rendering: "Rendering",
  Audio: "Audio",
  Physics: "Physics",
  Gameplay: "Gameplay",
  Asset: "Asset",
  Unknown: "Unknown",
} as const;

export type MemoryTag = (typeof MemoryTag)[keyof typeof MemoryTag];

export interface TagUsage {
  readonly tag: MemoryTag;
  readonly current: number;
  readonly peak: number;
  readonly live: number;
  readonly budget: number | null;
  readonly overBudget: boolean;
}

export interface LeakReport {
  readonly tag: MemoryTag;
  readonly delta: number;
}

/** 一次分配的凭据；调用 `free()` 归还。重复归还会被忽略。 */
export interface Allocation {
  readonly tag: MemoryTag;
  readonly bytes: number;
  free(): void;
}

export class MemoryTracker {
  readonly #current = new Map<MemoryTag, number>();
  readonly #peak = new Map<MemoryTag, number>();
  readonly #live = new Map<MemoryTag, number>();
  readonly #budget = new Map<MemoryTag, number>();
  #warn: (msg: string) => void;

  constructor(warn?: (msg: string) => void) {
    this.#warn = warn ?? (() => {});
  }

  setBudget(tag: MemoryTag, bytes: number): void {
    this.#budget.set(tag, bytes);
  }

  /** 记一笔分配，返回可归还的凭据。 */
  allocate(tag: MemoryTag, bytes: number): Allocation {
    if (!Number.isFinite(bytes) || bytes < 0) {
      throw new RangeError(`bytes must be a non-negative number, got ${bytes}`);
    }
    const cur = (this.#current.get(tag) ?? 0) + bytes;
    this.#current.set(tag, cur);
    if (cur > (this.#peak.get(tag) ?? 0)) this.#peak.set(tag, cur);
    this.#live.set(tag, (this.#live.get(tag) ?? 0) + 1);
    const budget = this.#budget.get(tag);
    if (budget !== undefined && cur > budget) {
      this.#warn(`[memory] ${tag} over budget: ${cur} > ${budget} B`);
    }
    let freed = false;
    return {
      tag,
      bytes,
      free: () => {
        if (freed) return;
        freed = true;
        const now = (this.#current.get(tag) ?? 0) - bytes;
        this.#current.set(tag, now < 0 ? 0 : now);
        this.#live.set(tag, (this.#live.get(tag) ?? 0) - 1);
      },
    };
  }

  usage(tag: MemoryTag): TagUsage {
    const budget = this.#budget.get(tag) ?? null;
    const current = this.#current.get(tag) ?? 0;
    return {
      tag,
      current,
      peak: this.#peak.get(tag) ?? 0,
      live: this.#live.get(tag) ?? 0,
      budget,
      overBudget: budget !== null && current > budget,
    };
  }

  totalCurrent(): number {
    let t = 0;
    for (const v of this.#current.values()) t += v;
    return t;
  }

  /** 当前「未归还」的分配笔数快照，供帧末比对。 */
  snapshot(): Map<MemoryTag, number> {
    return new Map(this.#live);
  }

  /** 对比快照：返回计数变大的标签（= 本帧没有配对的释放）。 */
  diff(before: Map<MemoryTag, number>): LeakReport[] {
    const out: LeakReport[] = [];
    for (const [tag, now] of this.#live) {
      const was = before.get(tag) ?? 0;
      if (now > was) out.push({ tag, delta: now - was });
    }
    return out;
  }
}

/**
 * 一帧的泄漏检测器：`begin()` 记下快照，`end()` 对比。
 * 用法：begin → 跑一帧逻辑 → end；未配对的分配会被列出。
 */
export class FrameLeakDetector {
  readonly #tracker: MemoryTracker;
  #before: Map<MemoryTag, number> | null = null;
  #onLeak: (reports: LeakReport[]) => void;

  constructor(tracker: MemoryTracker, onLeak?: (reports: LeakReport[]) => void) {
    this.#tracker = tracker;
    this.#onLeak = onLeak ?? (() => {});
  }

  begin(): void {
    this.#before = this.#tracker.snapshot();
  }

  end(): LeakReport[] {
    if (this.#before === null) throw new Error("FrameLeakDetector.end() before begin()");
    const reports = this.#tracker.diff(this.#before);
    this.#before = null;
    if (reports.length > 0) this.#onLeak(reports);
    return reports;
  }
}

// file: bench/memory-leak-demo.ts
// tier: B
// 运行：node bench/memory-leak-demo.ts
// 模拟《微光岛》一帧：渲染/音频各分配并释放，Gameplay 故意忘记释放。

import { FrameLeakDetector, MemoryTag, MemoryTracker } from '../src/core/memory-tags.ts';

const tracker = new MemoryTracker((m) => console.log(`WARN ${m}`));
tracker.setBudget(MemoryTag.Rendering, 16 * 1024);

const leaks: string[] = [];
const detector = new FrameLeakDetector(tracker, (reports) => {
  for (const r of reports) leaks.push(`${r.tag} +${r.delta}`);
});

function runFrame(n: number, forgetGameplay: boolean): void {
  detector.begin();
  const rt = tracker.allocate(MemoryTag.Rendering, 4096); // 本帧渲染临时内存
  const at = tracker.allocate(MemoryTag.Audio, 1024);
  const gp = tracker.allocate(MemoryTag.Gameplay, 256); // 实体组件
  rt.free();
  at.free();
  if (!forgetGameplay) gp.free(); // 忘记释放 → 泄漏
  const reports = detector.end();
  console.log(
    `frame ${n}: Rendering=${tracker.usage(MemoryTag.Rendering).current} B ` +
      `Gameplay=${tracker.usage(MemoryTag.Gameplay).current} B ` +
      `live=${tracker.usage(MemoryTag.Gameplay).live} leaks=${JSON.stringify(reports)}`,
  );
}

runFrame(0, false); // 干净帧
runFrame(1, false); // 干净帧
runFrame(2, true); // 泄漏帧
runFrame(3, false); // 后续帧：Gameplay 仍挂着未释放的 256 B

console.log(`total leaks detected: ${leaks.length} -> ${leaks.join(', ')}`);
console.log(`Gameplay peak = ${tracker.usage(MemoryTag.Gameplay).peak} B`);

frame 0: Rendering=0 B Gameplay=0 B live=0 leaks=[]
frame 1: Rendering=0 B Gameplay=0 B live=0 leaks=[]
frame 2: Rendering=0 B Gameplay=256 B live=1 leaks=[{"tag":"Gameplay","delta":1}]
frame 3: Rendering=0 B Gameplay=256 B live=1 leaks=[]
total leaks detected: 1 -> Gameplay +1
Gameplay peak = 512 B