node-ctypes 2.13.2 → 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 (42) hide show
  1. package/CHANGELOG.md +71 -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.d.ts +3 -0
  22. package/lib/index.js +2 -1
  23. package/lib/memory/buffer.js +1 -1
  24. package/lib/memory/mirror.js +2 -2
  25. package/lib/memory/operations.js +2 -1
  26. package/lib/memory/ownership.js +218 -0
  27. package/lib/memory/pointer.js +6 -1
  28. package/lib/platform/win_types.js +1 -1
  29. package/lib/structures/Structure.js +50 -37
  30. package/lib/structures/helpers/array.js +27 -13
  31. package/lib/structures/helpers/bitfield.js +1 -1
  32. package/lib/structures/helpers/common.js +3 -368
  33. package/lib/structures/helpers/fields.js +111 -0
  34. package/lib/structures/helpers/layout.js +44 -57
  35. package/lib/structures/helpers/struct.js +19 -108
  36. package/lib/structures/helpers/union.js +13 -114
  37. package/lib/structures/helpers/wrap.js +1 -1
  38. package/lib/structures/protocol.js +8 -0
  39. package/lib/types/SimpleCData.js +2 -1
  40. package/lib/types/primitives.js +2 -1
  41. package/lib/types/scalar-protocol.js +120 -0
  42. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -7,6 +7,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.15.0] - 2026-11-20
11
+
12
+ ### Changed
13
+
14
+ - Reading a nested `Structure` or `Union` field returns a fresh view each
15
+ time, as in CPython: `s.inner === s.inner` is now `false`. Both views
16
+ still refer to the same C bytes. Keep a reference to the view if your
17
+ code relies on JavaScript object identity or attaches properties to it.
18
+ - `from_buffer()`, `from_address()`, nested fields and array elements now
19
+ expose existing `Structure` or `Union` storage without running the user's
20
+ constructor or JavaScript instance field initializers. Explicit `new T()`
21
+ still runs them. This does not change by-value callback arguments: their
22
+ constructor is still called with no arguments.
23
+
24
+ ### Fixed
25
+
26
+ - **libffi headers generated on Windows**: with `core.autocrlf` the templates
27
+ are checked out with CRLF line endings, and `npm run generate-ffi-headers`
28
+ silently left out of `fficonfig.h` the `FFI_MMAP_EXEC_WRIT` block of macOS
29
+ x64, whose marker contains line feeds (`ffi.h` only got mixed line endings).
30
+ The generator now reads its templates with LF line endings, and stops with an
31
+ error when a marker it replaces is missing. The published binaries were not
32
+ affected: in CI only the Windows checkouts use CRLF, and the Windows builds
33
+ do not use that block.
34
+
35
+ ## [2.14.0] - 2026-11-15
36
+
37
+ ### Added
38
+
39
+ - **`Version.libffi`**: the version of the libffi node-ctypes is built with
40
+ (`ffi_get_version()`), for example `"3.8.1"`.
41
+
42
+ ### Changed
43
+
44
+ - **Callbacks on hardened Linux**: libffi is built as its `configure` does on
45
+ Linux x86-64 and AArch64, with static trampolines and `memfd_create`.
46
+ - The code of a callback now comes from a table inside `ctypes.node`, mapped
47
+ read and execute: closures no longer need a page that is writable and
48
+ executable. When the table cannot be mapped, libffi falls back to the
49
+ dynamic trampolines.
50
+ - In that fallback, when writable and executable pages are refused (SELinux,
51
+ PaX, Memory-Deny-Write-Execute), libffi maps an anonymous memory file
52
+ twice instead of looking for a temporary file in `TMPDIR`, `/tmp`,
53
+ `/var/tmp`, `/dev/shm` or `HOME`. Before, a process with no directory both
54
+ writable and executable (a read-only container running as a regular user,
55
+ for example) could not create callbacks: `Failed to allocate FFI closure`.
56
+ - `ctypes.node` now imports `memfd_create` (glibc 2.27), within the glibc
57
+ 2.28 baseline of the Linux binaries; musl has had it since 1.1.20.
58
+
59
+ ### Fixed
60
+
61
+ - **`ffi_closure` layout on macOS ARM64**: the generated `ffi.h` chose the
62
+ layout of `ffi_closure` with `FFI_EXEC_TRAMPOLINE_TABLE`, a macro of
63
+ `fficonfig.h` that it does not include. node-ctypes, and the libffi sources
64
+ that include `ffi.h` first, saw a 48-byte closure with `cif` at offset 24,
65
+ while the closure allocator and `ffi_prep_closure_loc` used the 40-byte
66
+ layout with `cif` at 16, as the header generated by Autotools does. The
67
+ header now tests the platform itself (macOS ARM64), so every source sees the
68
+ same layout. Callbacks were not affected: node-ctypes only allocates a closure
69
+ (48 bytes were enough) and never reads its fields.
70
+ - **`FFI_TYPE_LONGDOUBLE` where `long double` is a `double`**: the generated
71
+ `ffi.h` kept it distinct from `FFI_TYPE_DOUBLE` everywhere, while libffi's
72
+ `configure` makes them equal unless `long double` is larger (not on macOS
73
+ ARM64 nor with MSVC). On AArch64 libffi would then have treated an 8-byte
74
+ `long double` as the 128-bit type. The header now applies the same rule, from
75
+ the compiler's `__LDBL_MANT_DIG__` and `__DBL_MANT_DIG__`. node-ctypes does
76
+ not use `long double` yet, so nothing changes for existing code.
77
+
10
78
  ## [2.13.2] - 2026-11-15
11
79
 
12
80
  ### Fixed
@@ -1467,7 +1535,9 @@ It contains breaking changes: see [Migrating from 1.x](guides/python.md#migratin
1467
1535
 
1468
1536
  Initial releases.
1469
1537
 
1470
- [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.13.2...HEAD
1538
+ [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.15.0...HEAD
1539
+ [2.15.0]: https://github.com/dmazzella/node-ctypes/compare/v2.14.0...v2.15.0
1540
+ [2.14.0]: https://github.com/dmazzella/node-ctypes/compare/v2.13.2...v2.14.0
1471
1541
  [2.13.2]: https://github.com/dmazzella/node-ctypes/compare/v2.13.1...v2.13.2
1472
1542
  [2.13.1]: https://github.com/dmazzella/node-ctypes/compare/v2.13.0...v2.13.1
1473
1543
  [2.13.0]: https://github.com/dmazzella/node-ctypes/compare/v2.12.2...v2.13.0
Binary file
Binary file
@@ -40,7 +40,10 @@
40
40
  */
41
41
 
42
42
  import { _toNativeReturnType } from "./types.js";
43
- import { adaptCallbackFunction, argumentConverters, argumentsNeedOwners, callWithArgumentOwners, callWithResultHandler, convertArguments, resultCheck, resultConverter, scalarResult, specializeCall, structResult } from "./conversions.js";
43
+ import { adaptCallbackFunction } from "./callback-conversions.js";
44
+ import { argumentConverters, convertArguments } from "./conversions.js";
45
+ import { argumentsNeedOwners, callWithArgumentOwners, createCheckedInvoker, specializeCall } from "./invocation.js";
46
+ import { composeResult, resultCheck, resultConverter, scalarResult, structResult } from "./results.js";
44
47
  import { createTypeKey } from "../utils/cache.js";
45
48
  import { callOn } from "./executor.js";
46
49
 
@@ -74,13 +77,49 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
74
77
  return key;
75
78
  };
76
79
 
80
+ function captureResult(cdll, name, type) {
81
+ return { represent: resultConverter(type, native), check: cdll._resultCheck(type, name) };
82
+ }
83
+
84
+ class AttributeSignature {
85
+ // The exposed array is stable; only assignment changes the bound signature.
86
+ argtypes = [];
87
+ #declaredArgtypes;
88
+ #converters;
89
+ #restype;
90
+ #result;
91
+
92
+ setArguments(value) {
93
+ const types = [...(value ?? [])];
94
+ const converters = argumentConverters(types, native);
95
+ this.argtypes.splice(0, this.argtypes.length, ...types);
96
+ this.#declaredArgtypes = types;
97
+ this.#converters = converters;
98
+ }
99
+
100
+ returnType(cdll) {
101
+ return this.#restype === undefined ? cdll._defaultRestype() : this.#restype;
102
+ }
103
+
104
+ setResult(cdll, name, value) {
105
+ const type = value === undefined ? cdll._defaultRestype() : value;
106
+ this.#result = captureResult(cdll, name, type);
107
+ this.#restype = value;
108
+ }
109
+
110
+ bind(cdll, name) {
111
+ const type = this.returnType(cdll);
112
+ const { represent, check } = this.#result ?? captureResult(cdll, name, type);
113
+ this.#declaredArgtypes ??= [];
114
+ this.#converters ??= [];
115
+ return cdll._createFunction(name, type, this.#declaredArgtypes, {}, { represent, check, converters: this.#converters });
116
+ }
117
+ }
118
+
77
119
  class FunctionWrapper {
78
120
  constructor(cdll, name) {
79
- const argtypes = [];
80
- let declaredArgtypes = [];
81
- let converters = [];
82
- let restype = undefined;
83
- let resultSignature;
121
+ let declaration;
122
+ const signature = () => (declaration ??= new AttributeSignature());
84
123
  let errcheck = null;
85
124
  let cachedFunc = null;
86
125
 
@@ -90,9 +129,7 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
90
129
  // argtypes / restype, come in Python.
91
130
  const resolve = () => {
92
131
  if (!cachedFunc) {
93
- const returnType = restype === undefined ? cdll._defaultRestype() : restype;
94
- const signature = resultSignature ?? { represent: resultConverter(returnType), check: cdll._resultCheck(returnType, name) };
95
- cachedFunc = cdll._createFunction(name, returnType, declaredArgtypes, {}, { ...signature, converters });
132
+ cachedFunc = signature().bind(cdll, name);
96
133
  Object.defineProperty(cachedFunc, kErrcheckFunc, { value: func });
97
134
  if (errcheck !== null) {
98
135
  cachedFunc.errcheck = errcheck;
@@ -116,24 +153,17 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
116
153
  address: { get: () => resolve().address },
117
154
  _as_parameter_: { get: () => resolve().address },
118
155
  argtypes: {
119
- get: () => argtypes,
156
+ get: () => signature().argtypes,
120
157
  set: (value) => {
121
- // Python: argtypes = None toglie i tipi degli argomenti.
122
- const types = [...(value ?? [])];
123
- const next = argumentConverters(types, native);
124
- argtypes.splice(0, argtypes.length, ...types);
125
- declaredArgtypes = types;
126
- converters = next;
158
+ signature().setArguments(value);
127
159
  cachedFunc = null; // Invalidate cache
128
160
  },
129
161
  configurable: true,
130
162
  },
131
163
  restype: {
132
- get: () => (restype === undefined ? cdll._defaultRestype() : restype),
164
+ get: () => signature().returnType(cdll),
133
165
  set: (value) => {
134
- const returnType = value === undefined ? cdll._defaultRestype() : value;
135
- resultSignature = { represent: resultConverter(returnType), check: cdll._resultCheck(returnType, name) };
136
- restype = value;
166
+ signature().setResult(cdll, name, value);
137
167
  cachedFunc = null; // Invalidate cache
138
168
  },
139
169
  configurable: true,
@@ -266,39 +296,30 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
266
296
  * @protected
267
297
  */
268
298
  _createFunction(name, returnType, argTypes = [], options = {}, signature) {
269
- // Propagate library-level use_last_error / use_errno to the FFIFunction
270
- const mergedOptions = {
299
+ const nativeOptions = {
271
300
  ...options,
272
301
  ...(this._use_last_error ? { use_last_error: true } : {}),
273
302
  ...(this._use_errno ? { use_errno: true } : {}),
274
303
  ...(structResult(returnType) ? { struct_buffer: true } : {}),
275
304
  ...(scalarResult(returnType) ? { scalar_buffer: true } : {}),
276
305
  };
277
- const ffiFunc = this._lib.func(name, signature?.nativeRestype ?? _toNativeReturnType(returnType, native), signature?.nativeArgtypes ?? _toNativeTypes(argTypes, native), mergedOptions);
278
-
279
- // =========================================================================
280
- // OPTIMIZATION: Create specialized wrapper based on argument types
281
- // For primitive-only args, bypass the processing loop entirely
282
- // =========================================================================
306
+ const ffiFunc = this._lib.func(name, signature?.nativeRestype ?? _toNativeReturnType(returnType, native), signature?.nativeArgtypes ?? _toNativeTypes(argTypes, native), nativeOptions);
307
+ // Bind first: a missing symbol must fail before reading from_param or _check_retval_ here.
308
+ return CDLL.#wrapFunction(this, ffiFunc, name, returnType, argTypes, signature);
309
+ }
283
310
 
311
+ static #wrapFunction(library, ffiFunc, name, returnType, argTypes, signature) {
284
312
  // Conversione degli argomenti come il from_param di base di Python
285
313
  // (vedi conversions.js): un convertitore per posizione dichiarata.
286
314
  const C = signature?.converters ?? argumentConverters(argTypes, native);
287
315
  const convertAll = (args) => convertArguments(args, C);
288
316
  const hasAdapters = C.some((convert) => convert.requiresOwners);
289
- const baseConvert = signature === undefined ? resultConverter(returnType) : signature.represent;
290
- const check = signature === undefined ? this._resultCheck(returnType, name) : signature.check;
291
- const convertResult = check === undefined ? baseConvert : baseConvert === undefined ? check : (result) => check(baseConvert(result));
317
+ const baseConvert = signature === undefined ? resultConverter(returnType, native) : signature.represent;
318
+ const check = signature === undefined ? library._resultCheck(returnType, name) : signature.check;
319
+ const convertResult = composeResult(baseConvert, check);
292
320
  const captureHere = convertResult === undefined;
293
321
  const callState = { errcheck: null };
294
- let checkedSync;
295
- const checkedCall = (method, args, checked, target) => {
296
- const originalArgs = Array.isArray(args) ? args : Array.prototype.slice.call(args);
297
- const func = errcheckFunc();
298
- const finish = (result) => checked(convertResult === undefined ? result : convertResult(result), func, originalArgs);
299
- const call = method === "call" ? (checkedSync ??= ffiFunc._makeCheckedCall()) : undefined;
300
- return callWithResultHandler(ffiFunc, method, originalArgs, C, finish, hasAdapters || argumentsNeedOwners(originalArgs), call, target);
301
- };
322
+ const checkedCall = createCheckedInvoker(ffiFunc, C, hasAdapters, convertResult, () => exposed[kErrcheckFunc] ?? exposed);
302
323
  const ownedCall = (method, args) => callWithArgumentOwners(ffiFunc, method, args, C);
303
324
  const invoke = (method, args, checked) => {
304
325
  if (captureHere && checked !== null) return checkedCall(method, args, checked);
@@ -310,7 +331,7 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
310
331
  // callOn(): the same call on the Executor of `target` (this invocation's own).
311
332
  let onExecutor = (target, args) => {
312
333
  if (captureHere && callState.errcheck !== null) return checkedCall("callAsync", args, callState.errcheck, target);
313
- if (captureHere && (hasAdapters || argumentsNeedOwners(args))) return callWithArgumentOwners(ffiFunc, "callAsync", args, C, undefined, undefined, undefined, target);
334
+ if (captureHere && (hasAdapters || argumentsNeedOwners(args))) return callWithArgumentOwners(ffiFunc, "callAsync", args, C, undefined, target);
314
335
  return ffiFunc.callOn(target, ...convertAll(args));
315
336
  };
316
337
 
@@ -320,6 +341,7 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
320
341
  const rawCall = callMethod;
321
342
  const rawAsync = asyncCallMethod;
322
343
  const finish = (result) => convertResult(result);
344
+ const finishAsync = (result) => convertResult(result, true);
323
345
  callMethod = function (...args) {
324
346
  if (callState.errcheck !== null) return checkedCall("call", args, callState.errcheck);
325
347
  if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "call", args, C, finish);
@@ -327,22 +349,22 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
327
349
  };
328
350
  asyncCallMethod = function (...args) {
329
351
  if (callState.errcheck !== null) return checkedCall("callAsync", args, callState.errcheck);
330
- if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, C, finish);
331
- return rawAsync.apply(this, args).then((result) => finish(result, args));
352
+ if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, C, finishAsync);
353
+ return rawAsync.apply(this, args).then((result) => finishAsync(result, args));
332
354
  };
333
355
  const rawOn = onExecutor;
334
356
  onExecutor = (target, args) => {
335
357
  if (callState.errcheck !== null) return checkedCall("callAsync", args, callState.errcheck, target);
336
- if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, C, finish, undefined, undefined, target);
337
- return rawOn(target, args).then((result) => finish(result, args));
358
+ if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, C, finishAsync, target);
359
+ return rawOn(target, args).then((result) => finishAsync(result, args));
338
360
  };
339
361
  }
340
362
 
341
363
  // If use_last_error / use_errno is set on the library, wrap callMethod
342
364
  // so the most-recently-called FFIFunction is remembered on the library.
343
- if (this._use_last_error || this._use_errno) {
365
+ if (library._use_last_error || library._use_errno) {
344
366
  // The library itself, not its Proxy: this write runs on every call.
345
- const self = libraryTargets.get(this) ?? this;
367
+ const self = libraryTargets.get(library) ?? library;
346
368
  const origCall = callMethod;
347
369
  callMethod = function (...args) {
348
370
  self._lastCalledFfi = ffiFunc;
@@ -367,14 +389,10 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
367
389
  // stessi argomenti. Senza il wrapper JS il call site resta monomorfico:
368
390
  // le closure di specializeCall condividono il feedback di V8.
369
391
  let exposed = callMethod;
370
- if (convertResult === undefined && !hasAdapters && !this._use_last_error && !this._use_errno && C.every((convert) => convert.passesPrimitives === true || convert.passesStrings === true)) {
392
+ if (convertResult === undefined && !hasAdapters && !library._use_last_error && !library._use_errno && C.every((convert) => convert.passesPrimitives === true || convert.passesStrings === true)) {
371
393
  exposed = ffiFunc._makeEntry(callMethod, name) ?? callMethod;
372
394
  }
373
395
 
374
- // Python: errcheck riceve la funzione su cui è impostato (l'attributo
375
- // della libreria, se passa da lì), qualunque sia il restype.
376
- const errcheckFunc = () => exposed[kErrcheckFunc] ?? exposed;
377
-
378
396
  // Aggiungi metadata come proprietà non-enumerable per non interferire
379
397
  Object.defineProperties(exposed, {
380
398
  funcName: { value: name },
@@ -0,0 +1,123 @@
1
+ /** Convert the native callback's arguments to JS and its return value back to C. */
2
+ import { encodeWide } from "../memory/buffer.js";
3
+ import { kFromCallbackBytes } from "../structures/Structure.js";
4
+ import { isScalarSubclass, scalarView } from "../types/scalar-protocol.js";
5
+ import { buildWrapper } from "../structures/helpers/wrap.js";
6
+ import { coerceObject } from "./conversions.js";
7
+
8
+ const reflectApply = Reflect.apply;
9
+
10
+ /**
11
+ * Adapt a JS function used as a C callback to Python semantics: arguments
12
+ * declared `POINTER(T)` are passed as pointer objects (`null` for NULL), and an
13
+ * object returned by the function (pointer, SimpleCData instance, ...) is
14
+ * converted like an argument.
15
+ *
16
+ * @param {Function} fn - JS callback
17
+ * @param {Array} argTypes - Declared argument types
18
+ * @returns {Function} Function to register with the native callback
19
+ */
20
+ export function adaptCallbackFunction(fn, argTypes, returnType, native) {
21
+ const scalarTypes = argTypes.map((type) => (isScalarSubclass(type) ? type : null));
22
+ const hasScalars = scalarTypes.some((type) => type !== null);
23
+ const pointerTypes = argTypes.map((t) => (t !== null && typeof t === "object" && t._pointerTo !== undefined ? t : null));
24
+ const hasPointers = pointerTypes.some((t) => t !== null);
25
+ // The native trampoline supplies a buffer for each by-value aggregate.
26
+ const structViews = argTypes.map(structView);
27
+ const hasStructs = structViews.some((view) => view !== null);
28
+ const variantArgs = argTypes.map((type) => type?._isVariantBool === true);
29
+ const hasVariants = variantArgs.some(Boolean);
30
+ const variantResult = returnType?._isVariantBool === true;
31
+ const toResult = stringResult(returnType, native);
32
+ const convertResult = (result) => {
33
+ if (variantResult) return returnType.from_param(result);
34
+ if (toResult !== undefined && typeof result === "string") return toResult(result);
35
+ if (result === null || (typeof result !== "object" && typeof result !== "function")) return result;
36
+ return result._isSimpleCDataInstance === true ? result.value : coerceObject(result);
37
+ };
38
+ if (!hasScalars && !hasVariants && !hasPointers && !hasStructs) {
39
+ // The native trampoline passes exactly argTypes.length values with an
40
+ // undefined receiver. Like CPython (tp_call), the handler is invoked
41
+ // directly: own `call`/`apply` properties are not consulted.
42
+ switch (argTypes.length) {
43
+ case 0:
44
+ return () => convertResult(fn());
45
+ case 1:
46
+ return (a0) => convertResult(fn(a0));
47
+ case 2:
48
+ return (a0, a1) => convertResult(fn(a0, a1));
49
+ case 3:
50
+ return (a0, a1, a2) => convertResult(fn(a0, a1, a2));
51
+ default:
52
+ return (...args) => convertResult(reflectApply(fn, undefined, args));
53
+ }
54
+ }
55
+ return (...args) => {
56
+ if (hasScalars) {
57
+ for (let i = 0; i < scalarTypes.length; i++) {
58
+ if (scalarTypes[i] !== null) args[i] = scalarView(scalarTypes[i], args[i]);
59
+ }
60
+ }
61
+ if (hasVariants) {
62
+ for (let i = 0; i < variantArgs.length; i++) {
63
+ if (variantArgs[i] && scalarTypes[i] === null) args[i] = args[i] !== 0;
64
+ }
65
+ }
66
+ if (hasPointers) {
67
+ for (let i = 0; i < pointerTypes.length; i++) {
68
+ const T = pointerTypes[i];
69
+ if (T !== null && args[i] !== null) {
70
+ args[i] = T.fromAddress(args[i]);
71
+ }
72
+ }
73
+ }
74
+ if (hasStructs) {
75
+ for (let i = 0; i < structViews.length; i++) {
76
+ if (structViews[i] !== null) args[i] = structViews[i](args[i]);
77
+ }
78
+ }
79
+ return convertResult(reflectApply(fn, undefined, args));
80
+ };
81
+ }
82
+
83
+ /**
84
+ * View of a struct/union argument of a callback (Buffer with a copy of the
85
+ * C value): an instance of the class, or of the struct()/union() definition.
86
+ *
87
+ * @returns {Function|null} Converter, null for other argument types
88
+ */
89
+ function structView(type) {
90
+ if (typeof type === "function" && typeof type._buildStruct === "function") return type[kFromCallbackBytes].bind(type);
91
+ if (type !== null && typeof type === "object" && type._isStructType === true) {
92
+ let handler;
93
+ return (buf) => {
94
+ handler ??= buildWrapper(type, { instanceTag: "StructInstance", exposeAnonymous: true });
95
+ return new Proxy(buf, handler);
96
+ };
97
+ }
98
+ return null;
99
+ }
100
+
101
+ /**
102
+ * Result of a callback whose restype is c_char_p / c_wchar_p and that returns
103
+ * a JS string: a NUL-terminated buffer, kept alive as long as the callback
104
+ * (Python keeps it forever, with "RuntimeWarning: memory leak in callback
105
+ * function"). Buffers are cached by value, so a callback that returns the
106
+ * same strings does not accumulate memory.
107
+ *
108
+ * @returns {Function|undefined} Converter, undefined for other restypes
109
+ */
110
+ function stringResult(returnType, native) {
111
+ if (native === undefined || typeof returnType !== "function" || returnType._isSimpleCData !== true) return undefined;
112
+ const wide = returnType._type === native.CType.WSTRING;
113
+ if (!wide && returnType._type !== native.CType.STRING) return undefined;
114
+ const kept = new Map();
115
+ return (value) => {
116
+ let buf = kept.get(value);
117
+ if (buf === undefined) {
118
+ buf = wide ? Buffer.concat([encodeWide(value, native.WCHAR_SIZE), Buffer.alloc(native.WCHAR_SIZE)]) : Buffer.from(`${value}\0`, "utf8");
119
+ kept.set(value, buf);
120
+ }
121
+ return buf;
122
+ };
123
+ }
@@ -54,11 +54,18 @@
54
54
  */
55
55
 
56
56
  import { _toNativeReturnType, _toNativeTypes } from "./types.js";
57
- import { adaptCallbackFunction, scalarResult } from "./conversions.js";
57
+ import { adaptCallbackFunction } from "./callback-conversions.js";
58
+ import { scalarResult } from "./results.js";
58
59
  import { trackCallback } from "./callback-tracker.js";
59
- import { callbackPointer } from "../structures/helpers/common.js";
60
+ import { callbackPointer } from "./parameters.js";
60
61
  import { allocSnapshot } from "../memory/buffer.js";
61
62
 
63
+ function snapshotAllocator(argTypes) {
64
+ // A class constructor can detach or overwrite a pool exposed by an earlier
65
+ // callback. Keep pending C bytes private until all class arguments are initialized.
66
+ return argTypes.some((type) => typeof type === "function" && typeof type._buildStruct === "function") ? undefined : allocSnapshot;
67
+ }
68
+
62
69
  function nativeContextHook(value, name, owners) {
63
70
  if (value !== null && (typeof value === "object" || typeof value === "function")) {
64
71
  if ("_callback" in value) throw new TypeError(`nativeContext.${name} must not execute JavaScript`);
@@ -176,7 +183,7 @@ export function callback(fn, returnType, argTypes = [], native, abi = undefined)
176
183
  const args = [adaptCallbackFunction(fn, argTypes, returnType, native), _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native)];
177
184
  const scalarArgs = argTypes.map(scalarResult);
178
185
  const buffers = scalarArgs.some(Boolean) || args[2].some((type) => typeof type === "object" && type !== null);
179
- if (buffers) args.push(abi ?? "default", scalarArgs, undefined, allocSnapshot);
186
+ if (buffers) args.push(abi ?? "default", scalarArgs, undefined, snapshotAllocator(argTypes));
180
187
  else if (abi) args.push(abi);
181
188
  const cb = new native.Callback(...args);
182
189
 
@@ -203,6 +210,63 @@ export function callback(fn, returnType, argTypes = [], native, abi = undefined)
203
210
  return trackCallback(wrapper, fn, "callback");
204
211
  }
205
212
 
213
+ // Only a prototype constructed from JS owns a trampoline. Its release guard
214
+ // covers argument conversion, the native call and result hooks, not just C execution.
215
+ export function guardCallbackCalls(callback, call, asyncCall, onExecutor) {
216
+ let released = false;
217
+ let activeCalls = 0;
218
+ const assertLive = () => {
219
+ if (released) throw new Error("Callback has been released");
220
+ };
221
+ const release = () => {
222
+ if (activeCalls !== 0) throw new Error("Cannot release callback while calls to it are in progress");
223
+ if (!released) {
224
+ callback.release();
225
+ released = true;
226
+ }
227
+ };
228
+ const leave = () => {
229
+ activeCalls--;
230
+ };
231
+ function pending(invoke, args) {
232
+ assertLive();
233
+ activeCalls++;
234
+ try {
235
+ return invoke(...args).finally(leave);
236
+ } catch (error) {
237
+ // Argument conversion can throw before a Promise exists.
238
+ leave();
239
+ throw error;
240
+ }
241
+ }
242
+ const properties = Object.getOwnPropertyDescriptors(callback);
243
+ properties.release.value = properties[Symbol.dispose].value = release;
244
+ properties._as_parameter_ = {
245
+ get() {
246
+ assertLive();
247
+ return callback.pointer;
248
+ },
249
+ };
250
+ return {
251
+ properties,
252
+ call: function (...args) {
253
+ assertLive();
254
+ activeCalls++;
255
+ try {
256
+ return call(...args);
257
+ } finally {
258
+ leave();
259
+ }
260
+ },
261
+ callAsync: function (...args) {
262
+ return pending(asyncCall, args);
263
+ },
264
+ callOnExecutor: function (target, args) {
265
+ return pending(onExecutor, [target, args]);
266
+ },
267
+ };
268
+ }
269
+
206
270
  /**
207
271
  * Creates a thread-safe C-callable callback from a JavaScript function.
208
272
  *
@@ -324,7 +388,7 @@ export function threadSafeCallback(fn, returnType, argTypes = [], native, option
324
388
  const args = [dispatch, _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native)];
325
389
  const scalarArgs = argTypes.map(scalarResult);
326
390
  const buffers = scalarArgs.some(Boolean) || args[2].some((type) => typeof type === "object" && type !== null);
327
- if (buffers) args.push(abi ?? "default", scalarArgs, context, allocSnapshot);
391
+ if (buffers) args.push(abi ?? "default", scalarArgs, context, snapshotAllocator(argTypes));
328
392
  else if (context !== undefined) args.push(abi ?? "default", scalarArgs, context);
329
393
  else if (scalarArgs.some(Boolean)) args.push(abi ?? "default", scalarArgs);
330
394
  else if (abi) args.push(abi);