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 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.10.0...HEAD
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
@@ -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
+ }
@@ -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.10.0",
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.com/dmazzella/node-ctypes#readme",
14
+ "homepage": "https://dmazzella.github.io/node-ctypes/",
15
15
  "keywords": [
16
16
  "ffi",
17
17
  "ctypes",