node-ctypes 2.3.0 → 2.5.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.
@@ -37,8 +37,12 @@
37
37
  */
38
38
 
39
39
  import { _toNativeReturnType, _toNativeTypes } from "./types.js";
40
- import { argumentConverters, convertArguments, resultConverter, structResult } from "./conversions.js";
40
+ import { argumentConverters, argumentsNeedOwners, callWithArgumentOwners, callWithResultHandler, convertArguments, resultCheck, resultConverter, scalarResult, specializeCall, structResult } from "./conversions.js";
41
41
  import { callback as createCallback } from "./callback.js";
42
+ import { isScalarSubclass, keepFunctionOwner, scalarOutparam } from "../structures/helpers/common.js";
43
+ import { cacheWeakValue, createTypeKey } from "../utils/cache.js";
44
+
45
+ const prototypeOwners = new WeakMap();
42
46
 
43
47
  /**
44
48
  * Internal helper: builds a function wrapper that interprets paramflags
@@ -46,7 +50,7 @@ import { callback as createCallback } from "./callback.js";
46
50
  * native function. Used by both CFUNCTYPE and WINFUNCTYPE factories.
47
51
  *
48
52
  * `paramflags` is an array the same length as argtypes, where each entry is:
49
- * { dir: "in" | "out", name: string, default?: any }
53
+ * { dir: "in" | "out" | "inout", name: string, default?: any }
50
54
  *
51
55
  * Calling conventions:
52
56
  * - Positional: fn(arg1, arg2, ...) — only "in" params supplied in order
@@ -71,7 +75,8 @@ function applyParamflags(rawFn, restype, argtypes, paramflags) {
71
75
 
72
76
  // Classify slots and cache pointed-to types for out-params
73
77
  const slots = paramflags.map((pf, idx) => {
74
- const isOut = pf.dir === "out";
78
+ if (!["in", "out", "inout"].includes(pf.dir)) throw new TypeError(`paramflags[${idx}] has an invalid direction`);
79
+ const isOut = pf.dir !== "in";
75
80
  const argtype = argtypes[idx];
76
81
  let outType = null;
77
82
  if (isOut) {
@@ -81,20 +86,23 @@ function applyParamflags(rawFn, restype, argtypes, paramflags) {
81
86
  throw new TypeError(`paramflags[${idx}] is "out" but argtype ${idx} is not a POINTER(T)`);
82
87
  }
83
88
  }
84
- return { idx, name: pf.name, dir: pf.dir, default: pf.default, argtype, outType };
89
+ return { idx, name: pf.name, dir: pf.dir, default: pf.default, argtype, outType, simple: outType?._isSimpleCData === true && !isScalarSubclass(outType) };
85
90
  });
86
91
 
87
92
  const inputs = slots.filter((s) => s.dir !== "out");
88
- const outputs = slots.filter((s) => s.dir === "out");
93
+ const outputs = slots.filter((s) => s.dir !== "in");
89
94
 
90
95
  let errcheck = null;
91
96
 
92
- const paramflagsWrapper = function (...callArgs) {
97
+ const invokeWithFlags = (method, callArgs) => {
98
+ const checked = errcheck;
93
99
  const namedForm =
94
100
  callArgs.length === 1 &&
95
101
  callArgs[0] !== null &&
96
102
  typeof callArgs[0] === "object" &&
97
103
  !Buffer.isBuffer(callArgs[0]) &&
104
+ !ArrayBuffer.isView(callArgs[0]) &&
105
+ !(callArgs[0] instanceof ArrayBuffer) &&
98
106
  !Array.isArray(callArgs[0]) &&
99
107
  // Exclude struct/union proxies (they have _buffer)
100
108
  callArgs[0]._buffer === undefined;
@@ -120,43 +128,60 @@ function applyParamflags(rawFn, restype, argtypes, paramflags) {
120
128
  // Python: un parametro "out" è un'istanza del tipo puntato, passata per
121
129
  // riferimento (il suo Buffer).
122
130
  const outs = outputs.map((output) => {
123
- const instance = newOutInstance(output.outType, output.name);
131
+ const instance = output.dir === "inout" ? rawArgs[output.idx] : newOutInstance(output.outType, output.name);
124
132
  rawArgs[output.idx] = instance;
125
- return { instance, type: output.outType };
133
+ return { instance, type: output.outType, dir: output.dir, simple: output.simple };
126
134
  });
127
135
 
128
- const result = rawFn(...rawArgs);
129
-
130
- // Python: errcheck(result, func, args) riceve anche le istanze "out"; il
131
- // valore restituito è il risultato, salvo `args` stesso (allora le out).
132
- if (errcheck !== null) {
133
- const checked = errcheck(result, paramflagsWrapper, rawArgs);
134
- if (checked !== rawArgs) return checked;
136
+ const finish = (result) => {
137
+ // Returning the original args continues normal output unpacking.
138
+ if (checked !== null) {
139
+ const value = checked(result, paramflagsWrapper, rawArgs);
140
+ if (value !== rawArgs) return value;
141
+ }
142
+ if (outs.length === 0) return result;
143
+ const values = outs.map(({ instance, type, dir, simple }) => {
144
+ if (dir === "inout") return instance;
145
+ const convert = instance.__ctypes_from_outparam__;
146
+ if (convert === scalarOutparam) return simple ? instance.value : instance;
147
+ if (convert !== undefined) {
148
+ if (typeof convert !== "function") throw new TypeError("__ctypes_from_outparam__ must be callable");
149
+ return convert.call(instance);
150
+ }
151
+ if (typeof type === "function") return instance;
152
+ return type.toObject(instance._buffer);
153
+ });
154
+ return values.length === 1 ? values[0] : values;
155
+ };
156
+ // The private binding snapshots this handler and keeps adapter temporaries
157
+ // alive until output processing finishes, including on an async rejection.
158
+ const previous = rawFn.errcheck;
159
+ rawFn.errcheck = finish;
160
+ try {
161
+ return method === "callAsync" ? rawFn.callAsync(...rawArgs) : rawFn(...rawArgs);
162
+ } finally {
163
+ rawFn.errcheck = previous;
135
164
  }
136
-
137
- if (outs.length === 0) return result;
138
-
139
- // Python ctypes parity: quando ci sono out-params il return value è
140
- // SOLO le outs (singolo valore se 1, array se >1) — indipendentemente
141
- // da restype: il valore per i tipi semplici, l'istanza per Structure/Union.
142
- const values = outs.map(({ instance, type }) => {
143
- if (type._isSimpleCData) return instance.value;
144
- if (typeof type === "function") return instance;
145
- return type.toObject(instance._buffer);
146
- });
147
- return values.length === 1 ? values[0] : values;
148
165
  };
149
166
 
150
- Object.defineProperty(paramflagsWrapper, "errcheck", {
151
- get: () => errcheck,
152
- set: (callback) => {
153
- if (callback !== null && callback !== undefined && typeof callback !== "function") {
154
- throw new TypeError("errcheck must be a function or null");
155
- }
156
- errcheck = callback ?? null;
167
+ const paramflagsWrapper = (...args) => invokeWithFlags("call", args);
168
+ Object.defineProperties(paramflagsWrapper, {
169
+ funcName: { value: rawFn.funcName },
170
+ address: { value: rawFn.address },
171
+ _as_parameter_: { value: rawFn.address },
172
+ _ffi: { value: rawFn._ffi },
173
+ callAsync: { value: (...args) => invokeWithFlags("callAsync", args) },
174
+ errcheck: {
175
+ get: () => errcheck,
176
+ set: (callback) => {
177
+ if (callback !== null && callback !== undefined && typeof callback !== "function") {
178
+ throw new TypeError("errcheck must be a function or null");
179
+ }
180
+ errcheck = callback ?? null;
181
+ },
182
+ enumerable: false,
183
+ configurable: true,
157
184
  },
158
- enumerable: false,
159
- configurable: true,
160
185
  });
161
186
  return paramflagsWrapper;
162
187
  }
@@ -164,7 +189,7 @@ function applyParamflags(rawFn, restype, argtypes, paramflags) {
164
189
  // Istanza per un parametro "out": SimpleCData, Structure/Union class o
165
190
  // definizione struct()/union().
166
191
  function newOutInstance(type, name) {
167
- if (typeof type === "function" && (type._isSimpleCData || typeof type._buildStruct === "function")) {
192
+ if (typeof type === "function" && (type._isSimpleCData || type._isArrayType || typeof type._buildStruct === "function")) {
168
193
  return new type();
169
194
  }
170
195
  if (type && typeof type === "object" && typeof type.create === "function") {
@@ -175,13 +200,13 @@ function newOutInstance(type, name) {
175
200
 
176
201
  /**
177
202
  * Normalize a paramflags entry: Python tuple `[flag, name, default]`
178
- * (flag 1 = in, 2 = out, 4 = in defaulting to 0) or `{ dir, name, default }`.
203
+ * (flag 1 = in, 2 = out, 3 = inout, 4 = in defaulting to 0) or `{ dir, name, default }`.
179
204
  * @private
180
205
  */
181
206
  function toParamFlag(pf) {
182
207
  if (!Array.isArray(pf)) return pf;
183
208
  const [flag = 1, name, ...rest] = pf;
184
- const dir = flag & 2 ? "out" : "in";
209
+ const dir = (flag & 3) === 3 ? "inout" : flag & 2 ? "out" : "in";
185
210
  const result = { dir, name };
186
211
  if (rest.length > 0) result.default = rest[0];
187
212
  else if (flag & 4) result.default = 0;
@@ -193,7 +218,7 @@ function toParamFlag(pf) {
193
218
  * factory, enabling Python-style typed binding with in/out params.
194
219
  * @private
195
220
  */
196
- function attachBind(factory, restype, argtypes, abi) {
221
+ function attachBind(factory, restype, argtypes, abi, signature) {
197
222
  factory.bind = function bindWithFlags(library, symbolName, paramflags) {
198
223
  // Validate paramflags up-front so shape errors surface before the symbol
199
224
  // lookup (which may fail for unrelated reasons like missing export).
@@ -206,12 +231,14 @@ function attachBind(factory, restype, argtypes, abi) {
206
231
  }
207
232
  for (let i = 0; i < paramflags.length; i++) {
208
233
  const pf = paramflags[i];
209
- if (pf.dir === "out" && !(argtypes[i] && argtypes[i]._pointerTo)) {
234
+ if (pf.dir !== "in" && !(argtypes[i] && argtypes[i]._pointerTo)) {
210
235
  throw new TypeError(`paramflags[${i}] is "out" but argtype ${i} is not a POINTER(T)`);
211
236
  }
212
237
  }
213
- const rawFn = library.func(symbolName, restype, argtypes, abi ? { abi } : {});
214
- return applyParamflags(rawFn, restype, argtypes, paramflags);
238
+ const rawFn = library._createFunction(symbolName, restype, argtypes, abi ? { abi } : {}, signature);
239
+ const bound = applyParamflags(rawFn, restype, argtypes, paramflags);
240
+ prototypeOwners.set(bound, factory);
241
+ return bound;
215
242
  };
216
243
  return factory;
217
244
  }
@@ -219,16 +246,41 @@ function attachBind(factory, restype, argtypes, abi) {
219
246
  // Tipo funzione CFUNCTYPE / WINFUNCTYPE: chiamato con un indirizzo restituisce
220
247
  // una funzione chiamabile, con una funzione JS crea un callback C.
221
248
  function createFuncPtrType(native, typeName, abi) {
249
+ const cache = new Map();
250
+ const signatures = new WeakMap();
251
+ const typeKey = createTypeKey();
252
+ let recent;
222
253
  return function (restype, ...argtypes) {
254
+ const previous = recent?.deref();
255
+ if (previous !== undefined) {
256
+ const signature = signatures.get(previous);
257
+ let same = signature.restype === restype && signature.argtypes.length === argtypes.length;
258
+ for (let i = 0; same && i < argtypes.length; i++) same = signature.argtypes[i] === argtypes[i];
259
+ if (same) return previous;
260
+ }
261
+ const key = `${typeKey(restype)};${argtypes.map(typeKey).join(";")}`;
262
+ const cached = cache.get(key)?.deref();
263
+ if (cached !== undefined) {
264
+ recent = cache.get(key);
265
+ return cached;
266
+ }
223
267
  const nativeRestype = _toNativeReturnType(restype, native);
224
268
  const nativeArgtypes = _toNativeTypes(argtypes, native);
225
269
  const converters = argumentConverters(argtypes, native);
226
- const convertResult = resultConverter(restype);
270
+ const hasAdapters = converters.some((convert) => convert.requiresOwners);
271
+ const represent = resultConverter(restype);
272
+ const check = resultCheck(restype, typeName);
273
+ const convertResult = check === undefined ? represent : represent === undefined ? check : (value) => check(represent(value));
274
+ const signature = { nativeRestype, nativeArgtypes, converters, represent, check };
227
275
 
228
276
  function factory(addressOrFn, paramflags) {
277
+ let callback;
278
+ let released = false;
279
+ let activeCalls = 0;
229
280
  // Python ctypes parity: CFUNCTYPE(...)(jsFunc) wraps a JS function as a C callback.
230
281
  if (typeof addressOrFn === "function") {
231
- return createCallback(addressOrFn, restype, argtypes, native, abi);
282
+ callback = createCallback(addressOrFn, restype, argtypes, native, abi);
283
+ addressOrFn = callback.pointer;
232
284
  }
233
285
  // Python: prototype((name, dll)) / prototype((name, dll), paramflags)
234
286
  // binds an exported function of a library to this prototype.
@@ -256,59 +308,129 @@ function createFuncPtrType(native, typeName, abi) {
256
308
  if (abi) options.abi = abi;
257
309
  if (ownerLibrary) options.library = ownerLibrary;
258
310
  if (structResult(restype)) options.struct_buffer = true;
259
- const ffiFunc = new native.FFIFunction(address, null, nativeRestype, nativeArgtypes, options);
311
+ if (scalarResult(restype)) options.scalar_buffer = true;
312
+ let ffiFunc;
313
+ try {
314
+ ffiFunc = new native.FFIFunction(address, null, nativeRestype, nativeArgtypes, options);
315
+ } catch (error) {
316
+ callback?.release();
317
+ throw error;
318
+ }
260
319
 
261
320
  // Come le funzioni di CDLL: restype POINTER/CFUNCTYPE convertito, ed
262
321
  // errcheck applicato sul valore convertito.
263
- let jsErrcheck = null;
264
- const finish = (result, args) => {
265
- if (convertResult === undefined) return result;
266
- const converted = convertResult(result);
267
- return jsErrcheck === null ? converted : jsErrcheck(converted, callMethod, args);
322
+ const callState = { errcheck: null };
323
+ let checkedSync;
324
+ const finish = (result) => (convertResult === undefined ? result : convertResult(result));
325
+ const checkedCall = (method, args, checked) => {
326
+ const originalArgs = Array.isArray(args) ? args : Array.prototype.slice.call(args);
327
+ const resultHandler = (result) => checked(finish(result), callMethod, originalArgs);
328
+ const call = method === "call" ? (checkedSync ??= ffiFunc._makeCheckedCall()) : undefined;
329
+ return callWithResultHandler(ffiFunc, method, originalArgs, converters, resultHandler, hasAdapters || argumentsNeedOwners(originalArgs), call);
268
330
  };
269
331
 
270
- const callMethod = function (...args) {
332
+ const invoke = (args, checked) => {
333
+ if (checked !== null) return checkedCall("call", args, checked);
334
+ if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "call", args, converters, finish);
271
335
  return finish(ffiFunc.call(...convertArguments(args, converters)), args);
272
336
  };
337
+ let callMethod =
338
+ convertResult === undefined && !hasAdapters && converters.length <= 6
339
+ ? specializeCall(ffiFunc, "call", converters, callState, invoke)
340
+ : function (...args) {
341
+ return invoke(args, callState.errcheck);
342
+ };
273
343
 
344
+ const asyncCall = function (...args) {
345
+ if (callState.errcheck !== null) return checkedCall("callAsync", args, callState.errcheck);
346
+ if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, converters, finish);
347
+ return ffiFunc.callAsync(...convertArguments(args, converters)).then((result) => finish(result, args));
348
+ };
349
+ let callAsync = asyncCall;
350
+ let callbackProperties = {};
351
+ if (callback !== undefined) {
352
+ const assertLive = () => {
353
+ if (released) throw new Error("Callback has been released");
354
+ };
355
+ const release = () => {
356
+ if (activeCalls !== 0) throw new Error("Cannot release callback while calls to it are in progress");
357
+ if (!released) {
358
+ callback.release();
359
+ released = true;
360
+ }
361
+ };
362
+ const call = callMethod;
363
+ callMethod = function (...args) {
364
+ assertLive();
365
+ activeCalls++;
366
+ try {
367
+ return call(...args);
368
+ } finally {
369
+ activeCalls--;
370
+ }
371
+ };
372
+ callAsync = function (...args) {
373
+ assertLive();
374
+ activeCalls++;
375
+ try {
376
+ return asyncCall(...args).finally(() => activeCalls--);
377
+ } catch (error) {
378
+ activeCalls--;
379
+ throw error;
380
+ }
381
+ };
382
+ callbackProperties = Object.getOwnPropertyDescriptors(callback);
383
+ callbackProperties.release.value = release;
384
+ callbackProperties[Symbol.dispose].value = release;
385
+ callbackProperties._as_parameter_ = {
386
+ get() {
387
+ assertLive();
388
+ return callback.pointer;
389
+ },
390
+ };
391
+ }
274
392
  Object.defineProperties(callMethod, {
393
+ ...callbackProperties,
394
+ name: { value: "callMethod", configurable: true },
395
+ length: { value: 0, configurable: true },
275
396
  funcName: { value: `0x${address.toString(16)}` },
276
397
  address: { value: ffiFunc.address },
398
+ _as_parameter_: callbackProperties._as_parameter_ ?? { value: ffiFunc.address },
277
399
  _ffi: { value: ffiFunc },
278
400
  callAsync: {
279
- value: function (...args) {
280
- return ffiFunc.callAsync(...convertArguments(args, converters)).then((result) => finish(result, args));
281
- },
401
+ value: callAsync,
282
402
  writable: false,
283
403
  enumerable: false,
284
404
  configurable: false,
285
405
  },
286
406
  errcheck: {
287
407
  get() {
288
- return ffiFunc._errcheck ?? null;
408
+ return callState.errcheck;
289
409
  },
290
410
  set(callback) {
291
- ffiFunc._errcheck = callback;
292
- if (convertResult !== undefined) {
293
- jsErrcheck = callback ?? null;
294
- } else {
295
- ffiFunc.setErrcheck(callback);
296
- }
411
+ callback = callback ?? null;
412
+ if (callback !== null && typeof callback !== "function") throw new TypeError("errcheck must be a function or null");
413
+ callState.errcheck = callback;
297
414
  },
298
415
  enumerable: false,
299
416
  configurable: true,
300
417
  },
301
418
  });
302
419
 
420
+ if (callback !== undefined) keepFunctionOwner(callMethod, callback);
421
+ prototypeOwners.set(callMethod, factory);
303
422
  return callMethod;
304
423
  }
305
424
 
306
425
  // Attach metadata + paramflags binding to the factory
307
426
  factory.restype = restype;
308
- factory.argtypes = argtypes;
427
+ factory.argtypes = argtypes.slice();
309
428
  factory._isFuncPtr = true;
310
- attachBind(factory, restype, argtypes, abi);
429
+ attachBind(factory, restype, argtypes, abi, signature);
311
430
 
431
+ signatures.set(factory, { restype, argtypes });
432
+ cacheWeakValue(cache, key, factory);
433
+ recent = cache.get(key);
312
434
  return factory;
313
435
  };
314
436
  }
package/lib/core/types.js CHANGED
@@ -26,6 +26,8 @@
26
26
  * Dimensione e allineamento sono quelli del layout JS (layout.js, `_align_`).
27
27
  */
28
28
 
29
+ import { cacheWeakValue } from "../utils/cache.js";
30
+
29
31
  // ArrayType nativi costruiti per gli array di Structure/Union (gli array JS
30
32
  // espongono `_native` in sola lettura).
31
33
  const nativeArrayTypes = new WeakMap();
@@ -39,10 +41,10 @@ function byteRun(st, native, offset, length) {
39
41
  st.addField(`__byte@${offset}`, native.CType.UINT8);
40
42
  return;
41
43
  }
42
- let arrayType = byteArrayTypes.get(length);
44
+ let arrayType = byteArrayTypes.get(length)?.deref();
43
45
  if (arrayType === undefined) {
44
46
  arrayType = new native.ArrayType(native.CType.UINT8, length);
45
- byteArrayTypes.set(length, arrayType);
47
+ cacheWeakValue(byteArrayTypes, length, arrayType);
46
48
  }
47
49
  st.addField(`__bytes@${offset}`, arrayType);
48
50
  }
@@ -106,6 +108,9 @@ function hasUnalignedFields(def) {
106
108
  */
107
109
  function _buildNativeStructType(def, native) {
108
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
+ }
109
114
  const st = new native.StructType({ union: !!def.isUnion, alignment: def.alignment, memoryClass: hasUnalignedFields(def) });
110
115
  const fits = (alignment, offset) => alignment <= def.alignment && offset % alignment === 0;
111
116