《游戏引擎实现原理》5.1 对象池与 freelist

// file: src/core/object-pool.ts
// tier: L1
// verify: npx vitest run src/core/object-pool.test.ts
//
// helio 内核：定长对象池 + 空闲链表（freelist）。
// 与 4.x 的 arena 不同，池化保留「对象身份」——同一个实例被反复取出、
// 复位、放回，因此适合子弹、粒子、音频源这类「生命周期短、字段形状固定」的实体。

/** 池耗尽时的策略：抛错，或临时扩容。 */
export type ExhaustionPolicy = "throw" | "grow";

export interface PoolStats {
  /** 当前容量（grow 策略下会变大）。 */
  readonly capacity: number;
  /** 空闲链表里的对象数。 */
  readonly free: number;
  /** 正在被使用的对象数。 */
  readonly inUse: number;
  /** 累计真实构造次数（池的核心收益指标）。 */
  readonly created: number;
  /** 累计「从空闲链表里取到」的次数。 */
  readonly recycled: number;
  /** 累计触到容量上限的次数。 */
  readonly exhausted: number;
}

export interface ObjectPoolOptions<T> {
  create: () => T;
  reset: (item: T) => void;
  initial: number;
  policy?: ExhaustionPolicy;
}

/**
 * 定长对象池。预分配 `initial` 个实例塞进空闲链表；
 * `acquire()` 从链表尾弹出，`release()` 复位后压回。
 */
export class ObjectPool<T> {
  readonly #create: () => T;
  readonly #reset: (item: T) => void;
  readonly #policy: ExhaustionPolicy;
  #free: T[];
  #capacity: number;
  #inUse = 0;
  #created = 0;
  #recycled = 0;
  #exhausted = 0;

  constructor(opts: ObjectPoolOptions<T>) {
    if (!Number.isInteger(opts.initial) || opts.initial < 0) {
      throw new RangeError(`initial must be a non-negative integer, got ${opts.initial}`);
    }
    this.#create = opts.create;
    this.#reset = opts.reset;
    this.#policy = opts.policy ?? "throw";
    this.#capacity = opts.initial;
    this.#free = [];
    for (let i = 0; i < opts.initial; i++) {
      this.#free.push(this.#create());
      this.#created++;
    }
  }

  get capacity(): number {
    return this.#capacity;
  }

  get inUse(): number {
    return this.#inUse;
  }

  get stats(): PoolStats {
    return {
      capacity: this.#capacity,
      free: this.#free.length,
      inUse: this.#inUse,
      created: this.#created,
      recycled: this.#recycled,
      exhausted: this.#exhausted,
    };
  }

  /** 取一个对象：优先复用空闲链表，链表空则构造（或按策略扩容/抛错）。 */
  acquire(): T {
    const reused = this.#free.pop();
    if (reused !== undefined) {
      this.#recycled++;
      this.#inUse++;
      return reused;
    }
    if (this.#created >= this.#capacity) {
      this.#exhausted++;
      if (this.#policy === "throw") {
        throw new RangeError(
          `ObjectPool exhausted: ${this.#inUse} in use, capacity ${this.#capacity}`,
        );
      }
      this.#capacity++;
    }
    const fresh = this.#create();
    this.#created++;
    this.#inUse++;
    return fresh;
  }

  /** 复位后放回空闲链表。重复 release 同一对象会破坏计数，故显式拦截。 */
  release(item: T): void {
    if (this.#inUse <= 0) {
      throw new RangeError("ObjectPool.release called with nothing in use");
    }
    this.#reset(item);
    this.#free.push(item);
    this.#inUse--;
  }

  /** 池中空闲对象数——用来判断「池是否开得太大」。 */
  get freeCount(): number {
    return this.#free.length;
  }
}

// snippet: bench/object-pool-bench.ts 的核心循环
function churnPool(): { ms: number; created: number } {
  const pool = new ObjectPool<Particle>({
    create: makeParticle, reset: resetParticle, initial: 1024,
  });
  const t0 = performance.now();
  for (let i = 0; i < N; i++) {
    const p = pool.acquire();
    p.x = i; p.life = 1; sink += p.x;
    pool.release(p);
  }
  return { ms: performance.now() - t0, created: pool.stats.created };
}

function churnNew(): number {
  const t0 = performance.now();
  for (let i = 0; i < N; i++) {
    const p: Particle = { x: 0, y: 0, vx: 0, vy: 0, life: 0, alive: false };
    p.x = i; p.life = 1; sink += p.x; // p 在此失去引用，交给 GC
  }
  return performance.now() - t0;
}

// file: src/core/object-pool.test.ts
// tier: L1
// verify: npx vitest run src/core/object-pool.test.ts
import { describe, expect, it } from 'vitest';
import { ObjectPool } from './object-pool.ts';

interface Bullet {
  x: number;
  y: number;
  vx: number;
  vy: number;
  alive: boolean;
}

function makeBullet(): Bullet {
  return { x: 0, y: 0, vx: 0, vy: 0, alive: false };
}

function resetBullet(b: Bullet): void {
  b.x = 0;
  b.y = 0;
  b.vx = 0;
  b.vy = 0;
  b.alive = false;
}

function newPool(initial: number, policy?: 'throw' | 'grow'): ObjectPool<Bullet> {
  return new ObjectPool<Bullet>({ create: makeBullet, reset: resetBullet, initial, policy });
}

describe('ObjectPool', () => {
  it('预分配不重复构造，且 acquire 复用同一实例', () => {
    const pool = newPool(4);
    expect(pool.stats.created).toBe(4);
    const a = pool.acquire();
    pool.release(a);
    const b = pool.acquire();
    expect(b).toBe(a); // 复用同一实例
    expect(pool.stats.recycled).toBe(2); // 两次 acquire 都来自空闲链表
    expect(pool.stats.created).toBe(4); // 全程没有新增构造
  });

  it('release 会复位字段', () => {
    const pool = newPool(1);
    const b = pool.acquire();
    b.x = 42;
    b.alive = true;
    pool.release(b);
    const again = pool.acquire();
    expect(again.x).toBe(0);
    expect(again.alive).toBe(false);
  });

  it('耗尽时 throw 策略抛 RangeError', () => {
    const pool = newPool(1, 'throw');
    pool.acquire();
    expect(() => pool.acquire()).toThrow(RangeError);
    expect(pool.stats.exhausted).toBe(1);
  });

  it('耗尽时 grow 策略扩容并构造新对象', () => {
    const pool = newPool(1, 'grow');
    const a = pool.acquire();
    const b = pool.acquire();
    expect(b).not.toBe(a);
    expect(pool.stats.created).toBe(2);
    expect(pool.stats.capacity).toBe(2);
  });

  it('inUse / free 计数守恒', () => {
    const pool = newPool(3);
    const xs = [pool.acquire(), pool.acquire()];
    expect(pool.stats.inUse).toBe(2);
    expect(pool.freeCount).toBe(1);
    pool.release(xs[0]!);
    expect(pool.stats.inUse).toBe(1);
    expect(pool.freeCount).toBe(2);
  });

  it('空池 release 抛错（防重复归还）', () => {
    const pool = newPool(2);
    expect(() => pool.release(makeBullet())).toThrow(RangeError);
  });
});