node-ctypes 2.5.0 → 2.7.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 CHANGED
@@ -7,6 +7,83 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.7.0] - 2026-11-03
11
+
12
+ ### Changed
13
+
14
+ - **Callback dispatch**: `callback()` and `threadSafeCallback()` invoke the
15
+ JavaScript handler directly, like CPython's `tp_call`. Own `call` or `apply`
16
+ properties on the handler are no longer consulted. The receiver stays
17
+ `undefined` and the handler gets exactly the declared arguments.
18
+ - **Callback wrappers as arguments**: a `callback()` / `threadSafeCallback()`
19
+ wrapper passes its own code pointer even through an object derived with
20
+ `Object.create()` or a Proxy that redefines `_as_parameter_`. This matches
21
+ CPython and `CFUNCTYPE` instances.
22
+
23
+ ### Performance
24
+
25
+ - **Native entry point**: `FFIFunction` calls use a raw Node-API callback that
26
+ reads up to eight arguments with one `napi_get_cb_info` and tries the simple
27
+ call path before building a `Napi::CallbackInfo`.
28
+ - **Structures by value**: plain-object arguments of scalar-only `struct()`
29
+ definitions are written by precompiled field writers into an off-heap
30
+ transient buffer. Structures up to 16 bytes use the simple call path. Scalar-only
31
+ results are read in place without a copy, unless `toObject` is overridden.
32
+ Measured `{x,y}` argument: about 1.3x Koffi, down from 4.3x. Return: about 0.9x,
33
+ down from 1.3x.
34
+ - **Argument owners**: synchronous calls keep conversion owners on a LIFO stack
35
+ instead of a `Set`. Calls with one to three owner-bearing arguments skip
36
+ intermediate arrays.
37
+ - **Callbacks**: wrappers are resolved through an internal brand. Handlers with
38
+ up to three arguments are called without a rest array. Numeric results are
39
+ converted with a single V8 read.
40
+ - **Variadic numbers**: classified and written to the argument slot with a
41
+ single read.
42
+
43
+ ## [2.6.0] - 2026-10-30
44
+
45
+ ### Added
46
+
47
+ - **Native callback contexts**: opt into `suspend`, `resume` and `onError`
48
+ hooks through the fourth `threadSafeCallback()` argument. Foreign callers
49
+ detach their native state before waiting and restore it on the original
50
+ thread before consuming an opaque error supplied with `setNativeError()`.
51
+ Error payloads are isolated per invocation, including concurrent and nested
52
+ calls.
53
+ - **Cooperative callback dispatch**: optional native `notify` hooks can wake
54
+ the consumer's host runtime; `drain()` processes a snapshot of pending calls
55
+ on the owning Node thread. Atomic claiming prevents duplicate execution
56
+ between drains and TSFN delivery, and late deliveries do not access completed
57
+ calls' native arguments. These primitives do not pump a blocked event loop
58
+ automatically.
59
+ - **Electron + React example**: a real native system clock and process-ID check
60
+ in `examples/cross-platform/electron-app`, with node-ctypes confined to the main process,
61
+ typed sandboxed IPC and no renderer Node polyfill. Native `malloc`/clock/view/
62
+ `free` reads exercise automatic synchronized mirrors when Electron disables
63
+ external buffers. Local dependency packaging keeps the addon outside ASAR;
64
+ real macOS ARM64 development and standalone packaged-app checks passed without
65
+ an Electron-specific addon rebuild.
66
+
67
+ ### Changed
68
+
69
+ - **Explicit native hook functions**: accept ctypes native function objects,
70
+ low-level function handles and raw BigInt addresses. Resolve hook addresses
71
+ once and retain supplied function objects through release and queued delivery
72
+ cleanup. Plain JavaScript functions and known JavaScript-backed callback
73
+ wrappers are rejected; native hooks bypass JavaScript converters and
74
+ `errcheck`. Explicit library closure remains the consumer's responsibility.
75
+ - **Callback lifecycle**: represent validated native contexts with C++20
76
+ `std::optional` and restore caller state through a noncopyable, nonmovable
77
+ RAII scope, including a saved state equal to `nullptr`. Reject explicit
78
+ release while a native-context invocation is active.
79
+ - **Public types and documentation**: expose the native-context options,
80
+ error-transfer and drain methods, and native address metadata on library
81
+ attribute functions. Document ownership, thread constraints and dispatch
82
+ flows, with regressions for concurrency, reentry, GC and null-state
83
+ restoration. Existing ABI-string options and callbacks without native
84
+ contexts retain their behavior; the new hooks require a matching rebuilt
85
+ addon, not only updated JavaScript wrappers.
86
+
10
87
  ## [2.5.0] - 2026-10-26
11
88
 
12
89
  ### Fixed
@@ -974,7 +1051,9 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
974
1051
 
975
1052
  Initial releases.
976
1053
 
977
- [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.5.0...HEAD
1054
+ [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.7.0...HEAD
1055
+ [2.7.0]: https://github.com/dmazzella/node-ctypes/compare/v2.6.0...v2.7.0
1056
+ [2.6.0]: https://github.com/dmazzella/node-ctypes/compare/v2.5.0...v2.6.0
978
1057
  [2.5.0]: https://github.com/dmazzella/node-ctypes/compare/v2.4.0...v2.5.0
979
1058
  [2.4.0]: https://github.com/dmazzella/node-ctypes/compare/v2.3.0...v2.4.0
980
1059
  [2.3.0]: https://github.com/dmazzella/node-ctypes/compare/v2.2.0...v2.3.0
package/README.md CHANGED
@@ -329,6 +329,57 @@ const onEvent = threadSafeCallback((code) => console.log("event", code), null, [
329
329
  startWorker(onEvent); // a native library calling onEvent from its own thread
330
330
  ```
331
331
 
332
+ For an embedding runtime that must detach its native thread state before waiting,
333
+ the optional fourth argument can be `{ abi, nativeContext: { suspend, resume, onError, notify? } }`
334
+ instead of the existing ABI string. Each hook accepts a ctypes native function,
335
+ a low-level function handle, or a nonzero BigInt function address:
336
+
337
+ ```javascript
338
+ const onRequest = threadSafeCallback(handleRequest, c_int, [c_int], {
339
+ nativeContext: {
340
+ suspend: runtime.func("save_context", c_void_p, []),
341
+ resume: runtime.func("restore_context", null, [c_void_p]),
342
+ onError: runtime.func("install_error", null, [c_void_p]),
343
+ notify: runtime.func("wake_host", null, []),
344
+ },
345
+ });
346
+ ```
347
+
348
+ Function objects resolve through `_as_parameter_` or `address` once, when the
349
+ callback is constructed. The hooks are called directly using the default C ABI;
350
+ the function wrapper's JS converters and `errcheck` are not invoked:
351
+
352
+ - `void *suspend(void)` runs on a foreign caller before queueing.
353
+ - `void resume(void *)` restores that caller's saved state after dispatch, including
354
+ queue failure or environment shutdown. Neither hook runs on the Node host fast path.
355
+ - `void onError(void *)` consumes an opaque error pointer on the original caller
356
+ thread, after restoration. During the JS callback, use
357
+ `callback.setNativeError(pointer)` once and return the native API's required error
358
+ sentinel (`NULL`, `-1`, etc.). Error payloads belong to each invocation, including
359
+ concurrent and nested calls; JS exceptions are still reported as documented above.
360
+ - Optional `void notify(void)` runs on the foreign caller after successful queueing,
361
+ while its native state is detached. It may wake the host through the consumer's
362
+ runtime, but must not execute JavaScript itself.
363
+
364
+ `callback.drain()` executes a snapshot of pending calls **on the owning Node
365
+ thread**, returning the number it claimed. Each call executes at most once,
366
+ whether the TSFN or a drain gets there first. Delayed TSFN deliveries retain
367
+ only the shared request state and do not touch completed calls' native arguments.
368
+ The consumer must provide a safe way to reenter the host and call `drain()`;
369
+ calling it before entering a blocking native wait is not sufficient.
370
+
371
+ Hooks must not throw or execute JavaScript. Plain JS functions and known
372
+ JS-backed callback wrappers are rejected; an address cannot prove a function's
373
+ signature, validity or implementation. Supplied function objects are retained by
374
+ the native dispatcher through release and queued delivery cleanup. This does not
375
+ prevent explicitly closing their libraries or releasing their underlying resources;
376
+ raw addresses carry no owner. Keep the callback and the hook libraries
377
+ alive until all native calls have returned; explicit release is rejected while a
378
+ native-context call is active. These hooks do not acquire the host runtime context,
379
+ pump a blocked host event loop automatically, or implement interpreter ownership/subinterpreters.
380
+ The host JS handler must acquire/release its own runtime context around native API
381
+ operations. The ordinary callback path is unchanged when no hooks are supplied.
382
+
332
383
  Both callback implementations store narrow integer results in a complete
333
384
  libffi `ffi_arg`, with the declared signedness; failures zero that complete
334
385
  slot. Floating-point results retain their own storage width. The native
@@ -842,8 +893,10 @@ needs these changes:
842
893
 
843
894
  Each example in `examples/` has its own README; see the [index](examples/README.md).
844
895
 
896
+ - [Electron + React](examples/cross-platform/electron-app/README.md) — a native system clock through a sandboxed preload bridge, synchronized C-memory views and a packaged ASAR application
845
897
  - [Embedded Python](examples/cross-platform/python/README.md) — CPython through its C API: code, modules, callbacks, JavaScript objects by reference, shared memory, threads, asyncio and cancellation (Windows, macOS, Linux)
846
898
  - [Smart card (PC/SC)](examples/cross-platform/smartcard/README.md) — `winscard` on Windows, `PCSC.framework` on macOS, `libpcsclite` on Linux
899
+ - [Cryptoki (PKCS #11)](examples/cross-platform/cryptoki/README.md) — complete 3.2 declarations with 2.20–3.2 dispatch and a standalone SoftHSM demo: temporary token, login, RSA, ECDSA, AES and SHA-256
847
900
  - [Accessibility](examples/macos/accessibility/README.md) — macOS UI automation with the Accessibility API
848
901
  - [COM automation](examples/windows/com/README.md) — shell shortcuts (`IShellLinkW`) and Active Directory (`IDirectorySearch`)
849
902
  - [Controls](examples/windows/controls/README.md) — Win32 common controls
Binary file
Binary file
@@ -56,6 +56,32 @@
56
56
  import { _toNativeReturnType, _toNativeTypes } from "./types.js";
57
57
  import { adaptCallbackFunction, scalarResult } from "./conversions.js";
58
58
  import { trackCallback } from "./callback-tracker.js";
59
+ import { callbackPointer } from "../structures/helpers/common.js";
60
+
61
+ function nativeContextHook(value, name, owners) {
62
+ if (value !== null && (typeof value === "object" || typeof value === "function")) {
63
+ if ("_callback" in value) throw new TypeError(`nativeContext.${name} must not execute JavaScript`);
64
+ const parameter = value._as_parameter_;
65
+ const address = parameter === undefined ? value.address : parameter;
66
+ if (typeof address !== "bigint") throw new TypeError(`nativeContext.${name} must be a native function or BigInt address`);
67
+ owners.push(value);
68
+ return address;
69
+ }
70
+ if (typeof value !== "bigint") throw new TypeError(`nativeContext.${name} must be a native function or BigInt address`);
71
+ return value;
72
+ }
73
+
74
+ function nativeContextAddresses(context, owners) {
75
+ if (context === null || typeof context !== "object") throw new TypeError("nativeContext must contain suspend, resume and onError hooks");
76
+ const addresses = {
77
+ suspend: nativeContextHook(context.suspend, "suspend", owners),
78
+ resume: nativeContextHook(context.resume, "resume", owners),
79
+ onError: nativeContextHook(context.onError, "onError", owners),
80
+ };
81
+ const notify = context.notify;
82
+ if (notify !== undefined) addresses.notify = nativeContextHook(notify, "notify", owners);
83
+ return addresses;
84
+ }
59
85
 
60
86
  /**
61
87
  * Creates a C-callable callback from a JavaScript function (main-thread only).
@@ -164,13 +190,14 @@ export function callback(fn, returnType, argTypes = [], native, abi = undefined)
164
190
  },
165
191
  _callback: cb,
166
192
  };
167
- // Python ctypes parity: il callback si passa direttamente come argomento,
168
- // es. qsort(arr, n, size, cmp). Non enumerabile per non cambiare Object.keys.
193
+ // Python ctypes parity: pass the callback directly as an argument,
194
+ // e.g. qsort(arr, n, size, cmp). Non-enumerable to preserve Object.keys.
169
195
  Object.defineProperty(wrapper, "_as_parameter_", {
170
196
  get() {
171
197
  return cb.pointer;
172
198
  },
173
199
  });
200
+ Object.defineProperty(wrapper, callbackPointer, { value: cb.pointer });
174
201
  return trackCallback(wrapper, fn, "callback");
175
202
  }
176
203
 
@@ -276,10 +303,26 @@ export function callback(fn, returnType, argTypes = [], native, abi = undefined)
276
303
  * @throws {Error} If callback creation fails or type conversion fails
277
304
  * @see {@link callback} for main-thread-only callbacks
278
305
  */
279
- export function threadSafeCallback(fn, returnType, argTypes = [], native, abi = undefined) {
280
- const args = [adaptCallbackFunction(fn, argTypes, returnType, native), _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native)];
306
+ export function threadSafeCallback(fn, returnType, argTypes = [], native, options = undefined) {
307
+ const { abi, nativeContext } = typeof options === "object" && options !== null ? options : { abi: options };
308
+ const owners = [];
309
+ const context = nativeContext === undefined ? undefined : nativeContextAddresses(nativeContext, owners);
310
+ const adapted = adaptCallbackFunction(fn, argTypes, returnType, native);
311
+ // Both the native callback and TSFN pin this function through queued delivery.
312
+ const dispatch =
313
+ owners.length === 0
314
+ ? adapted
315
+ : Object.defineProperty(
316
+ function (...args) {
317
+ return Reflect.apply(adapted, this, args);
318
+ },
319
+ "_objects",
320
+ { value: owners },
321
+ );
322
+ const args = [dispatch, _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native)];
281
323
  const scalarArgs = argTypes.map(scalarResult);
282
- if (scalarArgs.some(Boolean)) args.push(abi ?? "default", scalarArgs);
324
+ if (context !== undefined) args.push(abi ?? "default", scalarArgs, context);
325
+ else if (scalarArgs.some(Boolean)) args.push(abi ?? "default", scalarArgs);
283
326
  else if (abi) args.push(abi);
284
327
  const cb = new native.ThreadSafeCallback(...args);
285
328
 
@@ -298,17 +341,24 @@ export function threadSafeCallback(fn, returnType, argTypes = [], native, abi =
298
341
  cb.unref();
299
342
  return wrapper;
300
343
  },
344
+ setNativeError(error) {
345
+ cb.setNativeError(error);
346
+ },
347
+ drain() {
348
+ return cb.drain();
349
+ },
301
350
  [Symbol.dispose]() {
302
351
  cb.release();
303
352
  },
304
353
  _callback: cb,
305
354
  };
306
- // Python ctypes parity: il callback si passa direttamente come argomento,
307
- // es. qsort(arr, n, size, cmp). Non enumerabile per non cambiare Object.keys.
355
+ // Python ctypes parity: pass the callback directly as an argument,
356
+ // e.g. qsort(arr, n, size, cmp). Non-enumerable to preserve Object.keys.
308
357
  Object.defineProperty(wrapper, "_as_parameter_", {
309
358
  get() {
310
359
  return cb.pointer;
311
360
  },
312
361
  });
362
+ Object.defineProperty(wrapper, callbackPointer, { value: cb.pointer });
313
363
  return trackCallback(wrapper, fn, "threadSafeCallback");
314
364
  }
@@ -10,9 +10,11 @@ import { mirrorAddress, mirrorsActive, refresh } from "../memory/mirror.js";
10
10
  import { ArgumentError } from "../platform/errors.js";
11
11
  import { encodeWide } from "../memory/buffer.js";
12
12
  import { buildWrapper } from "../structures/helpers/wrap.js";
13
- import { activeArgumentOwners as argumentOwnerRegistry, byrefOwners, isScalarSubclass, resolveParameter, scalarView, structArgumentFactories } from "../structures/helpers/common.js";
13
+ import { activeArgumentOwners as argumentOwnerRegistry, activeOwnerStack, byrefOwners, isScalarSubclass, resolveParameter, scalarView, structArgumentFactories, structResultReaders } from "../structures/helpers/common.js";
14
14
 
15
15
  const activeArgumentOwners = argumentOwnerRegistry;
16
+ // Captured at load so callback dispatch is not affected by later patches.
17
+ const reflectApply = Reflect.apply;
16
18
 
17
19
  function retainArgument(owners, value) {
18
20
  if (owners !== undefined && value !== null && (typeof value === "object" || typeof value === "function")) owners.push(value);
@@ -34,7 +36,9 @@ export function argumentsNeedOwners(args) {
34
36
  // The general fallback receives the hook snapshot taken before any owner probe.
35
37
  export function specializeCall(ffiFunc, method, converters, state, invoke, captureHere = true) {
36
38
  const [C0, C1, C2, C3, C4, C5] = converters;
39
+ const [N0, N1, N2, N3, N4, N5] = converters.map((convert) => convert.needsOwners ?? needsArgumentOwners);
37
40
  const hasAdapters = converters.some((convert) => convert.requiresOwners);
41
+ const sync = method !== "callAsync";
38
42
  switch (converters.length) {
39
43
  case 0:
40
44
  return function () {
@@ -46,43 +50,42 @@ export function specializeCall(ffiFunc, method, converters, state, invoke, captu
46
50
  return function (a0) {
47
51
  const checked = captureHere ? state.errcheck : null;
48
52
  if (checked !== null || arguments.length !== 1) return invoke(arguments, checked);
49
- if (captureHere && (hasAdapters || needsArgumentOwners(a0))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
53
+ if (captureHere && (hasAdapters || N0(a0))) return sync ? callOwned1(ffiFunc, method, C0, a0) : callWithArgumentOwners(ffiFunc, method, arguments, converters);
50
54
  return ffiFunc[method](C0(a0));
51
55
  };
52
56
  case 2:
53
57
  return function (a0, a1) {
54
58
  const checked = captureHere ? state.errcheck : null;
55
59
  if (checked !== null || arguments.length !== 2) return invoke(arguments, checked);
56
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
60
+ if (captureHere && (hasAdapters || N0(a0) || N1(a1))) return sync ? callOwned2(ffiFunc, method, C0, C1, a0, a1) : callWithArgumentOwners(ffiFunc, method, arguments, converters);
57
61
  return ffiFunc[method](C0(a0), C1(a1));
58
62
  };
59
63
  case 3:
60
64
  return function (a0, a1, a2) {
61
65
  const checked = captureHere ? state.errcheck : null;
62
66
  if (checked !== null || arguments.length !== 3) return invoke(arguments, checked);
63
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
67
+ if (captureHere && (hasAdapters || N0(a0) || N1(a1) || N2(a2))) return sync ? callOwned3(ffiFunc, method, C0, C1, C2, a0, a1, a2) : callWithArgumentOwners(ffiFunc, method, arguments, converters);
64
68
  return ffiFunc[method](C0(a0), C1(a1), C2(a2));
65
69
  };
66
70
  case 4:
67
71
  return function (a0, a1, a2, a3) {
68
72
  const checked = captureHere ? state.errcheck : null;
69
73
  if (checked !== null || arguments.length !== 4) return invoke(arguments, checked);
70
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2) || needsArgumentOwners(a3))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
74
+ if (captureHere && (hasAdapters || N0(a0) || N1(a1) || N2(a2) || N3(a3))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
71
75
  return ffiFunc[method](C0(a0), C1(a1), C2(a2), C3(a3));
72
76
  };
73
77
  case 5:
74
78
  return function (a0, a1, a2, a3, a4) {
75
79
  const checked = captureHere ? state.errcheck : null;
76
80
  if (checked !== null || arguments.length !== 5) return invoke(arguments, checked);
77
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2) || needsArgumentOwners(a3) || needsArgumentOwners(a4))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
81
+ if (captureHere && (hasAdapters || N0(a0) || N1(a1) || N2(a2) || N3(a3) || N4(a4))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
78
82
  return ffiFunc[method](C0(a0), C1(a1), C2(a2), C3(a3), C4(a4));
79
83
  };
80
84
  case 6:
81
85
  return function (a0, a1, a2, a3, a4, a5) {
82
86
  const checked = captureHere ? state.errcheck : null;
83
87
  if (checked !== null || arguments.length !== 6) return invoke(arguments, checked);
84
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2) || needsArgumentOwners(a3) || needsArgumentOwners(a4) || needsArgumentOwners(a5)))
85
- return callWithArgumentOwners(ffiFunc, method, arguments, converters);
88
+ if (captureHere && (hasAdapters || N0(a0) || N1(a1) || N2(a2) || N3(a3) || N4(a4) || N5(a5))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
86
89
  return ffiFunc[method](C0(a0), C1(a1), C2(a2), C3(a3), C4(a4), C5(a5));
87
90
  };
88
91
  default:
@@ -93,24 +96,55 @@ export function specializeCall(ffiFunc, method, converters, state, invoke, captu
93
96
  }
94
97
  }
95
98
 
99
+ // Synchronous owned calls nest strictly: the owners array is a stack entry
100
+ // and the converters run without an intermediate argument array.
101
+ function callOwned1(ffiFunc, method, C0, a0) {
102
+ const owners = [];
103
+ activeOwnerStack.push(owners);
104
+ try {
105
+ return ffiFunc[method](C0(a0, owners));
106
+ } finally {
107
+ activeOwnerStack.pop();
108
+ }
109
+ }
110
+
111
+ function callOwned2(ffiFunc, method, C0, C1, a0, a1) {
112
+ const owners = [];
113
+ activeOwnerStack.push(owners);
114
+ try {
115
+ return ffiFunc[method](C0(a0, owners), C1(a1, owners));
116
+ } finally {
117
+ activeOwnerStack.pop();
118
+ }
119
+ }
120
+
121
+ function callOwned3(ffiFunc, method, C0, C1, C2, a0, a1, a2) {
122
+ const owners = [];
123
+ activeOwnerStack.push(owners);
124
+ try {
125
+ return ffiFunc[method](C0(a0, owners), C1(a1, owners), C2(a2, owners));
126
+ } finally {
127
+ activeOwnerStack.pop();
128
+ }
129
+ }
130
+
96
131
  // The registry is a GC root, including while another converter reenters JS.
97
132
  export function callWithArgumentOwners(ffiFunc, method, args, converters, finish, resultHandler, checkedCall) {
98
133
  const owners = [];
99
- activeArgumentOwners.add(owners);
100
- let pending = false;
134
+ // Synchronous calls nest strictly, so a stack avoids hashing a fresh array.
135
+ activeOwnerStack.push(owners);
101
136
  try {
102
137
  const converted = convertArguments(args, converters, owners);
103
138
  const result =
104
139
  resultHandler === undefined ? ffiFunc[method](...converted) : checkedCall === undefined ? ffiFunc[method === "callAsync" ? "_callAsyncWithErrcheck" : "_callWithErrcheck"](resultHandler, ...converted) : checkedCall(resultHandler, ...converted);
105
140
  if (method === "callAsync") {
106
141
  const completed = finish === undefined ? result : result.then((value) => finish(value, args));
107
- const promise = completed.finally(() => activeArgumentOwners.delete(owners));
108
- pending = true;
109
- return promise;
142
+ activeArgumentOwners.add(owners);
143
+ return completed.finally(() => activeArgumentOwners.delete(owners));
110
144
  }
111
145
  return finish === undefined ? result : finish(result, args);
112
146
  } finally {
113
- if (!pending) activeArgumentOwners.delete(owners);
147
+ activeOwnerStack.pop();
114
148
  }
115
149
  }
116
150
 
@@ -181,7 +215,7 @@ const isStructType = (t) => t !== null && (typeof t === "function" || typeof t =
181
215
  function structArgument(T, index) {
182
216
  const instance = typeof T === "function" ? (values) => new T(values) : (structArgumentFactories.get(T) ?? ((values) => T.create(values)));
183
217
  const coerce = mirrorsActive ? coerceStructValue : coerceObject;
184
- return (a, owners) => {
218
+ const convert = (a, owners) => {
185
219
  a = resolveArgument(a, owners, index);
186
220
  retainArgument(owners, a);
187
221
  if (Array.isArray(a)) {
@@ -193,6 +227,10 @@ function structArgument(T, index) {
193
227
  }
194
228
  return coerce(a, owners);
195
229
  };
230
+ // A plain object of field values becomes a fresh Buffer passed directly to
231
+ // the call, so nothing else needs to stay reachable.
232
+ convert.needsOwners = (a) => needsArgumentOwners(a) && !(Object.getPrototypeOf(a) === Object.prototype && !("_buffer" in a) && !("_as_parameter_" in a));
233
+ return convert;
196
234
  }
197
235
 
198
236
  /**
@@ -403,7 +441,6 @@ function fromParamArgument(T, base, index, fromParam) {
403
441
  try {
404
442
  converted = Reflect.apply(fromParam, T, [a]);
405
443
  } catch (e) {
406
- if (e instanceof ArgumentError) throw e;
407
444
  throw new ArgumentError(`argument ${index + 1}: ${e?.name ?? "Error"}: ${e?.message ?? String(e)}`, { cause: e });
408
445
  }
409
446
  retainArgument(owners, converted);
@@ -495,7 +532,7 @@ export function resultConverter(restype) {
495
532
  return (r) => new restype(copyResultBytes(r));
496
533
  }
497
534
  if (restype !== null && typeof restype === "object" && restype._isStructType === true) {
498
- return (r) => restype.toObject(copyResultBytes(r));
535
+ return structResultReaders.get(restype) ?? ((r) => restype.toObject(copyResultBytes(r)));
499
536
  }
500
537
  return undefined;
501
538
  }
@@ -565,11 +602,23 @@ export function adaptCallbackFunction(fn, argTypes, returnType, native) {
565
602
  return result !== null && (typeof result === "object" || typeof result === "function") ? coerceValue(result) : result;
566
603
  };
567
604
  if (!hasScalars && !hasVariants && !hasPointers && !hasStructs) {
568
- return function (...args) {
569
- return convertResult(fn.apply(this, args));
570
- };
605
+ // The native trampoline passes exactly argTypes.length values with an
606
+ // undefined receiver. Like CPython (tp_call), the handler is invoked
607
+ // directly: own `call`/`apply` properties are not consulted.
608
+ switch (argTypes.length) {
609
+ case 0:
610
+ return () => convertResult(fn());
611
+ case 1:
612
+ return (a0) => convertResult(fn(a0));
613
+ case 2:
614
+ return (a0, a1) => convertResult(fn(a0, a1));
615
+ case 3:
616
+ return (a0, a1, a2) => convertResult(fn(a0, a1, a2));
617
+ default:
618
+ return (...args) => convertResult(reflectApply(fn, undefined, args));
619
+ }
571
620
  }
572
- return function (...args) {
621
+ return (...args) => {
573
622
  if (hasScalars) {
574
623
  for (let i = 0; i < scalarTypes.length; i++) {
575
624
  if (scalarTypes[i] !== null) args[i] = scalarView(scalarTypes[i], args[i]);
@@ -593,7 +642,7 @@ export function adaptCallbackFunction(fn, argTypes, returnType, native) {
593
642
  if (structViews[i] !== null) args[i] = structViews[i](args[i]);
594
643
  }
595
644
  }
596
- return convertResult(fn.apply(this, args));
645
+ return convertResult(reflectApply(fn, undefined, args));
597
646
  };
598
647
  }
599
648
 
package/lib/index.d.ts CHANGED
@@ -464,6 +464,10 @@ export interface FunctionWrapper {
464
464
  /** Call the function. */
465
465
  (...args: any[]): any;
466
466
 
467
+ /** Resolve the native function address. */
468
+ readonly address: bigint;
469
+ readonly _as_parameter_: bigint;
470
+
467
471
  /** Call the function asynchronously on a worker thread. */
468
472
  callAsync(...args: any[]): Promise<any>;
469
473
 
@@ -636,6 +640,49 @@ export interface ThreadSafeCallbackWrapper extends CallbackWrapper {
636
640
  * callback exists. Calls from other threads are delivered while it runs.
637
641
  */
638
642
  unref(): this;
643
+ /**
644
+ * Transfer a nonzero opaque error pointer to nativeContext.onError on the
645
+ * original caller thread, after resume. Only during this callback; once per
646
+ * invocation. The callback must also return its ABI's error sentinel.
647
+ * Ownership transfers to onError, which must consume the pointer.
648
+ */
649
+ setNativeError(error: bigint): void;
650
+ /** Execute a snapshot of queued calls on the owning Node thread; return the number claimed. */
651
+ drain(): number;
652
+ }
653
+
654
+ /**
655
+ * A raw function address, ctypes callable or low-level native function handle.
656
+ * JavaScript-backed callbacks are not valid hooks. Object targets are retained
657
+ * by the native dispatcher until release and queued delivery cleanup.
658
+ * @category Callbacks
659
+ */
660
+ export type NativeCallbackHook = bigint | (({ readonly _as_parameter_: bigint } | { readonly address: bigint }) & { readonly _callback?: never });
661
+
662
+ /**
663
+ * Opt-in native runtime hooks. Addresses are resolved once at construction.
664
+ * Keep the callback and hook libraries alive until every invocation returns;
665
+ * retaining a function does not prevent explicit close()/release().
666
+ * Hooks use the default C ABI directly, bypassing JS argument conversion and
667
+ * errcheck. They must not throw or execute JavaScript and do not provide
668
+ * subinterpreter support.
669
+ * @category Callbacks
670
+ */
671
+ export interface NativeCallbackContext {
672
+ /** `void *suspend(void)`: detach caller state before a foreign thread waits. */
673
+ suspend: NativeCallbackHook;
674
+ /** `void resume(void *)`: restore that state on the same thread, even on dispatch failure. */
675
+ resume: NativeCallbackHook;
676
+ /** `void onError(void *)`: consume setNativeError's pointer on the original thread. */
677
+ onError: NativeCallbackHook;
678
+ /** `void notify(void)`: after queueing on a foreign thread, while suspended; may wake the host, never run JS. */
679
+ notify?: NativeCallbackHook;
680
+ }
681
+
682
+ /** @category Callbacks */
683
+ export interface ThreadSafeCallbackOptions {
684
+ abi?: FunctionOptions["abi"];
685
+ nativeContext?: NativeCallbackContext;
639
686
  }
640
687
 
641
688
  /**
@@ -677,6 +724,10 @@ export class ThreadSafeCallback extends Callback {
677
724
  ref(): this;
678
725
  /** Do not keep the Node.js event loop alive. */
679
726
  unref(): this;
727
+ /** See {@link ThreadSafeCallbackWrapper.setNativeError}. */
728
+ setNativeError(error: bigint): void;
729
+ /** See {@link ThreadSafeCallbackWrapper.drain}. */
730
+ drain(): number;
680
731
  }
681
732
 
682
733
  // =============================================================================
@@ -1593,7 +1644,12 @@ export function callback<TRet extends CallbackRestype, const TArgs extends reado
1593
1644
  *
1594
1645
  * @category Callbacks
1595
1646
  */
1596
- export function threadSafeCallback<TRet extends CallbackRestype, const TArgs extends readonly FFIType[] = readonly []>(fn: (...args: CallbackArgs<TArgs>) => CallbackResult<TRet>, returnType: TRet, argTypes?: TArgs): ThreadSafeCallbackWrapper;
1647
+ export function threadSafeCallback<TRet extends CallbackRestype, const TArgs extends readonly FFIType[] = readonly []>(
1648
+ fn: (...args: CallbackArgs<TArgs>) => CallbackResult<TRet>,
1649
+ returnType: TRet,
1650
+ argTypes?: TArgs,
1651
+ options?: FunctionOptions["abi"] | ThreadSafeCallbackOptions,
1652
+ ): ThreadSafeCallbackWrapper;
1597
1653
 
1598
1654
  /**
1599
1655
  * Create a function pointer type with cdecl calling convention.
@@ -70,6 +70,30 @@ export function alloc(size) {
70
70
  return Buffer.alloc(size);
71
71
  }
72
72
 
73
+ const kTransientPoolSize = 8192;
74
+ let transientPool = new ArrayBuffer(kTransientPoolSize);
75
+ let transientOffset = 0;
76
+
77
+ /**
78
+ * Zero-filled buffer for a value that only lives for one native call. A small
79
+ * Buffer.alloc lives on the V8 heap and must be externalized when native code
80
+ * reads it; slices of an off-heap pool avoid that. Slices are never reused, so
81
+ * a fresh pool is already zeroed.
82
+ *
83
+ * @param {number} size - Size in bytes to allocate
84
+ * @returns {Buffer} Zero-initialized buffer
85
+ */
86
+ export function allocTransient(size) {
87
+ if (size > kTransientPoolSize >>> 2) return Buffer.alloc(size);
88
+ if (transientOffset + size > kTransientPoolSize) {
89
+ transientPool = new ArrayBuffer(kTransientPoolSize);
90
+ transientOffset = 0;
91
+ }
92
+ const buf = Buffer.from(transientPool, transientOffset, size);
93
+ transientOffset += (size + 7) & ~7;
94
+ return buf;
95
+ }
96
+
73
97
  /**
74
98
  * Creates a buffer containing a null-terminated C string.
75
99
  *
@@ -3,11 +3,22 @@ import { POINTER_SIZE } from "../../platform/constants.js";
3
3
 
4
4
  const simpleTypes = new WeakSet();
5
5
  export const activeArgumentOwners = new Set();
6
+ // GC roots of in-progress synchronous conversions, released in LIFO order.
7
+ export const activeOwnerStack = [];
6
8
  export const byrefOwners = new WeakMap();
7
9
  export const structArgumentFactories = new WeakMap();
10
+ export const structResultReaders = new WeakMap();
11
+ // Brand of callback wrappers: their constant pointer (the `_as_parameter_`
12
+ // value), read without the generic parameter probes.
13
+ export const callbackPointer = Symbol("callbackPointer");
8
14
 
9
15
  export function resolveParameter(value, owners) {
10
16
  if (value === null || (typeof value !== "object" && typeof value !== "function")) return value;
17
+ const pointer = value[callbackPointer];
18
+ if (pointer !== undefined) {
19
+ if (owners !== undefined) owners.push(value);
20
+ return pointer;
21
+ }
11
22
  if (owners !== undefined) owners.push(value);
12
23
  if (ArrayBuffer.isView(value) && !("_as_parameter_" in value)) return value;
13
24
  if (value._isSimpleCDataInstance === true || value._pointerType !== undefined || value._arrayType !== undefined || value._structDef !== undefined || byrefOwners.has(value)) return value;
@@ -18,11 +29,11 @@ export function resolveParameter(value, owners) {
18
29
 
19
30
  // Resolver-only memory operations also retain parents while nested getters can collect.
20
31
  const retained = [value];
21
- activeArgumentOwners.add(retained);
32
+ activeOwnerStack.push(retained);
22
33
  try {
23
34
  return resolveParameter(parameter, retained);
24
35
  } finally {
25
- activeArgumentOwners.delete(retained);
36
+ activeOwnerStack.pop();
26
37
  }
27
38
  }
28
39
 
@@ -37,7 +37,8 @@ import { bitFieldAccessors } from "./bitfield.js";
37
37
  import { computeLayout, isGccLayout, normalizePack } from "./layout.js";
38
38
  import { buildWrapper } from "./wrap.js";
39
39
  import { isMirror, syncDefinition } from "../../memory/mirror.js";
40
- import { copyInstance, fieldEntries, fieldsOf, funcPtrFieldType, isScalarSubclass, pointerOwner, scalarReader, simpleFieldWriter, structArgumentFactories, writePointerField } from "./common.js";
40
+ import { allocTransient } from "../../memory/buffer.js";
41
+ import { copyInstance, fieldEntries, fieldsOf, funcPtrFieldType, isScalarSubclass, pointerOwner, scalarReader, simpleFieldWriter, structArgumentFactories, structResultReaders, writePointerField } from "./common.js";
41
42
 
42
43
  /**
43
44
  * Creates a struct type definition with proper alignment and padding.
@@ -695,11 +696,41 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
695
696
 
696
697
  if (fieldDefs.every((field) => !field.isBitField && !field.isNested && !field.isArray && !field.isPointer && !field.type._isPointerValued && !isScalarSubclass(field.type))) {
697
698
  const create = structDef.create;
699
+ const set = structDef.set;
700
+ // Only scalar fields: `set` would resolve each name to its precompiled writer.
701
+ const writers = fieldDefs.map((field) => [field.name, fieldWriters[field.name]]);
702
+ const createScalar = (values) => {
703
+ const buf = allocTransient(totalSize);
704
+ for (let i = 0; i < writers.length; i++) {
705
+ const [name, write] = writers[i];
706
+ if (!Object.hasOwn(values, name)) continue;
707
+ const value = values[name];
708
+ if (value !== undefined) write(buf, value);
709
+ }
710
+ return buf;
711
+ };
712
+ const createFast = writers.every(([, write]) => typeof write === "function") ? createScalar : createBuffer;
698
713
  structArgumentFactories.set(structDef, (values) => {
699
714
  // A later create override must still run, with the definition as receiver.
700
715
  const current = structDef.create;
701
- return current === create ? createBuffer(values) : current.call(structDef, values);
716
+ if (current !== create) return current.call(structDef, values);
717
+ return structDef.set === set ? createFast(values) : createBuffer(values);
702
718
  });
719
+ const toObject = structDef.toObject;
720
+ const readers = fieldDefs.map((field) => [field.name, fieldReaders[field.name]]);
721
+ if (readers.every(([name, read]) => name !== "__proto__" && typeof read === "function")) {
722
+ // Scalar readers return primitives without reentering, so the native
723
+ // result buffer can be read in place; a toObject override gets a copy.
724
+ structResultReaders.set(structDef, (bytes) => {
725
+ if (structDef.toObject !== toObject) return structDef.toObject(Buffer.from(bytes));
726
+ const result = {};
727
+ for (let i = 0; i < readers.length; i++) {
728
+ const [name, read] = readers[i];
729
+ result[name] = read(bytes);
730
+ }
731
+ return result;
732
+ });
733
+ }
703
734
  }
704
735
 
705
736
  return syncDefinition(structDef);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-ctypes",
3
- "version": "2.5.0",
3
+ "version": "2.7.0",
4
4
  "description": "Python ctypes-like FFI for Node.js using libffi",
5
5
  "author": "Damiano Mazzella",
6
6
  "license": "MIT",