node-ctypes 2.9.0 → 2.11.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 +54 -1
- package/README.md +71 -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/Library.js +7 -0
- package/lib/core/callback.js +3 -3
- package/lib/core/executor.js +63 -0
- package/lib/core/funcptr.js +8 -0
- package/lib/index.d.ts +75 -0
- package/lib/index.js +6 -1
- package/lib/memory/buffer.js +37 -2
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [2.11.0] - 2026-11-10
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **`Executor` and `fn.callOn(executor, ...args)`**: a native thread owned by
|
|
15
|
+
node-ctypes with a FIFO queue. `callOn` is the same call as `callAsync`
|
|
16
|
+
(conversions, out parameters, structures, variadic arguments, `errcheck`,
|
|
17
|
+
argument lifetime), run on that thread instead of a libuv worker: calls run
|
|
18
|
+
one at a time in arrival order and never occupy the libuv pool. Queued calls
|
|
19
|
+
can be cancelled with an `AbortSignal` (`callOn({ executor, signal }, ...)`);
|
|
20
|
+
`close()` waits for the accepted calls and stops the thread. Pending calls
|
|
21
|
+
keep the process alive, an idle executor does not; on process exit or worker
|
|
22
|
+
termination queued calls are discarded and a running call is detached.
|
|
23
|
+
|
|
24
|
+
### Changed
|
|
25
|
+
|
|
26
|
+
- **Asynchronous call internals**: the converted arguments of `callAsync` are
|
|
27
|
+
held by a call object shared with `callOn`; the libuv worker only runs it.
|
|
28
|
+
Behavior is unchanged.
|
|
29
|
+
|
|
30
|
+
### Documentation
|
|
31
|
+
|
|
32
|
+
- **Asynchronous calls**: document `callAsync` on the libuv pool, when to use
|
|
33
|
+
an `Executor`, cancellation, `close()` and the process lifetime.
|
|
34
|
+
|
|
35
|
+
## [2.10.0] - 2026-11-06
|
|
36
|
+
|
|
37
|
+
### Fixed
|
|
38
|
+
|
|
39
|
+
- **Callback exception boundary**: a C++ exception other than a Node-API error
|
|
40
|
+
(for example `std::bad_alloc` while copying an aggregate) raised while
|
|
41
|
+
converting arguments or results, calling the JavaScript function, its error
|
|
42
|
+
handler or the warning fallback is recorded and yields a zero result instead
|
|
43
|
+
of crossing the native callback frame.
|
|
44
|
+
- **Callback snapshot pool isolation**: snapshots of callback arguments no
|
|
45
|
+
longer share their pool with native-call temporaries. Since 2.9.0, detaching
|
|
46
|
+
a snapshot's `ArrayBuffer` broke every later by-value structure argument and
|
|
47
|
+
structure callback, and could let JavaScript read, alter or release memory
|
|
48
|
+
still used by an in-flight native call. A detached pool is now replaced.
|
|
49
|
+
- **Detached buffer arguments**: a Buffer, typed array, DataView or ArrayBuffer
|
|
50
|
+
argument detached while native code could still use it (by a callback during
|
|
51
|
+
a synchronous call, or before a `callAsync()` completes) now makes the call
|
|
52
|
+
throw or reject instead of returning silently. Node-API cannot prevent the
|
|
53
|
+
detach; synchronous calls check only when a JavaScript callback ran.
|
|
54
|
+
|
|
55
|
+
### Documentation
|
|
56
|
+
|
|
57
|
+
- **Callback snapshot pool**: document the dedicated snapshot pool, how
|
|
58
|
+
retention affects memory and why the underlying `ArrayBuffer` should not be
|
|
59
|
+
exposed without copying.
|
|
60
|
+
|
|
10
61
|
## [2.9.0] - 2026-11-05
|
|
11
62
|
|
|
12
63
|
### Added
|
|
@@ -1130,7 +1181,9 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
|
|
|
1130
1181
|
|
|
1131
1182
|
Initial releases.
|
|
1132
1183
|
|
|
1133
|
-
[Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.
|
|
1184
|
+
[Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.11.0...HEAD
|
|
1185
|
+
[2.11.0]: https://github.com/dmazzella/node-ctypes/compare/v2.10.0...v2.11.0
|
|
1186
|
+
[2.10.0]: https://github.com/dmazzella/node-ctypes/compare/v2.9.0...v2.10.0
|
|
1134
1187
|
[2.9.0]: https://github.com/dmazzella/node-ctypes/compare/v2.8.0...v2.9.0
|
|
1135
1188
|
[2.8.0]: https://github.com/dmazzella/node-ctypes/compare/v2.7.0...v2.8.0
|
|
1136
1189
|
[2.7.0]: https://github.com/dmazzella/node-ctypes/compare/v2.6.0...v2.7.0
|
package/README.md
CHANGED
|
@@ -101,6 +101,47 @@ additional arguments bypass fixed invokers and prepare their libffi metadata
|
|
|
101
101
|
on the JavaScript thread. Inferred calls use the ordinary ABI; true variadic
|
|
102
102
|
calls preserve the declared named-prefix boundary.
|
|
103
103
|
|
|
104
|
+
### Asynchronous calls: `callAsync` and `Executor`
|
|
105
|
+
|
|
106
|
+
`fn.callAsync(...args)` runs the call on a libuv worker and returns a promise;
|
|
107
|
+
the event loop stays free meanwhile. Arguments are converted on the
|
|
108
|
+
JavaScript thread before the call, results (and `errcheck`) after it, and the
|
|
109
|
+
memory passed by address stays referenced until the promise settles.
|
|
110
|
+
|
|
111
|
+
libuv workers are shared with `fs`, `dns` and `crypto` (4 by default), and
|
|
112
|
+
concurrent calls run in parallel in any order. For long or blocking calls, or
|
|
113
|
+
calls that must run in sequence on one thread (thread-local state,
|
|
114
|
+
thread-affine handles, libraries that are not thread-safe), use an
|
|
115
|
+
`Executor`: a native thread owned by node-ctypes with a FIFO queue.
|
|
116
|
+
`fn.callOn(executor, ...args)` is the same call as `callAsync`, run there:
|
|
117
|
+
|
|
118
|
+
```javascript
|
|
119
|
+
import { Executor } from "node-ctypes";
|
|
120
|
+
|
|
121
|
+
const executor = new Executor({ name: "device" }); // thread name for debuggers
|
|
122
|
+
const read = await lib.device_read.callOn(executor, handle, buffer, buffer.length);
|
|
123
|
+
|
|
124
|
+
// Cancel a call that has not started yet: the promise rejects with signal.reason.
|
|
125
|
+
const controller = new AbortController();
|
|
126
|
+
const next = lib.device_read.callOn({ executor, signal: controller.signal }, handle, buffer, buffer.length);
|
|
127
|
+
controller.abort();
|
|
128
|
+
|
|
129
|
+
await executor.close(); // waits for the accepted calls, then stops the thread
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
- Calls run one at a time, in arrival order; each promise settles once.
|
|
133
|
+
- The thread starts with the first call. Pending calls keep the process
|
|
134
|
+
alive; an idle executor does not, and is collected with its thread when no
|
|
135
|
+
longer referenced. `close()` rejects new calls, waits for the accepted ones
|
|
136
|
+
and stops the thread (an executor cannot be reopened).
|
|
137
|
+
- `executor.pending`, `completed`, `running` and `closed` report its state.
|
|
138
|
+
- A call that has started cannot be interrupted: the signal only removes
|
|
139
|
+
queued calls.
|
|
140
|
+
- On process exit (or worker termination) queued calls are discarded and a
|
|
141
|
+
running call is left to finish on its own.
|
|
142
|
+
- Callbacks invoked during the call run on the executor thread: use
|
|
143
|
+
`threadSafeCallback`, as with `callAsync`.
|
|
144
|
+
|
|
104
145
|
### Structs, unions, bit fields, arrays
|
|
105
146
|
|
|
106
147
|
```javascript
|
|
@@ -297,6 +338,25 @@ Existing callers retain their result-check snapshot and their own `errcheck`.
|
|
|
297
338
|
An installed `from_param` converter still resolves the method at call time,
|
|
298
339
|
as before.
|
|
299
340
|
|
|
341
|
+
Structure, union and scalar-instance arguments received by `callback()`,
|
|
342
|
+
`CFUNCTYPE` and `threadSafeCallback()` are owned snapshots: each one is a
|
|
343
|
+
distinct slice of an 8 KB off-heap pool reserved for callback snapshots.
|
|
344
|
+
Native-call temporaries use a separate pool that is never exposed, so a
|
|
345
|
+
snapshot cannot reveal or alter memory that native code is still using.
|
|
346
|
+
Slices are never reused, so a retained argument keeps its own bytes and
|
|
347
|
+
identity. Detaching a snapshot's `ArrayBuffer` (`transfer()`, a transfer list)
|
|
348
|
+
only affects the snapshots in that pool; later callbacks use a fresh one.
|
|
349
|
+
|
|
350
|
+
- Retaining any slice keeps its whole 8 KB backing `ArrayBuffer` alive. When
|
|
351
|
+
storing many small arguments for a long time, copy them, for example
|
|
352
|
+
`Buffer.from(value._buffer)` or a new instance built from its fields.
|
|
353
|
+
- `value._buffer.buffer` is the whole pool and can contain other callback
|
|
354
|
+
snapshots. Use `_buffer` itself (or `byteOffset` and `length`), and copy
|
|
355
|
+
before handing the underlying `ArrayBuffer` to untrusted code.
|
|
356
|
+
|
|
357
|
+
Values larger than 2 KB, layouts aligned to more than 8 bytes and raw native
|
|
358
|
+
callbacks keep a dedicated allocation.
|
|
359
|
+
|
|
300
360
|
Both callbacks and libraries implement `Symbol.dispose`, so they work
|
|
301
361
|
with the `using` declaration for scope-bound cleanup (also on `throw`):
|
|
302
362
|
|
|
@@ -593,6 +653,17 @@ still stop at its end; raw native addresses remain the caller's responsibility.
|
|
|
593
653
|
Scalar `from_buffer()` / `from_buffer_copy()` validate byte size and offset
|
|
594
654
|
before producing an instance and accept Buffer, typed views and ctypes memory.
|
|
595
655
|
|
|
656
|
+
Do not detach (`ArrayBuffer.prototype.transfer()`, a `postMessage` /
|
|
657
|
+
`structuredClone` transfer list) memory passed to a call that is still running:
|
|
658
|
+
a pending `callAsync()`, or the outer call while a callback runs. Native code
|
|
659
|
+
keeps its address and may access memory that now belongs to another
|
|
660
|
+
`ArrayBuffer` or has been released. Node-API cannot prevent the detach, so
|
|
661
|
+
node-ctypes reports it instead. A synchronous call during which a JavaScript
|
|
662
|
+
callback ran throws `argument N: memory was detached ...` after native code
|
|
663
|
+
returns, and a `callAsync()` whose Buffer, typed array, DataView or ArrayBuffer
|
|
664
|
+
argument was detached rejects. The check covers those arguments as passed,
|
|
665
|
+
not addresses stored inside structures or obtained with `addressof()`.
|
|
666
|
+
|
|
596
667
|
### Electron
|
|
597
668
|
|
|
598
669
|
Electron does not allow Buffers over memory that V8 did not allocate, so a
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/lib/core/Library.js
CHANGED
|
@@ -42,6 +42,7 @@
|
|
|
42
42
|
import { _toNativeReturnType } from "./types.js";
|
|
43
43
|
import { adaptCallbackFunction, argumentConverters, argumentsNeedOwners, callWithArgumentOwners, callWithResultHandler, convertArguments, resultCheck, resultConverter, scalarResult, specializeCall, structResult } from "./conversions.js";
|
|
44
44
|
import { createTypeKey } from "../utils/cache.js";
|
|
45
|
+
import { callOn } from "./executor.js";
|
|
45
46
|
|
|
46
47
|
/**
|
|
47
48
|
* Creates the Library-related classes with required dependencies injected.
|
|
@@ -143,6 +144,11 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
|
|
|
143
144
|
set: () => {},
|
|
144
145
|
configurable: true,
|
|
145
146
|
},
|
|
147
|
+
callOn: {
|
|
148
|
+
get: () => resolve().callOn,
|
|
149
|
+
set: () => {},
|
|
150
|
+
configurable: true,
|
|
151
|
+
},
|
|
146
152
|
});
|
|
147
153
|
|
|
148
154
|
return func;
|
|
@@ -314,6 +320,7 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
|
|
|
314
320
|
_as_parameter_: { value: ffiFunc.address },
|
|
315
321
|
_ffi: { value: ffiFunc },
|
|
316
322
|
callAsync: { value: asyncCallMethod, writable: false, enumerable: false, configurable: false },
|
|
323
|
+
callOn: { value: (target, ...args) => callOn(callMethod, target, args), writable: false, enumerable: false, configurable: false },
|
|
317
324
|
// Esponi errcheck come setter/getter
|
|
318
325
|
errcheck: {
|
|
319
326
|
get() {
|
package/lib/core/callback.js
CHANGED
|
@@ -57,7 +57,7 @@ import { _toNativeReturnType, _toNativeTypes } from "./types.js";
|
|
|
57
57
|
import { adaptCallbackFunction, scalarResult } from "./conversions.js";
|
|
58
58
|
import { trackCallback } from "./callback-tracker.js";
|
|
59
59
|
import { callbackPointer } from "../structures/helpers/common.js";
|
|
60
|
-
import {
|
|
60
|
+
import { allocSnapshot } from "../memory/buffer.js";
|
|
61
61
|
|
|
62
62
|
function nativeContextHook(value, name, owners) {
|
|
63
63
|
if (value !== null && (typeof value === "object" || typeof value === "function")) {
|
|
@@ -176,7 +176,7 @@ export function callback(fn, returnType, argTypes = [], native, abi = undefined)
|
|
|
176
176
|
const args = [adaptCallbackFunction(fn, argTypes, returnType, native), _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native)];
|
|
177
177
|
const scalarArgs = argTypes.map(scalarResult);
|
|
178
178
|
const buffers = scalarArgs.some(Boolean) || args[2].some((type) => typeof type === "object" && type !== null);
|
|
179
|
-
if (buffers) args.push(abi ?? "default", scalarArgs, undefined,
|
|
179
|
+
if (buffers) args.push(abi ?? "default", scalarArgs, undefined, allocSnapshot);
|
|
180
180
|
else if (abi) args.push(abi);
|
|
181
181
|
const cb = new native.Callback(...args);
|
|
182
182
|
|
|
@@ -324,7 +324,7 @@ export function threadSafeCallback(fn, returnType, argTypes = [], native, option
|
|
|
324
324
|
const args = [dispatch, _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native)];
|
|
325
325
|
const scalarArgs = argTypes.map(scalarResult);
|
|
326
326
|
const buffers = scalarArgs.some(Boolean) || args[2].some((type) => typeof type === "object" && type !== null);
|
|
327
|
-
if (buffers) args.push(abi ?? "default", scalarArgs, context,
|
|
327
|
+
if (buffers) args.push(abi ?? "default", scalarArgs, context, allocSnapshot);
|
|
328
328
|
else if (context !== undefined) args.push(abi ?? "default", scalarArgs, context);
|
|
329
329
|
else if (scalarArgs.some(Boolean)) args.push(abi ?? "default", scalarArgs);
|
|
330
330
|
else if (abi) args.push(abi);
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @file executor.js
|
|
3
|
+
* @module core/executor
|
|
4
|
+
* @description `fn.callOn(executor, ...args)`: the same call as
|
|
5
|
+
* `fn.callAsync(...args)` (conversions, out parameters, errcheck, argument
|
|
6
|
+
* lifetime), run on an {@link Executor} thread instead of a libuv worker.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
let native = null;
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Set the native module (once, from lib/index.js, before any call).
|
|
13
|
+
*
|
|
14
|
+
* @param {Object} nativeModule - Native module
|
|
15
|
+
*/
|
|
16
|
+
export function initExecutor(nativeModule) {
|
|
17
|
+
native = nativeModule;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Run `fn.callAsync(...args)` on `target`: an `Executor`, or
|
|
22
|
+
* `{ executor, signal }` to cancel the call while it is still queued.
|
|
23
|
+
*
|
|
24
|
+
* The native binding takes the executor for exactly one call: the next
|
|
25
|
+
* asynchronous call of `fn`'s native function, made synchronously below.
|
|
26
|
+
*
|
|
27
|
+
* @param {Function} fn - A function with `callAsync` and `_ffi`
|
|
28
|
+
* @param {Object} target - Executor or `{ executor, signal }`
|
|
29
|
+
* @param {Array} args - Call arguments
|
|
30
|
+
* @returns {Promise<*>}
|
|
31
|
+
*/
|
|
32
|
+
export function callOn(fn, target, args) {
|
|
33
|
+
let executor = target;
|
|
34
|
+
let signal;
|
|
35
|
+
if (!(target instanceof native.Executor)) {
|
|
36
|
+
executor = target?.executor;
|
|
37
|
+
signal = target?.signal ?? undefined;
|
|
38
|
+
if (!(executor instanceof native.Executor)) {
|
|
39
|
+
return Promise.reject(new TypeError("callOn requires an Executor or { executor, signal }"));
|
|
40
|
+
}
|
|
41
|
+
if (signal !== undefined && !(signal instanceof AbortSignal)) {
|
|
42
|
+
return Promise.reject(new TypeError("callOn: signal must be an AbortSignal"));
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
if (signal?.aborted) return Promise.reject(signal.reason);
|
|
46
|
+
|
|
47
|
+
const previous = executor._lastJob;
|
|
48
|
+
let promise;
|
|
49
|
+
native.setCallTarget(executor, fn._ffi);
|
|
50
|
+
try {
|
|
51
|
+
promise = fn.callAsync(...args);
|
|
52
|
+
} finally {
|
|
53
|
+
native.setCallTarget(null);
|
|
54
|
+
}
|
|
55
|
+
const job = executor._lastJob;
|
|
56
|
+
if (signal === undefined || job === previous) return promise;
|
|
57
|
+
|
|
58
|
+
// Cancel while queued: the promise rejects with the abort reason; a call
|
|
59
|
+
// that has started completes normally.
|
|
60
|
+
const abort = () => executor._cancel(job, signal.reason);
|
|
61
|
+
signal.addEventListener("abort", abort, { once: true });
|
|
62
|
+
return promise.finally(() => signal.removeEventListener("abort", abort));
|
|
63
|
+
}
|
package/lib/core/funcptr.js
CHANGED
|
@@ -41,6 +41,7 @@ import { argumentConverters, argumentsNeedOwners, callWithArgumentOwners, callWi
|
|
|
41
41
|
import { callback as createCallback } from "./callback.js";
|
|
42
42
|
import { isScalarSubclass, keepFunctionOwner, scalarOutparam } from "../structures/helpers/common.js";
|
|
43
43
|
import { cacheWeakValue, createTypeKey } from "../utils/cache.js";
|
|
44
|
+
import { callOn } from "./executor.js";
|
|
44
45
|
|
|
45
46
|
const prototypeOwners = new WeakMap();
|
|
46
47
|
|
|
@@ -171,6 +172,7 @@ function applyParamflags(rawFn, restype, argtypes, paramflags) {
|
|
|
171
172
|
_as_parameter_: { value: rawFn.address },
|
|
172
173
|
_ffi: { value: rawFn._ffi },
|
|
173
174
|
callAsync: { value: (...args) => invokeWithFlags("callAsync", args) },
|
|
175
|
+
callOn: { value: (target, ...args) => callOn(paramflagsWrapper, target, args) },
|
|
174
176
|
errcheck: {
|
|
175
177
|
get: () => errcheck,
|
|
176
178
|
set: (callback) => {
|
|
@@ -403,6 +405,12 @@ function createFuncPtrType(native, typeName, abi) {
|
|
|
403
405
|
enumerable: false,
|
|
404
406
|
configurable: false,
|
|
405
407
|
},
|
|
408
|
+
callOn: {
|
|
409
|
+
value: (target, ...args) => callOn(callMethod, target, args),
|
|
410
|
+
writable: false,
|
|
411
|
+
enumerable: false,
|
|
412
|
+
configurable: false,
|
|
413
|
+
},
|
|
406
414
|
errcheck: {
|
|
407
415
|
get() {
|
|
408
416
|
return callState.errcheck;
|
package/lib/index.d.ts
CHANGED
|
@@ -223,6 +223,9 @@ export interface FFIFunction {
|
|
|
223
223
|
/** Call the native function asynchronously on a worker thread. */
|
|
224
224
|
callAsync(...args: any[]): Promise<any>;
|
|
225
225
|
|
|
226
|
+
/** Like {@link callAsync}, on the thread of an {@link Executor}. */
|
|
227
|
+
callOn(target: ExecutorTarget, ...args: any[]): Promise<any>;
|
|
228
|
+
|
|
226
229
|
/** The function name in the native library. */
|
|
227
230
|
readonly funcName: string;
|
|
228
231
|
|
|
@@ -287,6 +290,8 @@ export type NativeErrcheckCallback<TArgs extends readonly FFIType[] = FFIType[],
|
|
|
287
290
|
export interface TypedFFIFunction<TArgs extends readonly FFIType[], TRet extends FFIType | null> {
|
|
288
291
|
(...args: FFIArgs<TArgs>): FFIReturn<TRet>;
|
|
289
292
|
callAsync(...args: FFIArgs<TArgs>): Promise<FFIReturn<TRet>>;
|
|
293
|
+
/** Like {@link callAsync}, on the thread of an {@link Executor}. */
|
|
294
|
+
callOn(target: ExecutorTarget, ...args: FFIArgs<TArgs>): Promise<FFIReturn<TRet>>;
|
|
290
295
|
readonly funcName: string;
|
|
291
296
|
readonly address: bigint;
|
|
292
297
|
readonly _as_parameter_: bigint;
|
|
@@ -471,6 +476,9 @@ export interface FunctionWrapper {
|
|
|
471
476
|
/** Call the function asynchronously on a worker thread. */
|
|
472
477
|
callAsync(...args: any[]): Promise<any>;
|
|
473
478
|
|
|
479
|
+
/** Like {@link callAsync}, on the thread of an {@link Executor}. */
|
|
480
|
+
callOn(target: ExecutorTarget, ...args: any[]): Promise<any>;
|
|
481
|
+
|
|
474
482
|
/** Argument types. Set before calling. */
|
|
475
483
|
argtypes: FFIType[];
|
|
476
484
|
|
|
@@ -730,6 +738,73 @@ export class ThreadSafeCallback extends Callback {
|
|
|
730
738
|
drain(): number;
|
|
731
739
|
}
|
|
732
740
|
|
|
741
|
+
// =============================================================================
|
|
742
|
+
// Executor
|
|
743
|
+
// =============================================================================
|
|
744
|
+
|
|
745
|
+
/**
|
|
746
|
+
* Options of {@link Executor}.
|
|
747
|
+
* @category Async Calls
|
|
748
|
+
*/
|
|
749
|
+
export interface ExecutorOptions {
|
|
750
|
+
/** Thread name shown by debuggers and profilers (default `"node-ctypes"`). */
|
|
751
|
+
name?: string;
|
|
752
|
+
}
|
|
753
|
+
|
|
754
|
+
/**
|
|
755
|
+
* Where {@link FFIFunction.callOn} runs a call: an {@link Executor}, or an
|
|
756
|
+
* executor with an `AbortSignal` that cancels the call while it is queued
|
|
757
|
+
* (the promise rejects with `signal.reason`; a started call completes).
|
|
758
|
+
* @category Async Calls
|
|
759
|
+
*/
|
|
760
|
+
export type ExecutorTarget = Executor | { readonly executor: Executor; readonly signal?: AbortSignal };
|
|
761
|
+
|
|
762
|
+
/**
|
|
763
|
+
* A native thread owned by node-ctypes, with a FIFO queue of calls.
|
|
764
|
+
*
|
|
765
|
+
* `fn.callOn(executor, ...args)` is `fn.callAsync(...args)` (same conversions,
|
|
766
|
+
* out parameters, errcheck and argument lifetime) run on this thread instead
|
|
767
|
+
* of a libuv worker: calls run one at a time, in arrival order, so a slow call
|
|
768
|
+
* never occupies the libuv pool (fs, dns, crypto) and calls that must share a
|
|
769
|
+
* thread (thread-local state, thread-affine handles) can.
|
|
770
|
+
*
|
|
771
|
+
* The thread starts with the first call. While calls are pending the process
|
|
772
|
+
* stays alive; an idle executor does not keep it alive and is collected with
|
|
773
|
+
* its thread when unreferenced. When the process exits (or a worker thread
|
|
774
|
+
* terminates) queued calls are discarded and a running call is left to finish
|
|
775
|
+
* on its own.
|
|
776
|
+
*
|
|
777
|
+
* No Python equivalent.
|
|
778
|
+
*
|
|
779
|
+
* @example
|
|
780
|
+
* ```javascript
|
|
781
|
+
* const executor = new Executor({ name: "device" });
|
|
782
|
+
* const result = await lib.slow_read.callOn(executor, handle, buffer, size);
|
|
783
|
+
* const controller = new AbortController();
|
|
784
|
+
* const next = lib.slow_read.callOn({ executor, signal: controller.signal }, handle, buffer, size);
|
|
785
|
+
* controller.abort(); // rejects `next` if it has not started
|
|
786
|
+
* await executor.close();
|
|
787
|
+
* ```
|
|
788
|
+
*
|
|
789
|
+
* @category Async Calls
|
|
790
|
+
*/
|
|
791
|
+
export class Executor {
|
|
792
|
+
constructor(options?: ExecutorOptions);
|
|
793
|
+
/**
|
|
794
|
+
* Reject new calls, wait for the accepted ones, then stop the thread.
|
|
795
|
+
* Always returns the same promise; a closed executor cannot be reopened.
|
|
796
|
+
*/
|
|
797
|
+
close(): Promise<void>;
|
|
798
|
+
/** Calls queued or running. */
|
|
799
|
+
readonly pending: number;
|
|
800
|
+
/** Calls settled since the executor was created. */
|
|
801
|
+
readonly completed: number;
|
|
802
|
+
/** Whether the thread is running (started by the first call, stopped by `close()`). */
|
|
803
|
+
readonly running: boolean;
|
|
804
|
+
/** Whether `close()` has been called. */
|
|
805
|
+
readonly closed: boolean;
|
|
806
|
+
}
|
|
807
|
+
|
|
733
808
|
// =============================================================================
|
|
734
809
|
// Structures
|
|
735
810
|
// =============================================================================
|
package/lib/index.js
CHANGED
|
@@ -27,6 +27,7 @@ import { createLazyLoader } from "./core/lazy-loader.js";
|
|
|
27
27
|
import { callback as createCallback, threadSafeCallback as createThreadSafeCallback } from "./core/callback.js";
|
|
28
28
|
import { createCFUNCTYPE, createWINFUNCTYPE } from "./core/funcptr.js";
|
|
29
29
|
import { createLibraryClasses } from "./core/Library.js";
|
|
30
|
+
import { initExecutor } from "./core/executor.js";
|
|
30
31
|
import {
|
|
31
32
|
alloc as _alloc,
|
|
32
33
|
cstring as _cstring,
|
|
@@ -111,7 +112,10 @@ const native = externalBuffers ? rawNative : wrapNative(rawNative);
|
|
|
111
112
|
_initConstants(native);
|
|
112
113
|
|
|
113
114
|
// Re-esporta le classi native
|
|
114
|
-
const { Version, Library, FFIFunction, Callback, ThreadSafeCallback, StructType, ArrayType, CType } = native;
|
|
115
|
+
const { Version, Library, FFIFunction, Callback, ThreadSafeCallback, StructType, ArrayType, CType, Executor } = native;
|
|
116
|
+
|
|
117
|
+
// fn.callOn(executor, ...args) imposta l'Executor della chiamata nel nativo.
|
|
118
|
+
initExecutor(native);
|
|
115
119
|
|
|
116
120
|
// Gli errori di conversione degli argomenti nel nativo sono ctypes.ArgumentError.
|
|
117
121
|
native.setArgumentError(ArgumentError);
|
|
@@ -593,6 +597,7 @@ export {
|
|
|
593
597
|
FFIFunction,
|
|
594
598
|
Callback,
|
|
595
599
|
ThreadSafeCallback,
|
|
600
|
+
Executor,
|
|
596
601
|
CType,
|
|
597
602
|
|
|
598
603
|
// Funzioni base
|
package/lib/memory/buffer.js
CHANGED
|
@@ -74,14 +74,19 @@ const kTransientPoolSize = 8192;
|
|
|
74
74
|
const FixedArrayBuffer = ArrayBuffer;
|
|
75
75
|
const bufferFrom = Buffer.from;
|
|
76
76
|
const zeroBuffer = Buffer.alloc;
|
|
77
|
+
|
|
77
78
|
let transientPool = new FixedArrayBuffer(kTransientPoolSize);
|
|
78
79
|
let transientOffset = 0;
|
|
80
|
+
let snapshotPool = new FixedArrayBuffer(kTransientPoolSize);
|
|
81
|
+
let snapshotOffset = 0;
|
|
79
82
|
|
|
80
83
|
/**
|
|
81
|
-
* Zero-filled buffer for a
|
|
84
|
+
* Zero-filled buffer for a value that only lives for one native call. A small
|
|
82
85
|
* Buffer.alloc lives on the V8 heap and must be externalized when native code
|
|
83
86
|
* reads it; slices of an off-heap pool avoid that. Slices are never reused, so
|
|
84
|
-
* a fresh pool is already zeroed.
|
|
87
|
+
* a fresh pool is already zeroed. The pool is never handed to user code:
|
|
88
|
+
* native code may still use these slices while JavaScript runs (callbacks,
|
|
89
|
+
* async calls).
|
|
85
90
|
*
|
|
86
91
|
* @param {number} size - Size in bytes to allocate
|
|
87
92
|
* @returns {Buffer} Zero-initialized buffer
|
|
@@ -97,6 +102,36 @@ export function allocTransient(size) {
|
|
|
97
102
|
return buf;
|
|
98
103
|
}
|
|
99
104
|
|
|
105
|
+
/**
|
|
106
|
+
* Zero-filled buffer for an owned callback argument snapshot, sliced as
|
|
107
|
+
* {@link allocTransient} from a separate pool: a snapshot's `.buffer` exposes
|
|
108
|
+
* only other snapshots, and detaching it cannot affect native-call temporaries.
|
|
109
|
+
* Retained slices keep their pool alive; a pool detached by user code
|
|
110
|
+
* (`transfer()`, a transfer list) is replaced.
|
|
111
|
+
*
|
|
112
|
+
* @param {number} size - Size in bytes to allocate
|
|
113
|
+
* @returns {Buffer} Zero-initialized buffer
|
|
114
|
+
*/
|
|
115
|
+
export function allocSnapshot(size) {
|
|
116
|
+
if (size > kTransientPoolSize >>> 2) return zeroBuffer(size);
|
|
117
|
+
if (snapshotOffset + size > kTransientPoolSize) {
|
|
118
|
+
snapshotPool = new FixedArrayBuffer(kTransientPoolSize);
|
|
119
|
+
snapshotOffset = 0;
|
|
120
|
+
}
|
|
121
|
+
let buf;
|
|
122
|
+
try {
|
|
123
|
+
buf = bufferFrom(snapshotPool, snapshotOffset, size);
|
|
124
|
+
} catch (error) {
|
|
125
|
+
// Un pool staccato ha byteLength 0: il controllo resta fuori dal percorso caldo.
|
|
126
|
+
if (!snapshotPool.detached) throw error;
|
|
127
|
+
snapshotPool = new FixedArrayBuffer(kTransientPoolSize);
|
|
128
|
+
snapshotOffset = 0;
|
|
129
|
+
buf = bufferFrom(snapshotPool, 0, size);
|
|
130
|
+
}
|
|
131
|
+
snapshotOffset += (size + 7) & ~7;
|
|
132
|
+
return buf;
|
|
133
|
+
}
|
|
134
|
+
|
|
100
135
|
/**
|
|
101
136
|
* Creates a buffer containing a null-terminated C string.
|
|
102
137
|
*
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "node-ctypes",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.11.0",
|
|
4
4
|
"description": "Python ctypes-like FFI for Node.js using libffi",
|
|
5
5
|
"author": "Damiano Mazzella",
|
|
6
6
|
"license": "MIT",
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"bugs": {
|
|
12
12
|
"url": "https://github.com/dmazzella/node-ctypes/issues"
|
|
13
13
|
},
|
|
14
|
-
"homepage": "https://github.
|
|
14
|
+
"homepage": "https://dmazzella.github.io/node-ctypes/",
|
|
15
15
|
"keywords": [
|
|
16
16
|
"ffi",
|
|
17
17
|
"ctypes",
|