node-ctypes 2.10.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 +27 -1
- package/README.md +41 -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/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/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,31 @@ 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
|
+
|
|
10
35
|
## [2.10.0] - 2026-11-06
|
|
11
36
|
|
|
12
37
|
### Fixed
|
|
@@ -1156,7 +1181,8 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
|
|
|
1156
1181
|
|
|
1157
1182
|
Initial releases.
|
|
1158
1183
|
|
|
1159
|
-
[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
|
|
1160
1186
|
[2.10.0]: https://github.com/dmazzella/node-ctypes/compare/v2.9.0...v2.10.0
|
|
1161
1187
|
[2.9.0]: https://github.com/dmazzella/node-ctypes/compare/v2.8.0...v2.9.0
|
|
1162
1188
|
[2.8.0]: https://github.com/dmazzella/node-ctypes/compare/v2.7.0...v2.8.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
|
|
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() {
|
|
@@ -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/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",
|