tricu

io-resources.ts (9547B)

---

 import { Tasks, type Token, type Diagnostics } from './io-tasks.js';
 export interface Flags { readonly borrowed?: boolean; readonly internal?: boolean; readonly duplex?: boolean; }
 export interface Resource<B> {
   readonly owner: number; readonly kind: string; readonly backend: B; readonly flags: Flags;
   readonly busy: number; readonly closing: boolean; readonly releasing: boolean;
 }
 type Entry<B> = { -readonly [K in keyof Resource<B>]: Resource<B>[K] };
 export type Access = 'exclusive' | 'read' | 'write';
 // State only. Construct via lifecycle() to bind task settlement to registry guards.
 // Single owning event loop; host effects occur AFTER admission/lease/close claims.
 class Resources<P, B> {
   private next = 4;
   private readonly resources = new Map<number, Entry<B>>();
   private readonly admissions = new Map<number, number>();
   private readonly leases = new Map<number, { scope: number; resource: number; mask: number }>();
   constructor(private readonly tasks: Tasks<P>, standard: readonly [B, B, B], private readonly limit: number) {
     if (!Number.isSafeInteger(limit) || limit < 3) throw new Error('invalid resource identity limit');
     standard.forEach((backend, index) => this.resources.set(index + 1, {
       owner: 0, kind: index === 0 ? 'reader' : 'writer', backend, flags: Object.freeze({ borrowed: true }),
       busy: 0, closing: false, releasing: false }));
   }
   get counts() { return { resources: this.resources.size, admissions: this.admissions.size, leases: this.leases.size }; }
   private token(key: number): Token { return Object.freeze({ run: this.tasks.identity, key }); }
   private key(token: Token): number {
     if (token.run !== this.tasks.identity) throw new Error('stale-handle');
     return token.key;
   }
   private room(count: number): void {
     if (count > this.limit - this.next + 1) throw new Error('resource-identity-exhausted');
   }
   private open(scope: number): void {
     const state = this.tasks.state(scope);
     if (state.phase !== 'open' || state.reason) throw new Error('closed-scope');
   }
   private entry(current: number, token: Token): Entry<B> {
     const resource = this.resources.get(this.key(token));
     if (!resource) throw new Error('stale-handle');
     if (!this.tasks.within(current, resource.owner)) throw new Error('out-of-scope');
     return resource;
   }
   lookup(current: number, token: Token): Resource<B> { return { ...this.entry(current, token) }; }
   beginAcquire(current: number, owner = current): Token {
     this.tasks.checkpoint(current); this.open(owner);
     if (!this.tasks.within(current, owner)) throw new Error('out-of-scope');
     this.room(1); const token = this.token(this.next++);
     this.admissions.set(token.key, owner); return token;
   }
   abortAcquire(token: Token): void {
     if (!this.admissions.delete(this.key(token))) throw new Error('invalid-admission');
   }
   // An admitted acquisition can finish after owner stop/admission closure.
   // Publication failure leaves the admission live: release raw backend, then abort.
   publish(admission: Token, kind: string, backend: B, flags: Flags = {}): Token {
     const key = this.key(admission), owner = this.admissions.get(key);
     if (owner === undefined) throw new Error('invalid-admission');
     if (!kind || Object.values(flags).some(value => typeof value !== 'boolean')) throw new Error('invalid-argument');
     this.room(1);
     const savedFlags = Object.freeze({ ...flags }), token = this.token(this.next);
     this.resources.set(token.key, { owner, kind, backend, flags: savedFlags, busy: 0, closing: false, releasing: false });
     this.next++; this.admissions.delete(key); return token;
   }
   // All recoverable validation and preparation precede task admission. No host
   // callback/await separates admission from rekeying. JS OOM is fatal, not rollback.
   spawn(owner: number, supervised: boolean, keep: boolean, tokens: readonly Token[]) {
     this.tasks.checkpoint(owner); this.open(owner);
     if (typeof supervised !== 'boolean' || typeof keep !== 'boolean') throw new Error('invalid-argument');
     if (tokens.length > 256) throw new Error('transfer-limit');
     const seen = new Set<number>();
     const entries = tokens.map(token => {
       const resource = this.entry(owner, token);
       if (seen.has(token.key)) throw new Error('duplicate-handle');
       seen.add(token.key);
       if (resource.owner !== owner) throw new Error('not-owner');
       if (resource.flags.borrowed) throw new Error('borrowed-resource');
       if (resource.flags.internal) throw new Error('internal-resource');
       if (resource.closing) throw new Error('closed-handle');
       if (resource.busy) throw new Error('busy');
       return { old: token.key, resource };
     }).sort((a, b) => a.old - b.old);
     this.room(tokens.length);
     const fresh = new Map(entries.map((entry, i) => [entry.old, this.token(this.next + i)]));
     const handles = tokens.map(token => fresh.get(token.key)!);
     const task = this.tasks.spawn(owner, supervised, keep);
     for (const entry of entries) {
       this.resources.delete(entry.old); entry.resource.owner = task.key;
       this.resources.set(fresh.get(entry.old)!.key, entry.resource);
     }
     this.next += tokens.length;
     return { task, handles };
   }
   beginLease(current: number, token: Token, kind: string, access: Access, internal = false) {
     this.tasks.checkpoint(current);
     const resource = this.entry(current, token);
     if (resource.kind !== kind) throw new Error('wrong-kind');
     if (resource.closing) throw new Error('closed-handle');
     if (resource.flags.internal && !internal) throw new Error('internal-resource');
     if (!['exclusive', 'read', 'write'].includes(access)) throw new Error('invalid-argument');
     const mask = !resource.flags.duplex || access === 'exclusive' ? 3 : access === 'read' ? 1 : 2;
     if (resource.busy & mask) throw new Error('busy');
     this.room(1); const lease = this.token(this.next++);
     this.leases.set(lease.key, { scope: current, resource: token.key, mask }); resource.busy |= mask;
     return { token: lease, backend: resource.backend };
   }
   endLease(token: Token): void {
     const key = this.key(token), lease = this.leases.get(key);
     if (!lease) throw new Error('invalid-lease');
     this.resources.get(lease.resource)!.busy &= ~lease.mask; this.leases.delete(key);
   }
   claimClose(current: number, token: Token, settling = false): Resource<B> | null {
     const resource = this.entry(current, token);
     if (settling) {
       if (resource.owner !== current || this.tasks.state(current).phase !== 'releasing') throw new Error('invalid-close');
     } else {
       this.tasks.checkpoint(current);
       if (resource.flags.internal) throw new Error('internal-resource');
       if (resource.flags.borrowed) throw new Error('borrowed-resource');
     }
     resource.closing = true;
     if (resource.busy || resource.releasing) return null;
     resource.releasing = true; return { ...resource };
   }
   // Once, including failed release. Never retry a physically ambiguous close.
   finishClose(token: Token): void {
     const key = this.key(token), resource = this.resources.get(key);
     if (!resource) throw new Error('stale-handle');
     if (!resource.releasing) throw new Error('invalid-close');
     this.resources.delete(key);
   }
   newestOwned(scope: number): Token | null {
     let newest = -1;
     for (const [key, resource] of this.resources) if (resource.owner === scope && key > newest) newest = key;
     return newest < 0 ? null : this.token(newest);
   }
   readyForRelease(scope: number): boolean {
     return ![...this.admissions.values()].includes(scope) && ![...this.leases.values()].some(lease => lease.scope === scope);
   }
   finishScope(scope: number): void {
     if (!this.readyForRelease(scope) || this.newestOwned(scope)) throw new Error('busy');
   }
   // Use inside HostWork.release, after Tasks.beginRelease. Each provider is
   // attempted once, sequentially in reverse publication order; borrowed backends
   // stay open. Diagnostics construction failure must not skip remaining releases.
   async releaseScope(scope: number, release: (resource: Resource<B>) => void | Promise<void>,
     problem: (error: unknown) => P, fallback: P): Promise<Diagnostics<P>> {
     if (this.tasks.state(scope).phase !== 'releasing') throw new Error('invalid-transition');
     const items: P[] = []; let omitted = 0;
     for (let token = this.newestOwned(scope); token; token = this.newestOwned(scope)) {
       const resource = this.claimClose(scope, token, true);
       if (!resource) throw new Error('busy');
       try { if (!resource.flags.borrowed) await release(resource); }
       catch (error) {
         if (items.length === 16) omitted++;
         else {
           let value = fallback; try { value = problem(error); } catch { /* retain prebuilt fallback */ }
           items.push(value);
         }
       } finally { this.finishClose(token); }
     }
     return { items, omitted };
   }
 }
 export function lifecycle<P, B>(identity: bigint, ownerStopped: P, cycle: P, standard: readonly [B, B, B],
   limits: { taskIdentities?: number; resourceIdentities?: number } = {}) {
   let resources!: Resources<P, B>;
   const tasks = new Tasks(identity, ownerStopped, cycle, limits.taskIdentities ?? Number.MAX_SAFE_INTEGER, {
     readyForRelease: scope => resources.readyForRelease(scope), finishScope: scope => resources.finishScope(scope) });
   resources = new Resources(tasks, standard, limits.resourceIdentities ?? Number.MAX_SAFE_INTEGER);
   return { tasks, resources };
 }