@perspective-dev/client 4.5.1 → 4.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -12,9 +12,6 @@
12
12
 
13
13
  import type * as perspective_server from "@perspective-dev/server/dist/wasm/perspective-server.js";
14
14
 
15
- type PspPtr = bigint | number;
16
- type EmscriptenServer = number;
17
-
18
15
  var out = console.log.bind(console);
19
16
  var err = console.error.bind(console);
20
17
 
@@ -50,6 +47,151 @@ export default async function (obj: any) {
50
47
  let psp_module: perspective_server.MainModule;
51
48
  let is_memory64 = false;
52
49
  let wasm_memory: WebAssembly.Memory;
50
+
51
+ // A `BACKING_STORE_DISK` column's bytes live in wasm linear memory; the
52
+ // residency manager flushes/loads them to/from OPFS through these imports.
53
+ const heap = () => new Uint8Array(wasm_memory.buffer);
54
+ const toAddr = (p: number | bigint) =>
55
+ is_memory64 ? Number(p as bigint) : (p as number) >>> 0;
56
+
57
+ function readCString(p: number | bigint) {
58
+ const addr = toAddr(p);
59
+ const h = heap();
60
+ let end = addr;
61
+ while (h[end]) ++end;
62
+ return UTF8Decoder.decode(h.subarray(addr, end));
63
+ }
64
+
65
+ // A `DiskBridge` backs `BACKING_STORE_DISK` columns: `store`/`load` flush and
66
+ // re-read a column buffer to/from disk synchronously (the only async step,
67
+ // `ensureOpen`, is hoisted into the JS safepoint between engine calls). The
68
+ // browser default is OPFS; a host can inject an alternative (e.g. `node:fs`
69
+ // in `perspective.node.ts`) via `obj.make_disk_bridge`. `store`/`load`/
70
+ // `remove` receive raw wasm pointers and use the heap helpers; `ensureOpen`
71
+ // receives a resolved file name string (from `victim_fname`).
72
+ const disk_helpers = { heap, toAddr, readCString };
73
+
74
+ function makeOpfsBridge() {
75
+ async function opfsOpenFile(name: string, create: boolean) {
76
+ const parts = name.split("/").filter((s) => s.length > 0);
77
+ // @ts-ignore — navigator.storage.getDirectory is OPFS, Worker-only.
78
+ let dir = await navigator.storage.getDirectory();
79
+ for (let i = 0; i < parts.length - 1; i++) {
80
+ dir = await dir.getDirectoryHandle(parts[i], { create });
81
+ }
82
+ return await dir.getFileHandle(parts[parts.length - 1], { create });
83
+ }
84
+
85
+ // One OPFS `FileSystemSyncAccessHandle` is kept open per disk-backed file
86
+ // for its lifetime.
87
+ const handles = new Map<string, any>();
88
+
89
+ return {
90
+ async ensureOpen(name: string) {
91
+ if (handles.has(name)) {
92
+ return;
93
+ }
94
+ const fh = await opfsOpenFile(name, true);
95
+ // @ts-ignore — createSyncAccessHandle is Worker-only OPFS.
96
+ const ah = await fh.createSyncAccessHandle();
97
+ handles.set(name, ah);
98
+ },
99
+ store(
100
+ namePtr: number | bigint,
101
+ dataPtr: number | bigint,
102
+ len: number,
103
+ ): number {
104
+ try {
105
+ const ah = handles.get(readCString(namePtr));
106
+ if (!ah) {
107
+ // `commit` only evicts victims whose handle the safepoint
108
+ // just opened, so this should be unreachable.
109
+ return -1;
110
+ }
111
+ ah.truncate(len);
112
+ if (len > 0) {
113
+ const addr = toAddr(dataPtr);
114
+ ah.write(heap().subarray(addr, addr + len), { at: 0 });
115
+ }
116
+ ah.flush();
117
+ return len;
118
+ } catch (e) {
119
+ err("psp_opfs_store failed", e);
120
+ return -1;
121
+ }
122
+ },
123
+ load(
124
+ namePtr: number | bigint,
125
+ dataPtr: number | bigint,
126
+ len: number,
127
+ ): number {
128
+ try {
129
+ if (len <= 0) {
130
+ return 0;
131
+ }
132
+ const ah = handles.get(readCString(namePtr));
133
+ // A restore always follows an evict that left the handle open;
134
+ // a miss (or never-flushed file) reads as zeros.
135
+ if (!ah) {
136
+ return 0;
137
+ }
138
+ const addr = toAddr(dataPtr);
139
+ return ah.read(heap().subarray(addr, addr + len), {
140
+ at: 0,
141
+ });
142
+ } catch (e) {
143
+ return 0;
144
+ }
145
+ },
146
+ remove(namePtr: number | bigint) {
147
+ try {
148
+ const name = readCString(namePtr);
149
+ const ah = handles.get(name);
150
+ if (ah) {
151
+ try {
152
+ ah.close();
153
+ } catch (e) {
154
+ /* already closed */
155
+ }
156
+ handles.delete(name);
157
+ }
158
+ // Fire-and-forget the (async) file deletion; the handle is
159
+ // closed, so the bytes are no longer referenced.
160
+ void (async () => {
161
+ try {
162
+ const parts = name
163
+ .split("/")
164
+ .filter((s) => s.length > 0);
165
+ // @ts-ignore
166
+ let dir = await navigator.storage.getDirectory();
167
+ for (let i = 0; i < parts.length - 1; i++) {
168
+ dir = await dir.getDirectoryHandle(parts[i], {
169
+ create: false,
170
+ });
171
+ }
172
+ await dir.removeEntry(parts[parts.length - 1]);
173
+ } catch (e) {
174
+ /* already gone */
175
+ }
176
+ })();
177
+ } catch (e) {
178
+ /* already gone */
179
+ }
180
+ },
181
+ };
182
+ }
183
+
184
+ // The host may inject a disk bridge (e.g. `node:fs`); otherwise default to
185
+ // OPFS. Synchronous `store`/`load`/`remove` env imports — no JSPI.
186
+ const disk = obj.make_disk_bridge
187
+ ? obj.make_disk_bridge(disk_helpers)
188
+ : makeOpfsBridge();
189
+
190
+ const opfs_imports: Record<string, any> = {
191
+ psp_opfs_store: disk.store,
192
+ psp_opfs_load: disk.load,
193
+ psp_opfs_remove: disk.remove,
194
+ };
53
195
  const module = {
54
196
  HaveOffsetConverter() {
55
197
  console.error("HaveOffsetConverter");
@@ -211,6 +353,7 @@ export default async function (obj: any) {
211
353
  console.error("proc_exit", e);
212
354
  return 0;
213
355
  },
356
+ ...opfs_imports,
214
357
  };
215
358
 
216
359
  const x = await obj.instantiateWasm(
@@ -228,14 +371,41 @@ export default async function (obj: any) {
228
371
  },
229
372
  );
230
373
 
374
+ // No JSPI: every export is exposed verbatim (emscripten `_`-prefixed alias).
375
+ // Restore is a synchronous import, so `psp_handle_request`/`psp_poll` stay
376
+ // synchronous WASM calls.
231
377
  const extensions: Record<string, any> = {};
232
378
  for (const [name, func] of Object.entries(x)) {
233
379
  extensions[`_${name}`] = func;
234
380
  }
235
381
 
382
+ // JS-driven residency safepoint. The only async OPFS step — opening each
383
+ // victim's sync access handle — happens HERE, between the two synchronous C++
384
+ // phases: `prepare` picks the cold victims (no freeing), we open their
385
+ // handles, then `commit` flushes + frees them (now a synchronous write). The
386
+ // `engine.ts` server-wide lock serializes this against engine calls. A no-op
387
+ // when nothing is over budget.
388
+ const psp_residency_safepoint = async (server: number | bigint) => {
389
+ const mod = psp_module as any;
390
+ if (!mod.psp_residency_prepare) {
391
+ return;
392
+ }
393
+ const n = Number(mod.psp_residency_prepare(server));
394
+ for (let i = 0; i < n; i++) {
395
+ const fname = readCString(
396
+ mod.psp_residency_victim_fname(server, i),
397
+ );
398
+ if (fname) {
399
+ await disk.ensureOpen(fname);
400
+ }
401
+ }
402
+ mod.psp_residency_commit(server);
403
+ };
404
+
236
405
  return {
237
406
  ...x,
238
407
  ...extensions,
408
+ psp_residency_safepoint,
239
409
  get HEAPU8() {
240
410
  // @ts-ignore
241
411
  return new Uint8Array(wasm_memory.buffer);