node-ctypes 2.12.0 → 2.12.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,83 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.12.2] - 2026-11-11
11
+
12
+ ### Fixed
13
+
14
+ - **`callOn` target lost during reentrant conversions**: the executor of a
15
+ call was passed as ambient state just before `callAsync`; an argument
16
+ adapter (`from_param`) that made another `callOn` overwrote and cleared it,
17
+ and the outer call ran on the libuv pool. Each invocation now passes its own
18
+ call object down to the native call (`FFIFunction.callOn`), also when an
19
+ adapter calls the same function.
20
+ - **Cancellation of the wrong call**: the id of the call to cancel was read
21
+ from the executor after the call returned; after an inline completion its
22
+ errcheck may have queued other calls, and aborting the signal cancelled one
23
+ of those. The native call now writes the id of its own job into the call
24
+ object.
25
+ - **Abort during argument preparation ignored**: a signal aborted by an
26
+ argument adapter was checked before the conversions and listened to only
27
+ after submission, so the call ran. The native call checks the signal after
28
+ preparing the arguments and before queuing the call, and rejects with
29
+ `signal.reason` without running it.
30
+
31
+ ### Changed
32
+
33
+ - **Coalesced completion notifications**: the executor thread notified the
34
+ JavaScript thread once per completed call, while each delivery takes all the
35
+ completed calls: in a burst most deliveries found nothing to do (10,000
36
+ deliveries for 10,000 calls with `spin: 0`, all the promises settled by the
37
+ first). It now notifies only when no delivery is pending (1 delivery in the
38
+ same burst). Short calls cost about 25% less (sequential awaited calls about
39
+ 2.7 µs instead of 3.6 µs, bursts 2.4 µs instead of 3.2 µs, with a signal
40
+ 4.0 µs instead of 4.9 µs, locally on Windows x64).
41
+
42
+ ### Added
43
+
44
+ - Regression tests for the three defects (thread identity of the call, nested
45
+ calls on another executor and on the same function, cancellation after an
46
+ inline completion, abort during preparation) and for the coalesced
47
+ notifications; test fixture function `fixture_current_thread`.
48
+
49
+ ## [2.12.1] - 2026-11-11
50
+
51
+ ### Changed
52
+
53
+ - **Executor inline wait per function**: the JavaScript thread now waits for
54
+ a call for about one and a half times the typical duration of its function
55
+ (measured on every call; shorter durations weigh more, so a slow first call
56
+ is forgotten in a few calls), at least `spin` and at most the new
57
+ `spinLimit` option (microseconds, default 500, `0` for never more than
58
+ `spin`); a function that usually takes longer is not waited for. Before, a
59
+ single backoff per executor skipped the wait for every function after a slow
60
+ call: a slow function alternated with fast ones (e.g. ADSI `GetColumn`
61
+ with `FreeColumn`) sent the fast ones through the event loop too. On that
62
+ pattern (one call of 65 µs and two fast calls) the overhead per round drops
63
+ from about 47 µs to about 18 µs. The backoff is now per function: when its
64
+ waits time out (e.g. where the executor thread wakes up slowly), a function
65
+ skips the next 1, 3, 7, ... up to 1023 waits, without affecting the others.
66
+
67
+ ### Fixed
68
+
69
+ - **Executor busy waits on a loaded machine**: the busy waits called
70
+ `std::this_thread::yield()`, which, with other threads ready on the same
71
+ core, gives the core away for a whole time slice: on a loaded machine (CI
72
+ VMs running test files in parallel) each call cost tens of milliseconds, 401
73
+ awaited calls 13 s instead of 0.13 s. The waits no longer yield, the
74
+ executor thread polls for the next call for at most 50 µs whatever `spin`
75
+ is, and the JavaScript thread stops waiting as soon as a native thread waits
76
+ for it (a thread-safe callback invoked by the awaited call). Under load the
77
+ fast path is now 3 to 5 times faster than `spin: 0`, as on an idle machine.
78
+
79
+ ### Added
80
+
81
+ - **`Executor` `spinLimit` option**, and tests for the per-function wait
82
+ (a function beyond `spin` within `spinLimit`, a slow function alternated
83
+ with a fast one, a function that becomes fast again), checking the budget
84
+ computed per function (independent of the speed of the machine); test fixture
85
+ function `fixture_busy_wait_us`.
86
+
10
87
  ## [2.12.0] - 2026-11-10
11
88
 
12
89
  ### Added
@@ -1233,7 +1310,9 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
1233
1310
 
1234
1311
  Initial releases.
1235
1312
 
1236
- [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.12.0...HEAD
1313
+ [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.12.2...HEAD
1314
+ [2.12.2]: https://github.com/dmazzella/node-ctypes/compare/v2.12.1...v2.12.2
1315
+ [2.12.1]: https://github.com/dmazzella/node-ctypes/compare/v2.12.0...v2.12.1
1237
1316
  [2.12.0]: https://github.com/dmazzella/node-ctypes/compare/v2.11.1...v2.12.0
1238
1317
  [2.11.1]: https://github.com/dmazzella/node-ctypes/compare/v2.11.0...v2.11.1
1239
1318
  [2.11.0]: https://github.com/dmazzella/node-ctypes/compare/v2.10.0...v2.11.0
package/README.md CHANGED
@@ -136,13 +136,16 @@ await executor.close(); // waits for the accepted calls, then stops the thread
136
136
  and stops the thread (an executor cannot be reopened).
137
137
  - `executor.pending`, `completed`, `running` and `closed` report its state.
138
138
  - `spin` (microseconds, default 50, `0` to disable): after a call the thread
139
- polls for the next one this long before sleeping, and the JavaScript thread
139
+ polls for the next one this long (at most 50 µs) before sleeping, and the JavaScript thread
140
140
  waits this long for a call submitted to an idle executor, completing it
141
141
  without a round trip through the event loop. Awaited calls in sequence then
142
142
  cost a few microseconds instead of tens; its errcheck may run before
143
- `callOn` returns. Inline completions are limited to 1 ms per turn of the
144
- event loop, so timers, I/O and UI events keep running; slow calls fall back
145
- to the normal notification.
143
+ `callOn` returns. The wait is per function: `spin` for a function not
144
+ called yet, then about one and a half times its measured typical duration,
145
+ up to `spinLimit` (microseconds, default 500); a function that usually takes
146
+ longer completes through the event loop without delaying the others. Inline
147
+ completions are limited to 1 ms per turn of the event loop, so timers, I/O
148
+ and UI events keep running.
146
149
  - A call that has started cannot be interrupted: the signal only removes
147
150
  queued calls.
148
151
  - On process exit (or worker termination) queued calls are discarded and a
Binary file
Binary file
@@ -149,6 +149,10 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
149
149
  set: () => {},
150
150
  configurable: true,
151
151
  },
152
+ _callOn: {
153
+ get: () => resolve()._callOn,
154
+ configurable: true,
155
+ },
152
156
  });
153
157
 
154
158
  return func;
@@ -259,12 +263,12 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
259
263
  const captureHere = convertResult === undefined;
260
264
  const callState = { errcheck: null };
261
265
  let checkedSync;
262
- const checkedCall = (method, args, checked) => {
266
+ const checkedCall = (method, args, checked, target) => {
263
267
  const originalArgs = Array.isArray(args) ? args : Array.prototype.slice.call(args);
264
268
  const func = errcheckFunc();
265
269
  const finish = (result) => checked(convertResult === undefined ? result : convertResult(result), func, originalArgs);
266
270
  const call = method === "call" ? (checkedSync ??= ffiFunc._makeCheckedCall()) : undefined;
267
- return callWithResultHandler(ffiFunc, method, originalArgs, C, finish, hasAdapters || argumentsNeedOwners(originalArgs), call);
271
+ return callWithResultHandler(ffiFunc, method, originalArgs, C, finish, hasAdapters || argumentsNeedOwners(originalArgs), call, target);
268
272
  };
269
273
  const ownedCall = (method, args) => callWithArgumentOwners(ffiFunc, method, args, C);
270
274
  const invoke = (method, args, checked) => {
@@ -274,6 +278,12 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
274
278
 
275
279
  let callMethod = specializeCall(ffiFunc, "call", C, callState, (args, checked) => invoke("call", args, checked), captureHere);
276
280
  let asyncCallMethod = specializeCall(ffiFunc, "callAsync", C, callState, (args, checked) => invoke("callAsync", args, checked), captureHere);
281
+ // callOn(): the same call on the Executor of `target` (this invocation's own).
282
+ let onExecutor = (target, args) => {
283
+ if (captureHere && callState.errcheck !== null) return checkedCall("callAsync", args, callState.errcheck, target);
284
+ if (captureHere && (hasAdapters || argumentsNeedOwners(args))) return callWithArgumentOwners(ffiFunc, "callAsync", args, C, undefined, undefined, undefined, target);
285
+ return ffiFunc.callOn(target, ...convertAll(args));
286
+ };
277
287
 
278
288
  // Result handlers run inside the native call scope, after conversion and
279
289
  // with the hook/arguments captured before any argument adapter executes.
@@ -291,6 +301,12 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
291
301
  if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, C, finish);
292
302
  return rawAsync.apply(this, args).then((result) => finish(result, args));
293
303
  };
304
+ const rawOn = onExecutor;
305
+ onExecutor = (target, args) => {
306
+ if (callState.errcheck !== null) return checkedCall("callAsync", args, callState.errcheck, target);
307
+ if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, C, finish, undefined, undefined, target);
308
+ return rawOn(target, args).then((result) => finish(result, args));
309
+ };
294
310
  }
295
311
 
296
312
  // If use_last_error / use_errno is set on the library, wrap callMethod
@@ -307,6 +323,11 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
307
323
  self._lastCalledFfi = ffiFunc;
308
324
  return origAsync.apply(this, args);
309
325
  };
326
+ const origOn = onExecutor;
327
+ onExecutor = (target, args) => {
328
+ self._lastCalledFfi = ffiFunc;
329
+ return origOn(target, args);
330
+ };
310
331
  }
311
332
 
312
333
  // Python: errcheck riceve la funzione su cui è impostato (l'attributo
@@ -321,6 +342,7 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
321
342
  _ffi: { value: ffiFunc },
322
343
  callAsync: { value: asyncCallMethod, writable: false, enumerable: false, configurable: false },
323
344
  callOn: { value: (target, ...args) => callOn(callMethod, target, args), writable: false, enumerable: false, configurable: false },
345
+ _callOn: { value: onExecutor },
324
346
  // Esponi errcheck come setter/getter
325
347
  errcheck: {
326
348
  get() {
@@ -140,15 +140,29 @@ function callOwned3(ffiFunc, method, C0, C1, C2, a0, a1, a2) {
140
140
  }
141
141
  }
142
142
 
143
+ // The native asynchronous entry: on the Executor of `call` (callOn: the
144
+ // target of this invocation only) or, without it, on the libuv pool.
145
+ function invokeAsync(ffiFunc, call, resultHandler, converted) {
146
+ if (call === undefined) return resultHandler === undefined ? ffiFunc.callAsync(...converted) : ffiFunc._callAsyncWithErrcheck(resultHandler, ...converted);
147
+ return resultHandler === undefined ? ffiFunc.callOn(call, ...converted) : ffiFunc._callOnWithErrcheck(call, resultHandler, ...converted);
148
+ }
149
+
143
150
  // The registry is a GC root, including while another converter reenters JS.
144
- export function callWithArgumentOwners(ffiFunc, method, args, converters, finish, resultHandler, checkedCall) {
151
+ // `call`: the callOn target of an asynchronous call.
152
+ export function callWithArgumentOwners(ffiFunc, method, args, converters, finish, resultHandler, checkedCall, call) {
145
153
  const owners = [];
146
154
  // Synchronous calls nest strictly, so a stack avoids hashing a fresh array.
147
155
  activeOwnerStack.push(owners);
148
156
  try {
149
157
  const converted = convertArguments(args, converters, owners);
150
158
  const result =
151
- resultHandler === undefined ? ffiFunc[method](...converted) : checkedCall === undefined ? ffiFunc[method === "callAsync" ? "_callAsyncWithErrcheck" : "_callWithErrcheck"](resultHandler, ...converted) : checkedCall(resultHandler, ...converted);
159
+ method === "callAsync"
160
+ ? invokeAsync(ffiFunc, call, resultHandler, converted)
161
+ : resultHandler === undefined
162
+ ? ffiFunc[method](...converted)
163
+ : checkedCall === undefined
164
+ ? ffiFunc._callWithErrcheck(resultHandler, ...converted)
165
+ : checkedCall(resultHandler, ...converted);
152
166
  if (method === "callAsync") {
153
167
  const completed = finish === undefined ? result : result.then((value) => finish(value, args));
154
168
  activeArgumentOwners.add(owners);
@@ -160,10 +174,11 @@ export function callWithArgumentOwners(ffiFunc, method, args, converters, finish
160
174
  }
161
175
  }
162
176
 
163
- export function callWithResultHandler(ffiFunc, method, args, converters, handler, retainOwners, checkedCall) {
164
- if (retainOwners) return callWithArgumentOwners(ffiFunc, method, args, converters, undefined, handler, checkedCall);
177
+ export function callWithResultHandler(ffiFunc, method, args, converters, handler, retainOwners, checkedCall, call) {
178
+ if (retainOwners) return callWithArgumentOwners(ffiFunc, method, args, converters, undefined, handler, checkedCall, call);
165
179
  if (checkedCall !== undefined) return checkedCall(handler, ...convertArguments(args, converters));
166
- return ffiFunc[method === "callAsync" ? "_callAsyncWithErrcheck" : "_callWithErrcheck"](handler, ...convertArguments(args, converters));
180
+ if (method === "callAsync") return invokeAsync(ffiFunc, call, handler, convertArguments(args, converters));
181
+ return ffiFunc._callWithErrcheck(handler, ...convertArguments(args, converters));
167
182
  }
168
183
 
169
184
  /**
@@ -21,10 +21,14 @@ export function initExecutor(nativeModule) {
21
21
  * Run `fn.callAsync(...args)` on `target`: an `Executor`, or
22
22
  * `{ executor, signal }` to cancel the call while it is still queued.
23
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.
24
+ * Each invocation passes its own call object (`{ executor, signal, job }`)
25
+ * down to the native call: argument adapters (`from_param`) and errcheck may
26
+ * run other callOn meanwhile, and they have theirs. The native call reads the
27
+ * executor from it, does not queue the call when the signal was aborted while
28
+ * the arguments were prepared, and writes the job id into it, so that the
29
+ * abort cancels this call and no other.
26
30
  *
27
- * @param {Function} fn - A function with `callAsync` and `_ffi`
31
+ * @param {Function} fn - A function with `_callOn(call, args)`
28
32
  * @param {Object} target - Executor or `{ executor, signal }`
29
33
  * @param {Array} args - Call arguments
30
34
  * @returns {Promise<*>}
@@ -44,20 +48,23 @@ export function callOn(fn, target, args) {
44
48
  }
45
49
  if (signal?.aborted) return Promise.reject(signal.reason);
46
50
 
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;
51
+ const call = { executor, signal, job: 0 };
52
+ const promise = fn._callOn(call, args);
53
+ // Internal: a target object asking for it (`_job`) receives the job id
54
+ // (node-comtypes records the calls of an operation to cancel them).
55
+ if (target !== executor && "_job" in target) target._job = call.job;
56
+ // No job: rejected without being queued (closed executor, signal aborted
57
+ // while the arguments were prepared).
58
+ if (signal === undefined || call.job === 0) return promise;
57
59
 
58
60
  // 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
+ // that has started (or completed inline) completes normally.
62
+ const abort = () => executor._cancel(call.job, signal.reason);
63
+ if (signal.aborted) {
64
+ // Aborted by code that ran during the call (an inline errcheck).
65
+ abort();
66
+ return promise;
67
+ }
61
68
  signal.addEventListener("abort", abort, { once: true });
62
69
  return promise.finally(() => signal.removeEventListener("abort", abort));
63
70
  }
@@ -95,7 +95,8 @@ function applyParamflags(rawFn, restype, argtypes, paramflags) {
95
95
 
96
96
  let errcheck = null;
97
97
 
98
- const invokeWithFlags = (method, callArgs) => {
98
+ // `call`: the callOn target when `method` is "callOn".
99
+ const invokeWithFlags = (method, callArgs, call) => {
99
100
  const checked = errcheck;
100
101
  const namedForm =
101
102
  callArgs.length === 1 &&
@@ -159,6 +160,7 @@ function applyParamflags(rawFn, restype, argtypes, paramflags) {
159
160
  const previous = rawFn.errcheck;
160
161
  rawFn.errcheck = finish;
161
162
  try {
163
+ if (method === "callOn") return rawFn._callOn(call, rawArgs);
162
164
  return method === "callAsync" ? rawFn.callAsync(...rawArgs) : rawFn(...rawArgs);
163
165
  } finally {
164
166
  rawFn.errcheck = previous;
@@ -173,6 +175,7 @@ function applyParamflags(rawFn, restype, argtypes, paramflags) {
173
175
  _ffi: { value: rawFn._ffi },
174
176
  callAsync: { value: (...args) => invokeWithFlags("callAsync", args) },
175
177
  callOn: { value: (target, ...args) => callOn(paramflagsWrapper, target, args) },
178
+ _callOn: { value: (call, args) => invokeWithFlags("callOn", args, call) },
176
179
  errcheck: {
177
180
  get: () => errcheck,
178
181
  set: (callback) => {
@@ -324,11 +327,11 @@ function createFuncPtrType(native, typeName, abi) {
324
327
  const callState = { errcheck: null };
325
328
  let checkedSync;
326
329
  const finish = (result) => (convertResult === undefined ? result : convertResult(result));
327
- const checkedCall = (method, args, checked) => {
330
+ const checkedCall = (method, args, checked, target) => {
328
331
  const originalArgs = Array.isArray(args) ? args : Array.prototype.slice.call(args);
329
332
  const resultHandler = (result) => checked(finish(result), callMethod, originalArgs);
330
333
  const call = method === "call" ? (checkedSync ??= ffiFunc._makeCheckedCall()) : undefined;
331
- return callWithResultHandler(ffiFunc, method, originalArgs, converters, resultHandler, hasAdapters || argumentsNeedOwners(originalArgs), call);
334
+ return callWithResultHandler(ffiFunc, method, originalArgs, converters, resultHandler, hasAdapters || argumentsNeedOwners(originalArgs), call, target);
332
335
  };
333
336
 
334
337
  const invoke = (args, checked) => {
@@ -348,7 +351,14 @@ function createFuncPtrType(native, typeName, abi) {
348
351
  if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, converters, finish);
349
352
  return ffiFunc.callAsync(...convertArguments(args, converters)).then((result) => finish(result, args));
350
353
  };
354
+ // callOn(): the same call on the Executor of `target` (this invocation's own).
355
+ const onExecutor = function (target, args) {
356
+ if (callState.errcheck !== null) return checkedCall("callAsync", args, callState.errcheck, target);
357
+ if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, converters, finish, undefined, undefined, target);
358
+ return ffiFunc.callOn(target, ...convertArguments(args, converters)).then((result) => finish(result, args));
359
+ };
351
360
  let callAsync = asyncCall;
361
+ let callOnExecutor = onExecutor;
352
362
  let callbackProperties = {};
353
363
  if (callback !== undefined) {
354
364
  const assertLive = () => {
@@ -381,6 +391,16 @@ function createFuncPtrType(native, typeName, abi) {
381
391
  throw error;
382
392
  }
383
393
  };
394
+ callOnExecutor = function (target, args) {
395
+ assertLive();
396
+ activeCalls++;
397
+ try {
398
+ return onExecutor(target, args).finally(() => activeCalls--);
399
+ } catch (error) {
400
+ activeCalls--;
401
+ throw error;
402
+ }
403
+ };
384
404
  callbackProperties = Object.getOwnPropertyDescriptors(callback);
385
405
  callbackProperties.release.value = release;
386
406
  callbackProperties[Symbol.dispose].value = release;
@@ -411,6 +431,7 @@ function createFuncPtrType(native, typeName, abi) {
411
431
  enumerable: false,
412
432
  configurable: false,
413
433
  },
434
+ _callOn: { value: callOnExecutor },
414
435
  errcheck: {
415
436
  get() {
416
437
  return callState.errcheck;
package/lib/index.d.ts CHANGED
@@ -752,13 +752,22 @@ export interface ExecutorOptions {
752
752
  /**
753
753
  * Busy-wait budget in microseconds (default 50, 0 to disable, at most
754
754
  * 10000). After a call the executor thread polls for the next one this long
755
- * before sleeping, and the JavaScript thread waits this long for a call
756
- * submitted to an idle executor, completing it without a round trip through
757
- * the event loop: awaited calls in sequence cost a few microseconds instead
758
- * of tens. When the wait times out (slow calls) the following calls skip it,
759
- * with exponential backoff, until one completes in time again.
755
+ * (at most 50 µs) before sleeping, and the JavaScript thread waits for a call submitted to
756
+ * an idle executor, completing it without a round trip through the event
757
+ * loop: awaited calls in sequence cost a few microseconds instead of tens.
758
+ * The JavaScript thread waits `spin` for a function not called yet; then,
759
+ * per function, about one and a half times its typical duration (measured
760
+ * on every call), at least `spin` and at most {@link spinLimit}. A function
761
+ * that usually takes longer is not waited for: its calls complete through
762
+ * the event loop, without delaying the others.
760
763
  */
761
764
  spin?: number;
765
+ /**
766
+ * Longest wait in microseconds for a function that usually takes longer
767
+ * than {@link spin} (default 500, at most 10000; 0: never more than
768
+ * `spin`).
769
+ */
770
+ spinLimit?: number;
762
771
  }
763
772
 
764
773
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-ctypes",
3
- "version": "2.12.0",
3
+ "version": "2.12.2",
4
4
  "description": "Python ctypes-like FFI for Node.js using libffi",
5
5
  "author": "Damiano Mazzella",
6
6
  "license": "MIT",