node-ctypes 2.14.0 → 2.15.0

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.
Files changed (41) hide show
  1. package/CHANGELOG.md +27 -1
  2. package/build/Release/ctypes-darwin-arm64.node +0 -0
  3. package/build/Release/ctypes-darwin-x64.node +0 -0
  4. package/build/Release/ctypes-linux-arm64-musl.node +0 -0
  5. package/build/Release/ctypes-linux-arm64.node +0 -0
  6. package/build/Release/ctypes-linux-x64-musl.node +0 -0
  7. package/build/Release/ctypes-linux-x64.node +0 -0
  8. package/build/Release/ctypes-win32-arm64.node +0 -0
  9. package/build/Release/ctypes-win32-x64.node +0 -0
  10. package/lib/core/Library.js +69 -51
  11. package/lib/core/callback-conversions.js +123 -0
  12. package/lib/core/callback.js +68 -4
  13. package/lib/core/conversions.js +74 -412
  14. package/lib/core/funcptr.js +31 -287
  15. package/lib/core/invocation.js +170 -0
  16. package/lib/core/native-aggregate.js +193 -0
  17. package/lib/core/parameters.js +45 -0
  18. package/lib/core/paramflags.js +183 -0
  19. package/lib/core/results.js +86 -0
  20. package/lib/core/types.js +14 -277
  21. package/lib/index.js +2 -1
  22. package/lib/memory/buffer.js +1 -1
  23. package/lib/memory/mirror.js +2 -2
  24. package/lib/memory/operations.js +2 -1
  25. package/lib/memory/ownership.js +218 -0
  26. package/lib/memory/pointer.js +6 -1
  27. package/lib/platform/win_types.js +1 -1
  28. package/lib/structures/Structure.js +50 -37
  29. package/lib/structures/helpers/array.js +27 -13
  30. package/lib/structures/helpers/bitfield.js +1 -1
  31. package/lib/structures/helpers/common.js +3 -368
  32. package/lib/structures/helpers/fields.js +111 -0
  33. package/lib/structures/helpers/layout.js +44 -57
  34. package/lib/structures/helpers/struct.js +19 -108
  35. package/lib/structures/helpers/union.js +13 -114
  36. package/lib/structures/helpers/wrap.js +1 -1
  37. package/lib/structures/protocol.js +8 -0
  38. package/lib/types/SimpleCData.js +2 -1
  39. package/lib/types/primitives.js +2 -1
  40. package/lib/types/scalar-protocol.js +120 -0
  41. package/package.json +1 -1
package/lib/core/types.js CHANGED
@@ -1,319 +1,56 @@
1
- /**
2
- * @file types.js
3
- * @module core/types
4
- * @description Type normalization helpers tra il formato JS-facing della lib
5
- * e quello richiesto dal binding nativo (`FFIFunction` / `Callback` / ecc.).
6
- *
7
- * Le classi `Structure`/`Union` JS (e `struct()`/`union()` plain helpers)
8
- * producono `structDef` — oggetti JS con `fields`/`fieldMap`/ecc. — **non**
9
- * sono il native `StructType` che il C++ si aspetta come argtype/restype.
10
- *
11
- * `_buildNativeStructType` costruisce (o recupera cached) il wrapper
12
- * `new native.StructType()` popolato con `addField(name, type)` per ogni
13
- * campo del def. Supporta tutti i tipi di field:
14
- *
15
- * - SimpleCData primitives (c_int32, ecc.)
16
- * - POINTER
17
- * - Bitfield: i byte che contengono bitfield diventano campi uint8 agli
18
- * offset del layout JS (con gcc-sysv un bitfield può condividere byte con
19
- * altri campi, e un unico tipo per "cella" non riprodurrebbe gli offset).
20
- * - Campi disallineati (`_pack_`): byte uint8 agli offset del layout JS.
21
- * - Array: sia `array(SimpleCData, N)` sia `array(Structure/Union, N)`;
22
- * per il secondo caso il native ArrayType è costruito lazy qui.
23
- * - Nested Structure/Union (anche `_anonymous_`): ricorsione.
24
- * - Classe base (Python: sottoclasse con _fields_): primo campo, come in C.
25
- *
26
- * Dimensione e allineamento sono quelli del layout JS (layout.js, `_align_`).
27
- */
1
+ /** Normalize public ctypes declarations for native arguments and return values. */
2
+ import { buildNativeAggregate } from "./native-aggregate.js";
28
3
 
29
- import { cacheWeakValue } from "../utils/cache.js";
30
-
31
- // ArrayType nativi costruiti per gli array di Structure/Union (gli array JS
32
- // espongono `_native` in sola lettura).
33
- const nativeArrayTypes = new WeakMap();
34
-
35
- // ArrayType nativi uint8[n] per i byte emessi come tali (vedi sotto).
36
- const byteArrayTypes = new Map();
37
-
38
- function byteRun(st, native, offset, length) {
39
- if (length <= 0) return;
40
- if (length === 1) {
41
- st.addField(`__byte@${offset}`, native.CType.UINT8);
42
- return;
43
- }
44
- let arrayType = byteArrayTypes.get(length)?.deref();
45
- if (arrayType === undefined) {
46
- arrayType = new native.ArrayType(native.CType.UINT8, length);
47
- cacheWeakValue(byteArrayTypes, length, arrayType);
48
- }
49
- st.addField(`__bytes@${offset}`, arrayType);
50
- }
51
-
52
- const roundUp = (n, a) => Math.ceil(n / a) * a;
53
-
54
- // Byte toccati da un bitfield (dentro la sua unità di `baseSize` byte).
55
- function bitFieldBytes(f) {
56
- const first = Math.floor(f.bitOffset / 8);
57
- const last = Math.floor((f.bitOffset + f.bitSize - 1) / 8);
58
- const bytes = [];
59
- for (let b = first; b <= last; b++) {
60
- bytes.push(f.offset + (f.swapped ? f.baseSize - 1 - b : b));
61
- }
62
- return bytes;
63
- }
64
-
65
- const nestedDefOf = (f) => {
66
- if (f.isNested) return typeof f.type === "function" ? f.type._structDef || f.type._buildStruct?.() : f.type;
67
- const element = f.isArray ? f.type?.elementType : undefined;
68
- if (typeof element === "function" && typeof element._buildStruct === "function") return element._structDef || element._buildStruct();
69
- return undefined;
70
- };
71
-
72
- // Campi (anche di struct annidate) a un offset non multiplo del loro
73
- // allineamento C, come con `_pack_`: l'ABI x86-64 System V passa queste struct
74
- // in memoria (vedi StructInfo::SetMemoryClass).
75
- const unalignedDefs = new WeakMap();
76
- function hasUnalignedFields(def) {
77
- let result = unalignedDefs.get(def);
78
- if (result === undefined) {
79
- result = def.fields.some((f) => {
80
- if (f.isBitField) return false;
81
- if (!def.isUnion && f.offset % (f.naturalAlignment ?? f.alignment) !== 0) return true;
82
- const nested = nestedDefOf(f);
83
- return nested !== undefined && hasUnalignedFields(nested);
84
- });
85
- unalignedDefs.set(def, result);
86
- }
87
- return result;
88
- }
89
-
90
- /**
91
- * Costruisce (o recupera cached) un native `StructType` corrispondente a un
92
- * structDef/unionDef. Cacheato su `def._nativeStructType` per evitare
93
- * ricostruzioni multiple sulla stessa def.
94
- *
95
- * La struct nativa ha gli offset, la dimensione e l'allineamento del layout
96
- * JS (layout.js, `_pack_`, `_align_`, bitfield). Un campo resta del suo tipo
97
- * (che conta per la classificazione dell'ABI: float/double vanno nei registri
98
- * SSE) quando nella struct nativa cade allo stesso offset: offset allineato al
99
- * suo allineamento C, non superiore a quello della struct. Altrimenti (campi
100
- * disallineati da `_pack_`, byte dei bitfield) i suoi byte diventano uint8. Il
101
- * padding non è emesso, se non prima di byte da collocare all'offset giusto.
102
- *
103
- * @param {Object} def - structDef o unionDef (output di `struct()`/`union()`
104
- * o `_structDef` di una Structure class).
105
- * @param {Object} native - modulo native (`require('ctypes.node')`).
106
- * @returns {Object} istanza di `native.StructType` utilizzabile come
107
- * argtype/restype dal FFIFunction.
108
- */
109
- function _buildNativeStructType(def, native) {
110
- if (def._nativeStructType) return def._nativeStructType;
111
- if (!Number.isInteger(Math.log2(def.alignment))) {
112
- throw new TypeError("Native by-value ABI requires power-of-two alignment; use this layout only for memory serialization");
113
- }
114
- const st = new native.StructType({
115
- union: !!def.isUnion,
116
- alignment: def.alignment,
117
- memoryClass: hasUnalignedFields(def),
118
- });
119
- const fits = (alignment, offset) => alignment <= def.alignment && offset % alignment === 0;
120
-
121
- // La classe base è il primo membro della struct (i suoi campi sono i primi
122
- // di def.fields, agli stessi offset).
123
- let fields = def.fields;
124
- let position = 0;
125
- if (def.base) {
126
- if (fits(def.base.alignment, 0)) st.addField("__base__", _buildNativeStructType(def.base, native));
127
- else byteRun(st, native, 0, def.base.size);
128
- fields = def.fields.slice(def.base.fields.length);
129
- position = def.isUnion ? 0 : def.base.size;
130
- }
131
-
132
- if (def.isUnion) {
133
- for (const f of fields) {
134
- const size = f.isBitField ? f.baseSize : f.size;
135
- const alignment = f.naturalAlignment ?? f.alignment;
136
- if (!fits(alignment, 0)) byteRun(st, native, 0, size);
137
- // Un bitfield occupa il proprio tipo base all'offset 0.
138
- else if (f.isBitField) st.addField(`__bitfield_${f.name}`, bitFieldBaseType(f));
139
- else addNativeField(st, f, native);
140
- }
141
- } else {
142
- // Campi e byte dei bitfield in ordine di offset.
143
- const items = [];
144
- const bitBytes = new Set();
145
- for (const f of fields) {
146
- if (f.isBitField) bitFieldBytes(f).forEach((b) => bitBytes.add(b));
147
- else if (f.size > 0) items.push({ offset: f.offset, size: f.size, field: f });
148
- }
149
- for (const b of bitBytes) items.push({ offset: b, size: 1, field: null });
150
- items.sort((a, b) => a.offset - b.offset);
151
-
152
- let bytesFrom = -1; // inizio della sequenza di byte in corso
153
- const flushBytes = () => {
154
- if (bytesFrom >= 0) byteRun(st, native, bytesFrom, position - bytesFrom);
155
- bytesFrom = -1;
156
- };
157
- const addBytes = (offset, size) => {
158
- if (bytesFrom < 0) bytesFrom = position;
159
- position = offset + size;
160
- };
161
-
162
- for (const { offset, size, field } of items) {
163
- if (offset < position) continue; // byte già coperto
164
- const alignment = field ? (field.naturalAlignment ?? field.alignment) : 1;
165
- if (field && fits(alignment, offset)) {
166
- // Il padding naturale prima del campo resta padding; un vuoto più
167
- // grande (es. `_align_` di una struct annidata) diventa byte.
168
- if (roundUp(position, alignment) !== offset) addBytes(offset, 0);
169
- flushBytes();
170
- addNativeField(st, field, native);
171
- position = offset + size;
172
- } else {
173
- addBytes(offset, size);
174
- }
175
- }
176
- flushBytes();
177
- // Coda oltre l'arrotondamento all'allineamento (non accade con i layout
178
- // di layout.js, ma la dimensione deve comunque coincidere).
179
- if (roundUp(position, def.alignment) < def.size) byteRun(st, native, position, def.size - position);
180
- }
181
-
182
- const size = st.getSize();
183
- if (size !== def.size || st.getAlignment() !== def.alignment) {
184
- throw new Error(`Native layout of the structure (size ${size}, alignment ${st.getAlignment()}) differs from its definition (size ${def.size}, alignment ${def.alignment})`);
185
- }
186
- def._nativeStructType = st;
187
- return st;
188
- }
189
-
190
- function bitFieldBaseType(f) {
191
- if (!f.type || typeof f.type._type !== "number") {
192
- throw new Error(`Bitfield '${f.name}': base type senza _type numerico`);
193
- }
194
- return f.type._type;
195
- }
196
-
197
- function addNativeField(st, f, native) {
198
- const options = f.isAnonymous ? { anonymous: true } : undefined;
199
- if (f.isArray) {
200
- // Array di primitive (o di struct native): `_native` è già un ArrayType.
201
- const own = f.type?._native;
202
- if (own && typeof own.getSize === "function" && own.constructor?.name === "ArrayType") {
203
- st.addField(f.name, own, options);
204
- return;
205
- }
206
- // Array di Structure/Union: ArrayType nativo costruito qui (una volta per tipo).
207
- const elementType = f.type?.elementType;
208
- const count = f.type?.length;
209
- const elemDef = typeof elementType === "function" && typeof elementType._buildStruct === "function" ? elementType._structDef || elementType._buildStruct() : elementType?._isStructType === true ? elementType : undefined;
210
- if (elemDef !== undefined && typeof count === "number") {
211
- let arrNative = nativeArrayTypes.get(f.type);
212
- if (arrNative === undefined) {
213
- arrNative = new native.ArrayType(_buildNativeStructType(elemDef, native), count);
214
- nativeArrayTypes.set(f.type, arrNative);
215
- }
216
- st.addField(f.name, arrNative, options);
217
- return;
218
- }
219
- throw new Error(`Field '${f.name}': array-in-struct-by-value non riconosciuto. ` + `Tipi supportati: array(SimpleCData, N), array(Structure/Union subclass o struct()/union(), N). ` + `Alternativa: passa la struct per puntatore.`);
220
- }
221
- if (f.isNested) {
222
- // f.type è un structDef/unionDef (quando dichiarato via struct/union)
223
- // o una Structure/Union class (quando dichiarato con class extends).
224
- let nestedDef = f.type;
225
- if (typeof f.type === "function") {
226
- nestedDef = f.type._structDef || f.type._buildStruct?.();
227
- }
228
- if (!nestedDef || !Array.isArray(nestedDef.fields)) {
229
- throw new Error(`Field '${f.name}': nested type non riconosciuto`);
230
- }
231
- st.addField(f.name, _buildNativeStructType(nestedDef, native), options);
232
- return;
233
- }
234
- if (f.isPointer) {
235
- st.addField(f.name, native.CType.POINTER);
236
- return;
237
- }
238
- // SimpleCData class: usa il suo _type numerico.
239
- if (f.type && typeof f.type === "function" && f.type._isSimpleCData) {
240
- st.addField(f.name, f.type._type);
241
- return;
242
- }
243
- throw new Error(`Field '${f.name}': tipo non riconosciuto durante _buildNativeStructType`);
244
- }
245
-
246
- /**
247
- * Normalizza un tipo singolo nel formato atteso dal native FFIFunction.
248
- *
249
- * Regole di conversione:
250
- * 1. SimpleCData class (c_int32, c_char_p, ecc.): ritorna `_type` numerico.
251
- * 2. POINTER(T) wrapper (ha `_pointerTo`): ritorna `CType.POINTER`.
252
- * 3. Structure / Union class: costruisce (o cachea) un native StructType.
253
- * 4. Plain structDef / unionDef (ha `_isStructType`): idem.
254
- * 5. ArrayType wrapper (ha `_isArrayType`): ritorna il `_native` se
255
- * disponibile, altrimenti l'object.
256
- * 6. Numero: pass-through (già un CType).
257
- * 7. Altro: pass-through (es. native CType object, HRESULT, ecc.).
258
- */
259
4
  export function _toNativeType(type, native) {
260
- // 1. SimpleCData
261
5
  if (typeof type === "function" && type._isSimpleCData) {
262
6
  return type._type;
263
7
  }
264
8
 
265
- // 2. POINTER wrapper
266
9
  if (type && typeof type === "object" && type._pointerTo !== undefined) {
267
10
  return native.CType.POINTER;
268
11
  }
269
12
 
270
- // 2b. Tipo funzione CFUNCTYPE / WINFUNCTYPE (Python: argtypes = [..., CMPFUNC])
271
13
  if (typeof type === "function" && type._isFuncPtr === true) {
272
14
  return native.CType.POINTER;
273
15
  }
274
16
 
275
- // 3. Structure / Union subclass → native StructType.
276
17
  if (typeof type === "function" && typeof type._buildStruct === "function") {
277
18
  const def = type._structDef || type._buildStruct();
278
- return _buildNativeStructType(def, native);
19
+ return buildNativeAggregate(def, native);
279
20
  }
280
21
  if (typeof type === "function" && typeof type._buildUnion === "function") {
281
22
  const def = type._unionDef || type._buildUnion();
282
- return _buildNativeStructType(def, native);
23
+ return buildNativeAggregate(def, native);
283
24
  }
284
25
 
285
- // 4. Plain structDef / unionDef.
286
26
  if (type && typeof type === "object" && type._isStructType && Array.isArray(type.fields)) {
287
- return _buildNativeStructType(type, native);
27
+ return buildNativeAggregate(type, native);
288
28
  }
289
29
 
290
- // 5. Array wrapper
291
30
  if (type && (typeof type === "object" || typeof type === "function") && type._isArrayType) {
292
31
  return type._native || type;
293
32
  }
294
33
 
295
- // 6. Numero
296
34
  if (typeof type === "number") return type;
297
35
 
298
- // 7. Pass-through
299
36
  return type;
300
37
  }
301
38
 
302
- /**
303
- * Come _toNativeType, per i tipi di ritorno: `null` vale `void`
304
- * (Python ctypes: `restype = None`, `CFUNCTYPE(None, ...)`).
305
- */
39
+ // A null restype denotes void, not a null pointer.
306
40
  export function _toNativeReturnType(type, native) {
307
41
  if (type === null) return native.CType.VOID;
308
42
  return _toNativeType(type, native);
309
43
  }
310
44
 
311
- /**
312
- * Normalizza un array di tipi di argomento (batch). Non-array → pass-through.
313
- * Un tipo array come argomento è un puntatore, come in C e Python
314
- * (`argtypes = [c_int * 4]` passa l'indirizzo dell'array).
315
- */
45
+ // Array parameters decay to pointers; array fields in aggregates do not.
316
46
  export function _toNativeTypes(types, native) {
317
47
  if (!Array.isArray(types)) return types;
318
48
  return types.map((type) => (type && (typeof type === "object" || typeof type === "function") && type._isArrayType === true ? native.CType.POINTER : _toNativeType(type, native)));
319
49
  }
50
+
51
+ export function requireDescriptor(type, native, index) {
52
+ // A low-level array wrapper can resolve its _native getter later, at binding.
53
+ if (type instanceof native.StructType || type instanceof native.ArrayType || "_native" in type) return;
54
+ const position = index === undefined ? "return type" : `argument type at index ${index}`;
55
+ throw new TypeError(`Invalid ${position}: expected a ctypes type descriptor`);
56
+ }
package/lib/index.js CHANGED
@@ -43,7 +43,8 @@ import { createMemoryOps } from "./memory/operations.js";
43
43
  import { enableMirrors, wrapNative } from "./memory/mirror.js";
44
44
  import { addressOf as _addressOf, byref as _byref, cast as _cast, ptrToBuffer as _ptrToBuffer, POINTER as _POINTER, pointer as _pointer } from "./memory/pointer.js";
45
45
  import { FormatError as _FormatError, WinError as _WinError, ArgumentError } from "./platform/errors.js";
46
- import { bitfield as _bitfield, _isStruct, _isArrayType, _isBitField, registerSimpleType } from "./structures/helpers/common.js";
46
+ import { bitfield as _bitfield, _isStruct, _isArrayType, _isBitField } from "./structures/helpers/common.js";
47
+ import { registerSimpleType } from "./types/scalar-protocol.js";
47
48
  import { array as _array } from "./structures/helpers/array.js";
48
49
  import { union as _union } from "./structures/helpers/union.js";
49
50
  import { struct as _struct } from "./structures/helpers/struct.js";
@@ -28,7 +28,7 @@
28
28
  */
29
29
 
30
30
  import { mirrorAddress } from "./mirror.js";
31
- import { resolveParameter } from "../structures/helpers/common.js";
31
+ import { resolveParameter } from "../core/parameters.js";
32
32
  import { ArgumentError } from "../platform/errors.js";
33
33
 
34
34
  // Fixed backing stores do not move; resizable/growable stores are never cached.
@@ -214,13 +214,13 @@ export function syncDefinition(def) {
214
214
  const size = def.size;
215
215
  const fieldMap = def.fieldMap;
216
216
  const { get, set, toObject } = def;
217
- def.get = function (bufOrObj, fieldName) {
217
+ def.get = function (bufOrObj, fieldName, owner) {
218
218
  if (isMirror(bufOrObj)) {
219
219
  const field = fieldMap?.get(fieldName);
220
220
  if (field === undefined) refresh(bufOrObj, 0, size);
221
221
  else if (!field.isNested && !field.isArray) refresh(bufOrObj, field.offset, fieldSize(field));
222
222
  }
223
- return get.call(this, bufOrObj, fieldName);
223
+ return get.call(this, bufOrObj, fieldName, owner);
224
224
  };
225
225
  def.set = function (bufOrObj, fieldName, value) {
226
226
  if (!isMirror(bufOrObj)) return set.call(this, bufOrObj, fieldName, value);
@@ -28,7 +28,8 @@
28
28
  */
29
29
 
30
30
  import { flush, mirrorsActive, refresh } from "./mirror.js";
31
- import { copyInstance, isScalarSubclass, scalarView } from "../structures/helpers/common.js";
31
+ import { copyInstance } from "./ownership.js";
32
+ import { isScalarSubclass, scalarView } from "../types/scalar-protocol.js";
32
33
 
33
34
  /**
34
35
  * Factory che cattura le dipendenze in closure e restituisce un bundle di
@@ -0,0 +1,218 @@
1
+ /** Pointer registrations and leases belong to the backing memory, not to an individual view. */
2
+ import { flush, mirrorsActive, refresh } from "./mirror.js";
3
+ import { POINTER_SIZE } from "../platform/constants.js";
4
+
5
+ export function sourceBytes(source, offset, size, name) {
6
+ const bytes = source !== null && typeof source === "object" && !ArrayBuffer.isView(source) && Buffer.isBuffer(source._buffer) ? source._buffer : source;
7
+ if (!ArrayBuffer.isView(bytes)) throw new TypeError(`${name}: source must be a Buffer, a typed array or a ctypes instance`);
8
+ if (!Number.isSafeInteger(offset)) throw new TypeError(`${name}: offset must be a safe integer`);
9
+ if (offset < 0) throw new RangeError(`${name}: offset cannot be negative`);
10
+ if (bytes.byteLength - offset < size) throw new RangeError(`${name}: Buffer size too small (${bytes.byteLength} instead of at least ${size + offset} bytes)`);
11
+ return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
12
+ }
13
+
14
+ export function keepFunctionOwner(fn, owner) {
15
+ if (owner !== undefined) {
16
+ Object.defineProperty(fn, "_objects", { value: owner });
17
+ // AsyncWorker pins the native handle, not its public JS function.
18
+ Object.defineProperty(fn._ffi, "_objects", { value: owner });
19
+ }
20
+ return fn;
21
+ }
22
+
23
+ const keptObjects = new WeakMap();
24
+
25
+ const memoryOwners = new WeakMap();
26
+
27
+ // Address-backed aliases share the reference table of their known owner.
28
+ const memoryDomains = new WeakMap();
29
+
30
+ export function memoryDomain(buf) {
31
+ return memoryDomains.get(buf.buffer) ?? { root: buf.buffer, offset: 0n };
32
+ }
33
+
34
+ function memoryPosition(buf, offset) {
35
+ return BigInt(buf.byteOffset + offset) + (memoryDomains.get(buf.buffer)?.offset ?? 0n);
36
+ }
37
+
38
+ export function shareMemory(buf, memory, position) {
39
+ memoryDomains.set(buf.buffer, { root: memory.root, offset: position - BigInt(buf.byteOffset) });
40
+ return keepMemoryOwner(buf, memory);
41
+ }
42
+
43
+ // Attach to the backing store, so subarrays and typed arrays keep the lease too.
44
+ export function keepMemoryOwner(buf, owner) {
45
+ if (owner === undefined || owner === null) return buf;
46
+ let owners = memoryOwners.get(buf.buffer);
47
+ if (owners === undefined) memoryOwners.set(buf.buffer, (owners = new Set()));
48
+ owners.add(owner);
49
+ return buf;
50
+ }
51
+
52
+ function storedAddress(buf, offset) {
53
+ return POINTER_SIZE === 8 ? buf.readBigUInt64LE(offset) : BigInt(buf.readUInt32LE(offset));
54
+ }
55
+
56
+ export function pointerOwner(buf, offset, address) {
57
+ const root = memoryDomains.get(buf.buffer)?.root ?? buf.buffer;
58
+ const kept = keptObjects.get(root);
59
+ if (kept === undefined) return buf;
60
+ const position = memoryPosition(buf, offset);
61
+ const reference = kept.get(position);
62
+ if (reference !== undefined && reference.address !== (address ?? storedAddress(buf, offset))) {
63
+ kept.delete(position);
64
+ return buf;
65
+ }
66
+ return reference?.owner ?? buf;
67
+ }
68
+
69
+ export function inDllBuffer(library, name, size, ptrToBuffer) {
70
+ const lib = library?._lib ?? library;
71
+ if (typeof lib?._symbolView !== "function") throw new TypeError("in_dll: first arg must be a Library (CDLL/WinDLL)");
72
+ const { address, owner } = lib._symbolView(name);
73
+ return keepMemoryOwner(ptrToBuffer(address, size), owner);
74
+ }
75
+
76
+ function pointerSlots(type, offset = 0, size) {
77
+ if (type?._isPointerValued || type?._isFuncPtr || type?._pointerTo !== undefined) return [[offset, type._size ?? type.size ?? size]];
78
+ if (type?._isArrayType) {
79
+ const slots = [];
80
+ const elementSize = type.length === 0 ? 0 : type.getSize() / type.length;
81
+ const elements = pointerSlots(type.elementType, 0, elementSize);
82
+ if (elements.length === 0) return slots;
83
+ for (let i = 0; i < type.length; i++) {
84
+ for (const [position, width] of elements) slots.push([offset + i * elementSize + position, width]);
85
+ }
86
+ return slots;
87
+ }
88
+ const def = typeof type?._buildStruct === "function" ? (type._structDef ?? type._buildStruct()) : type;
89
+ const slots = [];
90
+ for (const field of def?.fields ?? []) {
91
+ if (field.isPointer) slots.push([offset + field.offset, field.size]);
92
+ else slots.push(...pointerSlots(field.type, offset + field.offset, field.size));
93
+ }
94
+ return slots;
95
+ }
96
+
97
+ /**
98
+ * Keep `value` alive as long as the memory of `targetBuf`, like Python ctypes
99
+ * `_objects`: an object whose address is stored in the buffer (string,
100
+ * pointer, callback) must not be garbage collected while native code can
101
+ * still read that address. The table belongs to the memory, not to the view,
102
+ * so assigning through a nested structure keeps the object alive with the
103
+ * outer one.
104
+ *
105
+ * @param {Uint8Array} targetBuf - Buffer holding the address
106
+ * @param {number} offset - Offset of the slot in `targetBuf`
107
+ * @param {*} value - Referenced object (or null to clear the slot)
108
+ */
109
+ export function keepAlive(targetBuf, offset, value) {
110
+ const position = memoryPosition(targetBuf, offset);
111
+ const root = memoryDomains.get(targetBuf.buffer)?.root ?? targetBuf.buffer;
112
+ let kept = keptObjects.get(root);
113
+ if (value === null || (typeof value !== "object" && typeof value !== "function")) {
114
+ kept?.delete(position);
115
+ return;
116
+ }
117
+ if (kept === undefined) {
118
+ kept = new Map();
119
+ keptObjects.set(root, kept);
120
+ }
121
+ // A pointer wrapper can later be repointed; retain its current memory.
122
+ if (value._pointerType !== undefined) value = value._buffer ?? value._objects ?? value;
123
+ else if (value._isSimpleCDataInstance && value.constructor._isPointerValued) value = pointerOwner(value._buffer, 0);
124
+ kept.set(position, { owner: value, address: storedAddress(targetBuf, offset) });
125
+ }
126
+
127
+ /**
128
+ * Object kept alive at `offset` of `buf` (see {@link keepAlive}).
129
+ *
130
+ * @param {Uint8Array} buf - Buffer
131
+ * @param {number} offset - Offset in `buf`
132
+ * @returns {*} The object, or undefined
133
+ */
134
+ export function keptObject(buf, offset) {
135
+ const root = memoryDomains.get(buf.buffer)?.root ?? buf.buffer;
136
+ return keptObjects.get(root)?.get(memoryPosition(buf, offset))?.owner;
137
+ }
138
+
139
+ export function clearKeepAlives(buf, offset, size) {
140
+ const root = memoryDomains.get(buf.buffer)?.root ?? buf.buffer;
141
+ const kept = keptObjects.get(root);
142
+ if (kept === undefined) return;
143
+ const start = BigInt(memoryPosition(buf, offset));
144
+ const end = start + BigInt(size);
145
+ for (const position of kept.keys()) {
146
+ if (position >= start && position < end) kept.delete(position);
147
+ }
148
+ }
149
+
150
+ /**
151
+ * Copy a struct/union instance into a nested field: the bytes (as Python
152
+ * does) plus the objects it keeps alive (strings, pointers, callbacks), so
153
+ * the addresses copied with them stay valid.
154
+ *
155
+ * @param {Buffer} buf - Target buffer
156
+ * @param {number} offset - Field offset
157
+ * @param {number} size - Field size
158
+ * @param {Object|Buffer} value - Instance with a `_buffer`, or source bytes
159
+ * @param {number} [sourceOffset=0] - Byte offset in the source
160
+ * @param {Function|Object} [type] - Layout used to retain references into leased memory
161
+ */
162
+ export function copyInstance(buf, offset, size, value, sourceOffset = 0, type) {
163
+ const bytes = value._buffer ?? value;
164
+ const source = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
165
+ if (mirrorsActive) refresh(source, sourceOffset, size);
166
+ // Source and destination can overlap, including their reference tables.
167
+ const owners = snapshotOwners(source, sourceOffset, size, type);
168
+ source.copy(buf, offset, sourceOffset, sourceOffset + size);
169
+ clearKeepAlives(buf, offset, size);
170
+ for (const [relative, owner] of owners) keepAlive(buf, offset + relative, owner);
171
+ if (mirrorsActive) flush(buf, offset, size);
172
+ }
173
+
174
+ function snapshotOwners(source, sourceOffset, size, type) {
175
+ const start = memoryPosition(source, sourceOffset);
176
+ const sourceRoot = memoryDomains.get(source.buffer)?.root ?? source.buffer;
177
+ const sourceKept = keptObjects.get(sourceRoot);
178
+ const snapshot = new Map();
179
+ if (sourceKept !== undefined) {
180
+ for (const [position, reference] of sourceKept) {
181
+ if (position < start || position + BigInt(POINTER_SIZE) > start + BigInt(size)) continue;
182
+ const relative = Number(position - start);
183
+ if (reference.address === storedAddress(source, sourceOffset + relative)) {
184
+ snapshot.set(relative, reference.owner);
185
+ } else {
186
+ // A leased copy can retain the source buffer, so don't leave a stale owner on it.
187
+ sourceKept.delete(position);
188
+ }
189
+ }
190
+ }
191
+ if (type !== undefined && memoryOwners.has(source.buffer)) {
192
+ for (const [position, width] of pointerSlots(type)) {
193
+ if (snapshot.has(position) || position + width > size) continue;
194
+ for (let i = 0; i < width; i++) {
195
+ if (source[sourceOffset + position + i] !== 0) {
196
+ snapshot.set(position, source);
197
+ break;
198
+ }
199
+ }
200
+ }
201
+ }
202
+ return snapshot;
203
+ }
204
+
205
+ // Keep the owners of the copied addresses even if a later adapter overwrites
206
+ // the original pointer fields. Plain bytes need no reference bookkeeping.
207
+ export function snapshotArgumentBytes(view, def) {
208
+ const size = def.size;
209
+ const copy = Buffer.alloc(size);
210
+ if (memoryOwners.has(view.buffer) || keptObjects.has(memoryDomains.get(view.buffer)?.root ?? view.buffer)) {
211
+ copyInstance(copy, 0, size, Buffer.from(view.buffer, view.byteOffset, size), 0, def);
212
+ } else {
213
+ const source = view instanceof Uint8Array && view.length === size ? view : Buffer.from(view.buffer, view.byteOffset, size);
214
+ if (mirrorsActive) refresh(source, 0, size);
215
+ copy.set(source);
216
+ }
217
+ return copy;
218
+ }
@@ -26,9 +26,14 @@
26
26
  * ```
27
27
  */
28
28
 
29
- import { byrefOwners, isScalarSubclass, keepAlive, keepFunctionOwner, keptObject, kPointerMemory, memoryDomain, pointerOwner, scalarView, shareMemory, writePointerField } from "../structures/helpers/common.js";
29
+ import { byrefOwners } from "../core/parameters.js";
30
+ import { keepAlive, keepFunctionOwner, keptObject, memoryDomain, pointerOwner, shareMemory } from "./ownership.js";
31
+ import { writePointerField } from "../structures/helpers/common.js";
32
+ import { isScalarSubclass, scalarView } from "../types/scalar-protocol.js";
30
33
  import { flush, mirrorAddress, mirrorsActive, refresh } from "./mirror.js";
31
34
 
35
+ const kPointerMemory = Symbol("pointerMemory");
36
+
32
37
  /**
33
38
  * Gets the memory address of a buffer or pointer.
34
39
  *
@@ -1,4 +1,4 @@
1
- import { booleanValue, registerSimpleType } from "../structures/helpers/common.js";
1
+ import { booleanValue, registerSimpleType } from "../types/scalar-protocol.js";
2
2
 
3
3
  /**
4
4
  * @file win_types.js