node-ctypes 2.3.0 → 2.4.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.
- package/CHANGELOG.md +932 -0
- package/README.md +446 -99
- package/build/Release/ctypes-darwin-arm64.node +0 -0
- package/build/Release/ctypes-darwin-x64.node +0 -0
- package/build/Release/ctypes-linux-arm64-musl.node +0 -0
- package/build/Release/ctypes-linux-arm64.node +0 -0
- package/build/Release/ctypes-linux-x64-musl.node +0 -0
- package/build/Release/ctypes-linux-x64.node +0 -0
- package/build/Release/ctypes-win32-arm64.node +0 -0
- package/build/Release/ctypes-win32-x64.node +0 -0
- package/lib/core/Library.js +79 -62
- package/lib/core/callback.js +7 -3
- package/lib/core/conversions.js +226 -34
- package/lib/core/funcptr.js +115 -57
- package/lib/core/types.js +7 -2
- package/lib/index.d.ts +119 -54
- package/lib/index.js +10 -8
- package/lib/memory/buffer.js +39 -8
- package/lib/memory/operations.js +4 -6
- package/lib/memory/pointer.js +105 -38
- package/lib/platform/win_types.js +8 -3
- package/lib/structures/Structure.js +8 -39
- package/lib/structures/helpers/array.js +31 -12
- package/lib/structures/helpers/bitfield.js +17 -8
- package/lib/structures/helpers/common.js +218 -29
- package/lib/structures/helpers/layout.js +17 -3
- package/lib/structures/helpers/struct.js +25 -26
- package/lib/structures/helpers/union.js +32 -22
- package/lib/types/SimpleCData.js +11 -32
- package/lib/types/primitives.js +34 -16
- package/lib/utils/cache.js +34 -2
- package/package.json +3 -1
package/lib/core/funcptr.js
CHANGED
|
@@ -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, structResult } from "./conversions.js";
|
|
41
41
|
import { callback as createCallback } from "./callback.js";
|
|
42
|
+
import { isScalarSubclass, 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
|
-
|
|
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
|
|
93
|
+
const outputs = slots.filter((s) => s.dir !== "in");
|
|
89
94
|
|
|
90
95
|
let errcheck = null;
|
|
91
96
|
|
|
92
|
-
const
|
|
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
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
if (
|
|
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
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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;
|
|
@@ -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
|
|
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.
|
|
214
|
-
|
|
238
|
+
const rawFn = library._createFunction(symbolName, restype, argtypes, abi ? { abi } : {});
|
|
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,17 +246,39 @@ 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
|
-
const converters = argumentConverters(argtypes, native);
|
|
226
|
-
const convertResult = resultConverter(restype);
|
|
227
269
|
|
|
228
270
|
function factory(addressOrFn, paramflags) {
|
|
229
271
|
// Python ctypes parity: CFUNCTYPE(...)(jsFunc) wraps a JS function as a C callback.
|
|
230
272
|
if (typeof addressOrFn === "function") {
|
|
231
|
-
|
|
273
|
+
const callback = createCallback(addressOrFn, restype, argtypes, native, abi);
|
|
274
|
+
prototypeOwners.set(callback, factory);
|
|
275
|
+
return callback;
|
|
232
276
|
}
|
|
277
|
+
const converters = argumentConverters(argtypes, native);
|
|
278
|
+
const hasAdapters = converters.some((convert) => convert.requiresOwners);
|
|
279
|
+
const represent = resultConverter(restype);
|
|
280
|
+
const check = resultCheck(restype, typeName);
|
|
281
|
+
const convertResult = check === undefined ? represent : represent === undefined ? check : (value) => check(represent(value));
|
|
233
282
|
// Python: prototype((name, dll)) / prototype((name, dll), paramflags)
|
|
234
283
|
// binds an exported function of a library to this prototype.
|
|
235
284
|
let ownerLibrary;
|
|
@@ -256,27 +305,35 @@ function createFuncPtrType(native, typeName, abi) {
|
|
|
256
305
|
if (abi) options.abi = abi;
|
|
257
306
|
if (ownerLibrary) options.library = ownerLibrary;
|
|
258
307
|
if (structResult(restype)) options.struct_buffer = true;
|
|
308
|
+
if (scalarResult(restype)) options.scalar_buffer = true;
|
|
259
309
|
const ffiFunc = new native.FFIFunction(address, null, nativeRestype, nativeArgtypes, options);
|
|
260
310
|
|
|
261
311
|
// Come le funzioni di CDLL: restype POINTER/CFUNCTYPE convertito, ed
|
|
262
312
|
// errcheck applicato sul valore convertito.
|
|
263
313
|
let jsErrcheck = null;
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
314
|
+
let checkedSync;
|
|
315
|
+
const finish = (result) => (convertResult === undefined ? result : convertResult(result));
|
|
316
|
+
const checkedCall = (method, args, checked) => {
|
|
317
|
+
const resultHandler = (result) => checked(finish(result), callMethod, args);
|
|
318
|
+
const call = method === "call" ? (checkedSync ??= ffiFunc._makeCheckedCall()) : undefined;
|
|
319
|
+
return callWithResultHandler(ffiFunc, method, args, converters, resultHandler, hasAdapters || argumentsNeedOwners(args), call);
|
|
268
320
|
};
|
|
269
321
|
|
|
270
322
|
const callMethod = function (...args) {
|
|
323
|
+
if (jsErrcheck !== null) return checkedCall("call", args, jsErrcheck);
|
|
324
|
+
if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "call", args, converters, finish);
|
|
271
325
|
return finish(ffiFunc.call(...convertArguments(args, converters)), args);
|
|
272
326
|
};
|
|
273
327
|
|
|
274
328
|
Object.defineProperties(callMethod, {
|
|
275
329
|
funcName: { value: `0x${address.toString(16)}` },
|
|
276
330
|
address: { value: ffiFunc.address },
|
|
331
|
+
_as_parameter_: { value: ffiFunc.address },
|
|
277
332
|
_ffi: { value: ffiFunc },
|
|
278
333
|
callAsync: {
|
|
279
334
|
value: function (...args) {
|
|
335
|
+
if (jsErrcheck !== null) return checkedCall("callAsync", args, jsErrcheck);
|
|
336
|
+
if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, converters, finish);
|
|
280
337
|
return ffiFunc.callAsync(...convertArguments(args, converters)).then((result) => finish(result, args));
|
|
281
338
|
},
|
|
282
339
|
writable: false,
|
|
@@ -285,30 +342,31 @@ function createFuncPtrType(native, typeName, abi) {
|
|
|
285
342
|
},
|
|
286
343
|
errcheck: {
|
|
287
344
|
get() {
|
|
288
|
-
return
|
|
345
|
+
return jsErrcheck;
|
|
289
346
|
},
|
|
290
347
|
set(callback) {
|
|
291
|
-
|
|
292
|
-
if (
|
|
293
|
-
|
|
294
|
-
} else {
|
|
295
|
-
ffiFunc.setErrcheck(callback);
|
|
296
|
-
}
|
|
348
|
+
callback = callback ?? null;
|
|
349
|
+
if (callback !== null && typeof callback !== "function") throw new TypeError("errcheck must be a function or null");
|
|
350
|
+
jsErrcheck = callback;
|
|
297
351
|
},
|
|
298
352
|
enumerable: false,
|
|
299
353
|
configurable: true,
|
|
300
354
|
},
|
|
301
355
|
});
|
|
302
356
|
|
|
357
|
+
prototypeOwners.set(callMethod, factory);
|
|
303
358
|
return callMethod;
|
|
304
359
|
}
|
|
305
360
|
|
|
306
361
|
// Attach metadata + paramflags binding to the factory
|
|
307
362
|
factory.restype = restype;
|
|
308
|
-
factory.argtypes = argtypes;
|
|
363
|
+
factory.argtypes = argtypes.slice();
|
|
309
364
|
factory._isFuncPtr = true;
|
|
310
365
|
attachBind(factory, restype, argtypes, abi);
|
|
311
366
|
|
|
367
|
+
signatures.set(factory, { restype, argtypes });
|
|
368
|
+
cacheWeakValue(cache, key, factory);
|
|
369
|
+
recent = cache.get(key);
|
|
312
370
|
return factory;
|
|
313
371
|
};
|
|
314
372
|
}
|
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
|
|
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
|
|