《Cocos 游戏开发入门》10.3 引用计数与资源释放

// src/assets/resource-manager.ts
interface CacheEntry {
  value: unknown;
  refCount: number;
  size: number;
  lastUsed: number;
}

export class ResourceManager {
  private readonly entries = new Map<string, CacheEntry>();
  private readonly budget: number;
  private used = 0;

  constructor(budget: number) {
    this.budget = budget;
  }

  /** 资源刚进内存时登记，引用计数从 0 起算 */
  put(uuid: string, value: unknown, size: number): void {
    const existing = this.entries.get(uuid);
    if (existing) {
      existing.value = value;
      return;
    }
    this.entries.set(uuid, { value, refCount: 0, size, lastUsed: performance.now() });
    this.used += size;
  }

  /** 取用资源：命中则计数 +1，并刷新使用时间 */
  retain(uuid: string): unknown {
    const entry = this.entries.get(uuid);
    if (!entry) return null;
    entry.refCount += 1;
    entry.lastUsed = performance.now();
    return entry.value;
  }

  /** 归还资源：计数 -1，归零后成为可回收候选 */
  release(uuid: string): void {
    const entry = this.entries.get(uuid);
    if (!entry) return;
    entry.refCount = Math.max(0, entry.refCount - 1);
    entry.lastUsed = performance.now();
    if (entry.refCount === 0) this.collect();
  }

  /** 当前内存里是否还留着这份资源 */
  has(uuid: string): boolean {
    return this.entries.has(uuid);
  }
}

  private collect(): void {
    if (this.used <= this.budget) return; // 未超预算：零引用资源留作缓存
    const candidates = [...this.entries.entries()]
      .filter(([, e]) => e.refCount === 0)
      .sort((a, b) => a[1].lastUsed - b[1].lastUsed); // 最久未用的排前面

    for (const [uuid, entry] of candidates) {
      if (this.used <= this.budget) break;
      this.evict(uuid, entry);
    }
  }

  private evict(uuid: string, entry: CacheEntry): void {
    this.entries.delete(uuid);
    this.used -= entry.size;
    entry.value = null; // 断开引用，交给 GC
  }

export interface AssetHandle<T> {
  readonly uuid: string;
  readonly value: T;
  dispose: () => void;
}

export function acquire<T>(mgr: ResourceManager, uuid: string): AssetHandle<T> | null {
  const value = mgr.retain(uuid) as T | null;
  if (value === null) return null;
  let disposed = false;
  return {
    uuid,
    value,
    dispose: () => {
      if (disposed) return; // 幂等：重复 dispose 只生效一次
      disposed = true;
      mgr.release(uuid);
    },
  };
}

// 反例：每个方块都注册了指向关卡对象的回调，关卡对象又持有所有方块
level.onScoreChange = () => {
  this.playSound(); // 闭包捕获了 this（关卡），而关卡持有 blocks 数组
};

  /** 诊断用：列出疑似泄漏的条目 */
  suspectLeaks(idleMs = 60_000): string[] {
    const now = performance.now();
    const out: string[] = [];
    for (const [uuid, e] of this.entries) {
      if (e.refCount > 0 && now - e.lastUsed > idleMs) out.push(uuid);
    }
    return out;
  }

import { describe, expect, it } from 'vitest';
import { ResourceManager } from '../src/assets/resource-manager';

describe('资源引用计数', () => {
  it('计数归零不立即释放，超预算才按 LRU 淘汰', () => {
    const mgr = new ResourceManager(100); // 预算 100 字节
    mgr.put('a', { img: 'a' }, 60);
    mgr.put('b', { img: 'b' }, 60); // 合计 120，已超预算

    mgr.retain('a');
    mgr.retain('b');
    expect(mgr.suspectLeaks(0)).toEqual([]); // 两个都在用，不算泄漏

    mgr.release('b');
    // b 计数归零且总用量超预算，应被淘汰；a 仍被持有，必须留下
    expect(mgr.has('a')).toBe(true);
    expect(mgr.has('b')).toBe(false);
  });

  it('重复释放不会把计数减成负数', () => {
    const mgr = new ResourceManager(1000);
    mgr.put('a', {}, 10);
    mgr.retain('a');
    mgr.release('a');
    mgr.release('a'); // 多还一次
    expect(mgr.suspectLeaks(0)).toEqual([]);
  });
});

import { assetManager, resources, SpriteFrame } from 'cc';

let coinFrame: SpriteFrame | null = null;

resources.load('textures/coin/spriteFrame', SpriteFrame, (err, sf) => {
  if (err) return;
  coinFrame = sf;
  sf.addRef(); // 手动持有，阻止被自动释放
  console.log(sf.refCount); // 当前引用数

  // 不再需要时归还，计数归零且允许自动释放则被回收
  sf.decRef();
});

// 也可以由管理器直接释放某个资源，不必自己维护计数
if (coinFrame) assetManager.releaseAsset(coinFrame);