《移动游戏产品的架构·客户端与移动运行时》6.1 资源句柄、引用计数与生命周期

// file: src/resource/graph.ts
// tier: L1
// verify: node --test test/resource/graph.test.ts

import { fail, ok, type Result } from "../core/result.ts";

export type ResourceKind = "texture" | "atlas" | "audio" | "config";

export interface ResourceSpec {
  readonly id: string;
  readonly kind: ResourceKind;
  readonly sizeBytes: number;
}

export interface Handle {
  readonly id: number;
  readonly key: string;
  readonly generation: number;
  readonly owner: string;
}

export interface Loader {
  load(spec: ResourceSpec): Result<number, string>;
}

export type ResourceError =
  | "unknown-key"
  | "unknown-handle"
  | "stale-handle"
  | "double-release"
  | "load-failed"
  | "invalid-size"
  | "duplicate-key";

export interface ReleaseOutcome {
  readonly key: string;
  readonly freed: boolean;
  readonly freedBytes: number;
}

export interface OwnerReleaseReport {
  readonly owner: string;
  readonly handles: number;
  readonly freedEntries: number;
  readonly freedBytes: number;
  readonly errors: readonly ResourceError[];
}

export interface ResourceView {
  readonly key: string;
  readonly kind: ResourceKind;
  readonly sizeBytes: number;
  readonly generation: number;
  readonly refCount: number;
  readonly owners: Readonly<Record<string, number>>;
}

interface Entry {
  readonly spec: ResourceSpec;
  refCount: number;
  readonly holdings: Map<string, number>;
}

interface HandleRecord {
  readonly key: string;
  readonly generation: number;
  readonly owner: string;
  released: boolean;
}

const DEFAULT_LOADER: Loader = { load: (spec) => ok(spec.sizeBytes) };

export class ResourceGraph {
  #loader: Loader;
  #specs = new Map<string, ResourceSpec>();
  #entries = new Map<string, Entry>();
  #generations = new Map<string, number>();
  #handles = new Map<number, HandleRecord>();
  #nextHandleId = 1;
  #disposedEntries = 0;
  #disposedBytes = 0;
  #staleReleases = 0;
  #doubleReleases = 0;

  constructor(loader: Loader = DEFAULT_LOADER) {
    this.#loader = loader;
  }

  register(spec: ResourceSpec): Result<ResourceSpec, ResourceError> {
    if (!Number.isInteger(spec.sizeBytes) || spec.sizeBytes < 0) {
      return fail("invalid-size", `${spec.id}: ${spec.sizeBytes}`);
    }
    const existing = this.#specs.get(spec.id);
    if (existing !== undefined) {
      if (existing.sizeBytes !== spec.sizeBytes || existing.kind !== spec.kind) {
        return fail("duplicate-key", spec.id);
      }
      return ok(existing);
    }
    this.#specs.set(spec.id, spec);
    return ok(spec);
  }

  acquire(key: string, owner: string): Result<Handle, ResourceError> {
    const spec = this.#specs.get(key);
    if (spec === undefined) return fail("unknown-key", key);
    let entry = this.#entries.get(key);
    if (entry === undefined) {
      const loaded = this.#loader.load(spec);
      if (!loaded.ok) return fail("load-failed", `${key}: ${loaded.reason}`);
      entry = { spec, refCount: 0, holdings: new Map() };
      this.#entries.set(key, entry);
    }
    entry.refCount += 1;
    entry.holdings.set(owner, (entry.holdings.get(owner) ?? 0) + 1);
    const id = this.#nextHandleId;
    this.#nextHandleId += 1;
    const generation = this.#generationOf(key);
    this.#handles.set(id, { key, generation, owner, released: false });
    return ok({ id, key, generation, owner });
  }

  release(handle: Handle): Result<ReleaseOutcome, ResourceError> {
    const record = this.#handles.get(handle.id);
    if (record === undefined || record.key !== handle.key) return fail("unknown-handle", String(handle.id));
    if (record.generation !== this.#generationOf(handle.key)) {
      this.#staleReleases += 1;
      return fail("stale-handle", `${handle.key}@${record.generation}`);
    }
    if (record.released) {
      this.#doubleReleases += 1;
      return fail("double-release", `${handle.key}#${handle.id}`);
    }
    const entry = this.#entries.get(handle.key);
    if (entry === undefined) {
      this.#staleReleases += 1;
      return fail("stale-handle", `${handle.key}@${record.generation}`);
    }
    const held = (entry.holdings.get(handle.owner) ?? 0) - 1;
    if (entry.refCount === 1 && held !== 0) {
      return fail("stale-handle", `${handle.key}: holdings disagree with refcount`);
    }
    record.released = true;
    entry.refCount -= 1;
    if (held <= 0) entry.holdings.delete(handle.owner);
    else entry.holdings.set(handle.owner, held);
    if (entry.refCount > 0) return ok({ key: handle.key, freed: false, freedBytes: 0 });

    this.#entries.delete(handle.key);
    this.#generations.set(handle.key, this.#generationOf(handle.key) + 1);
    this.#disposedEntries += 1;
    this.#disposedBytes += entry.spec.sizeBytes;
    return ok({ key: handle.key, freed: true, freedBytes: entry.spec.sizeBytes });
  }

  releaseOwner(owner: string): OwnerReleaseReport {
    const owned: Handle[] = [];
    for (const [id, record] of this.#handles) {
      if (record.released || record.owner !== owner || !this.#entries.has(record.key)) continue;
      owned.push({ id, key: record.key, generation: record.generation, owner });
    }
    owned.sort((a, b) => b.id - a.id);
    const errors: ResourceError[] = [];
    let freedEntries = 0;
    let freedBytes = 0;
    for (const handle of owned) {
      const outcome = this.release(handle);
      if (!outcome.ok) {
        errors.push(outcome.error);
        continue;
      }
      if (outcome.value.freed) {
        freedEntries += 1;
        freedBytes += outcome.value.freedBytes;
      }
    }
    return { owner, handles: owned.length, freedEntries, freedBytes, errors };
  }

  has(key: string): boolean {
    return this.#entries.has(key);
  }

  refCount(key: string): number {
    return this.#entries.get(key)?.refCount ?? 0;
  }

  generationOf(key: string): number {
    return this.#generationOf(key);
  }

  snapshot(): readonly ResourceView[] {
    return [...this.#entries.entries()]
      .map(([key, entry]) => ({
        key,
        kind: entry.spec.kind,
        sizeBytes: entry.spec.sizeBytes,
        generation: this.#generationOf(key),
        refCount: entry.refCount,
        owners: Object.fromEntries([...entry.holdings.entries()].sort()),
      }))
      .sort((a, b) => a.key.localeCompare(b.key));
  }

  audit(): readonly string[] {
    const problems: string[] = [];
    for (const [key, entry] of this.#entries) {
      const held = [...entry.holdings.values()].reduce((sum, count) => sum + count, 0);
      if (entry.refCount !== held) problems.push(`${key}: refCount=${entry.refCount} holdings=${held}`);
      if (entry.refCount <= 0) problems.push(`${key}: non-positive refCount=${entry.refCount}`);
    }
    return problems;
  }

  stats(): Readonly<Record<string, number>> {
    let bytes = 0;
    let refs = 0;
    for (const entry of this.#entries.values()) {
      bytes += entry.spec.sizeBytes;
      refs += entry.refCount;
    }
    return {
      entries: this.#entries.size,
      refs,
      bytes,
      disposedEntries: this.#disposedEntries,
      disposedBytes: this.#disposedBytes,
      staleReleases: this.#staleReleases,
      doubleReleases: this.#doubleReleases,
    };
  }

  #generationOf(key: string): number {
    return this.#generations.get(key) ?? 0;
  }
}