《游戏引擎实现原理》4.2 线性 arena 与栈式分配器

aligned = (offset + alignment - 1) & ~(alignment - 1)

// file: src/core/arena.ts
// tier: L1
// verify: npx vitest run src/core/arena.test.ts
//
// helio 内核：线性 arena 分配器。
// 底层是一块 ArrayBuffer + typed array 视图——buffer 的内容不走 JS 堆，
// 这是本套书里「真手动内存」的立足点。

export type ByteOffset = number;

/** 线性 arena：只前进，不回收；`reset()` 一次性释放全部。 */
export class Arena {
  readonly #buffer: ArrayBuffer;
  readonly #bytes: Uint8Array;
  readonly #f32: Float32Array;
  readonly #u32: Uint32Array;
  #offset = 0;
  #highWater = 0;

  constructor(capacityBytes: number) {
    if (!Number.isInteger(capacityBytes) || capacityBytes <= 0) {
      throw new RangeError(`Arena capacity must be a positive integer, got ${capacityBytes}`);
    }
    this.#buffer = new ArrayBuffer(capacityBytes);
    this.#bytes = new Uint8Array(this.#buffer);
    this.#f32 = new Float32Array(this.#buffer);
    this.#u32 = new Uint32Array(this.#buffer);
  }

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

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

  /** 峰值占用，用于评估容量是否合理。 */
  get highWaterMark(): number {
    return this.#highWater;
  }

  get remaining(): number {
    return this.#buffer.byteLength - this.#offset;
  }

  /** 按 alignment（必须是 2 的幂）向上对齐当前偏移后推进。 */
  #bump(sizeBytes: number, alignment: number): ByteOffset {
    const aligned = (this.#offset + alignment - 1) & ~(alignment - 1);
    const end = aligned + sizeBytes;
    if (end > this.#buffer.byteLength) {
      throw new RangeError(
        `Arena out of memory: need ${sizeBytes} B @ align ${alignment}, ` +
          `have ${this.#buffer.byteLength - aligned} B left`,
      );
    }
    this.#offset = end;
    if (end > this.#highWater) this.#highWater = end;
    return aligned;
  }

  allocBytes(sizeBytes: number, alignment = 8): ByteOffset {
    return this.#bump(sizeBytes, alignment);
  }

  allocF32(count: number): ByteOffset {
    return this.#bump(count * 4, 4);
  }

  allocU32(count: number): ByteOffset {
    return this.#bump(count * 4, 4);
  }

  /** 返回可读写的 f32 视图（与 arena 共享底层 buffer，零拷贝）。 */
  f32View(byteOffset: ByteOffset, count: number): Float32Array {
    return this.#f32.subarray(byteOffset >> 2, (byteOffset >> 2) + count);
  }

  u32View(byteOffset: ByteOffset, count: number): Uint32Array {
    return this.#u32.subarray(byteOffset >> 2, (byteOffset >> 2) + count);
  }

  byteView(byteOffset: ByteOffset, count: number): Uint8Array {
    return this.#bytes.subarray(byteOffset, byteOffset + count);
  }

  /** 一次性归还全部内存（不回退 buffer，只是把偏移归零）。 */
  reset(): void {
    this.#offset = 0;
  }

  /**
   * 把偏移回退到更早的位置。仅供栈式分配器使用——
   * 回退后原先分配的区块视为失效，再次分配会覆盖它们。
   */
  rewindTo(byteOffset: ByteOffset): void {
    if (byteOffset < 0 || byteOffset > this.#offset) {
      throw new RangeError(`rewindTo(${byteOffset}) out of range [0, ${this.#offset}]`);
    }
    this.#offset = byteOffset;
  }
}

/** 栈式分配器：支持把偏移恢复到标记点，适合「帧内临时内存」。 */
export class ScratchArena {
  readonly arena: Arena;
  #mark = 0;

  constructor(capacityBytes: number) {
    this.arena = new Arena(capacityBytes);
  }

  mark(): ByteOffset {
    this.#mark = this.arena.used;
    return this.#mark;
  }

  release(): void {
    this.arena.rewindTo(this.#mark);
  }
}

// file: src/core/arena.test.ts
// tier: L1
// verify: npx vitest run src/core/arena.test.ts

import { describe, expect, it } from 'vitest';
import { Arena, ScratchArena } from './arena.ts';

describe('Arena', () => {
  it('按对齐推进偏移', () => {
    const a = new Arena(1024);
    expect(a.allocBytes(3, 1)).toBe(0);
    expect(a.allocBytes(4, 4)).toBe(4); // 3 → 对齐到 4
    expect(a.used).toBe(8);
  });

  it('越界抛 RangeError', () => {
    const a = new Arena(16);
    expect(() => a.allocBytes(32)).toThrow(RangeError);
  });

  it('f32 视图零拷贝共享底层 buffer', () => {
    const a = new Arena(1024);
    const off = a.allocF32(4);
    const v = a.f32View(off, 4);
    v[0] = 1.5;
    v[3] = -2.25;
    expect(a.f32View(off, 4)[0]).toBeCloseTo(1.5);
    expect(a.f32View(off, 4)[3]).toBeCloseTo(-2.25);
  });

  it('highWaterMark 记录峰值', () => {
    const a = new Arena(1024);
    a.allocBytes(100);
    a.allocBytes(50);
    expect(a.highWaterMark).toBeGreaterThanOrEqual(150);
  });

  it('reset 后偏移归零但 buffer 复用', () => {
    const a = new Arena(1024);
    a.allocBytes(500);
    a.reset();
    expect(a.used).toBe(0);
    expect(a.capacity).toBe(1024);
  });
});

describe('ScratchArena', () => {
  it('mark/release 回退临时分配', () => {
    const s = new ScratchArena(1024);
    s.arena.allocF32(16);
    const before = s.arena.used;
    s.mark();
    s.arena.allocF32(64);
    expect(s.arena.used).toBeGreaterThan(before);
    s.release();
    expect(s.arena.used).toBe(before);
  });

  it('rewindTo 拒绝前向回退', () => {
    const s = new ScratchArena(1024);
    s.mark();
    s.arena.allocF32(16);
    expect(() => s.arena.rewindTo(9999)).toThrow(RangeError);
  });
});

allocBytes(3,1) -> 0
allocBytes(4,4) -> 4        # 3 向上对齐到 4
used -> 8
highWaterMark -> 162        # 8 + 100 → 108，再 +50 对齐到 112 → 162
after reset used -> 0  capacity -> 1024
during scratch used -> 320  before -> 64   # 64 + 64*4 = 320
after release used -> 64