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 +80 -1
- package/README.md +53 -0
- 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/callback.js +57 -7
- package/lib/core/conversions.js +71 -22
- package/lib/index.d.ts +57 -1
- package/lib/memory/buffer.js +24 -0
- package/lib/structures/helpers/common.js +13 -2
- package/lib/structures/helpers/struct.js +33 -2
- package/package.json +1 -1
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.
|
|
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
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/lib/core/callback.js
CHANGED
|
@@ -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:
|
|
168
|
-
//
|
|
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,
|
|
280
|
-
const
|
|
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 (
|
|
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:
|
|
307
|
-
//
|
|
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
|
}
|
package/lib/core/conversions.js
CHANGED
|
@@ -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 ||
|
|
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 ||
|
|
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 ||
|
|
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 ||
|
|
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 ||
|
|
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 ||
|
|
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
|
-
|
|
100
|
-
|
|
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
|
-
|
|
108
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
569
|
-
|
|
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
|
|
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
|
|
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 []>(
|
|
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.
|
package/lib/memory/buffer.js
CHANGED
|
@@ -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
|
-
|
|
32
|
+
activeOwnerStack.push(retained);
|
|
22
33
|
try {
|
|
23
34
|
return resolveParameter(parameter, retained);
|
|
24
35
|
} finally {
|
|
25
|
-
|
|
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 {
|
|
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
|
-
|
|
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);
|