node-ctypes 2.12.1 → 2.13.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,131 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.13.0] - 2026-11-14
11
+
12
+ ### Changed
13
+
14
+ - **Register-frame calls instead of libffi**: synchronous calls of any
15
+ signature of scalars, pointers and strings (up to 32 arguments) no longer go
16
+ through libffi on AArch64, x86-64 System V and Win64. Each argument is
17
+ converted straight into its register or stack word and one C++ signature per
18
+ ABI passes the frame; before, libffi handled every signature with a pointer
19
+ or a string and every one over four arguments. On x64 the call keeps the
20
+ variadic register setup of libffi (AL on System V, doubles mirrored in the
21
+ integer registers on Win64) for variadic functions declared with argtypes.
22
+ Functions without argtypes and, on x64, variadic arguments use it too. On
23
+ Apple ARM64 the stack arguments are packed by size and natural alignment,
24
+ as the platform ABI (and libffi) lay them out; variadic arguments there
25
+ stay with libffi.
26
+ - **Native functions returned by `CDLL.func()` and prototypes**: when the
27
+ arguments need no JavaScript conversion (scalars, `c_char_p` strings) the
28
+ returned function is the native one, as in Koffi, instead of a JavaScript
29
+ wrapper; calls with objects (`CData` instances, buffers for `c_char_p`,
30
+ `_as_parameter_`), with `errcheck` and the other signatures go to the
31
+ JavaScript converters as before. The JavaScript wrappers shared V8 feedback
32
+ across all functions, which made calls slower in programs using many of them.
33
+ Visible differences for `CDLL.func()`: the function's `length` is 0 (it was
34
+ the number of `argtypes` up to six) and its `name` is the C function's;
35
+ `Function.prototype.toString` shows `[native code]` (prototypes too). Its
36
+ properties (`errcheck`, `callAsync`, `callOn`, `address`, ...) are unchanged.
37
+ - **Fast path up to 32 arguments** (it was 8), reading the arguments with a
38
+ capacity close to the declared signature (2, 4 or 8); primitive arguments
39
+ pass through the JavaScript wrapper without conversion or copies.
40
+ - **Faster struct arguments**: structs passed by value take the fast path at
41
+ any size (it was up to 16 bytes); libffi copies their bytes from the buffer
42
+ before the call, as the general path did. A plain object of field values
43
+ skips the generic parameter probes and the struct's Buffer is passed without
44
+ a second conversion; `create`/`set` overrides, getters and field validation
45
+ are unchanged. A `{x, y}` argument is about 20% faster, a four-double HFA
46
+ argument about 30%.
47
+ - **Faster attribute calls** (`lib.name(...)`): a function already looked up
48
+ is found with one lookup, before the library's own properties, and its
49
+ arguments are forwarded without a rest array; a call through the attribute
50
+ is about 30% faster. As in Python, where `__getattr__` stores the function
51
+ on the library, a property defined later with the same name still replaces
52
+ it, and `delete lib.name` now forgets the function: the next access returns
53
+ a new one with no `argtypes`/`restype` (before, the same function).
54
+ - **Faster long string arguments**: strings that do not fit the 512-byte inline
55
+ buffer are encoded straight into the reusable scratch of the function in the
56
+ fast path, instead of retrying the conversion in the general path (three
57
+ partial copies before the complete one). Strings of 600 bytes are about 30%
58
+ faster, of 4 KB about 10-15%.
59
+ - **Faster pointer arguments**: each pointer position remembers the kind of
60
+ value it received last (BigInt, Number, `null`/`undefined`, or a buffer for
61
+ `c_char_p`) and reads that kind first, with one call to V8 instead of three;
62
+ another kind takes the full conversion as before. An address passed as a
63
+ BigInt or a Number is about 15-20% faster, `null` 5-10%.
64
+ - **Faster callbacks**: up to 64 callbacks running inside one synchronous call
65
+ reuse its handle scope instead of opening one each (`napi_open_handle_scope`
66
+ allocates); numeric results are converted with one read; after a callback,
67
+ only the arguments that are JavaScript memory are checked for detachment.
68
+
69
+ ### Fixed
70
+
71
+ - **gcc `-Wstringop-overread` warning** in the conversion of callback results:
72
+ the helper that widens a narrow integer result was also instantiated for the
73
+ types that fill the whole return word, and gcc 13 saw a read past the end of
74
+ the value. Narrow results now have their own helper
75
+ (`StoreNarrowIntegerValue`).
76
+ - **Flaky Executor test**: the coalescing test counted deliveries while the
77
+ executor thread was still completing the burst, so a loaded machine produced
78
+ more deliveries without any defect. Each call of the burst now marks its own
79
+ byte and the JavaScript thread waits for every mark before yielding; the test
80
+ fails with one delivery per call when coalescing is disabled.
81
+ - README: the Koffi version approved for the comparison benchmarks is 3.3.8.
82
+
83
+ ### Added
84
+
85
+ - README: an `Executor` for many short calls kept in flight, with the reasons
86
+ and the limits (one call at a time).
87
+ - Regression tests: many and nested callbacks in one call, out-of-range and
88
+ non-finite Number results of integer callbacks, pointer arguments whose kind
89
+ of value changes between calls, `_as_parameter_` adapters of structure
90
+ arguments read once with their errors normalized, assignment and `delete` of
91
+ library attributes, attribute functions with `use_last_error`, strings
92
+ that fill the inline buffer followed by any `c_char_p` value, and results
93
+ that point into long string arguments (with `errcheck` and reentrant
94
+ calls); test fixture function `fixture_string_lengths_nullable`.
95
+
96
+ ## [2.12.2] - 2026-11-11
97
+
98
+ ### Fixed
99
+
100
+ - **`callOn` target lost during reentrant conversions**: the executor of a
101
+ call was passed as ambient state just before `callAsync`; an argument
102
+ adapter (`from_param`) that made another `callOn` overwrote and cleared it,
103
+ and the outer call ran on the libuv pool. Each invocation now passes its own
104
+ call object down to the native call (`FFIFunction.callOn`), also when an
105
+ adapter calls the same function.
106
+ - **Cancellation of the wrong call**: the id of the call to cancel was read
107
+ from the executor after the call returned; after an inline completion its
108
+ errcheck may have queued other calls, and aborting the signal cancelled one
109
+ of those. The native call now writes the id of its own job into the call
110
+ object.
111
+ - **Abort during argument preparation ignored**: a signal aborted by an
112
+ argument adapter was checked before the conversions and listened to only
113
+ after submission, so the call ran. The native call checks the signal after
114
+ preparing the arguments and before queuing the call, and rejects with
115
+ `signal.reason` without running it.
116
+
117
+ ### Changed
118
+
119
+ - **Coalesced completion notifications**: the executor thread notified the
120
+ JavaScript thread once per completed call, while each delivery takes all the
121
+ completed calls: in a burst most deliveries found nothing to do (10,000
122
+ deliveries for 10,000 calls with `spin: 0`, all the promises settled by the
123
+ first). It now notifies only when no delivery is pending (1 delivery in the
124
+ same burst). Short calls cost about 25% less (sequential awaited calls about
125
+ 2.7 µs instead of 3.6 µs, bursts 2.4 µs instead of 3.2 µs, with a signal
126
+ 4.0 µs instead of 4.9 µs, locally on Windows x64).
127
+
128
+ ### Added
129
+
130
+ - Regression tests for the three defects (thread identity of the call, nested
131
+ calls on another executor and on the same function, cancellation after an
132
+ inline completion, abort during preparation) and for the coalesced
133
+ notifications; test fixture function `fixture_current_thread`.
134
+
10
135
  ## [2.12.1] - 2026-11-11
11
136
 
12
137
  ### Changed
@@ -1271,7 +1396,9 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
1271
1396
 
1272
1397
  Initial releases.
1273
1398
 
1274
- [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.12.1...HEAD
1399
+ [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.13.0...HEAD
1400
+ [2.13.0]: https://github.com/dmazzella/node-ctypes/compare/v2.12.2...v2.13.0
1401
+ [2.12.2]: https://github.com/dmazzella/node-ctypes/compare/v2.12.1...v2.12.2
1275
1402
  [2.12.1]: https://github.com/dmazzella/node-ctypes/compare/v2.12.0...v2.12.1
1276
1403
  [2.12.0]: https://github.com/dmazzella/node-ctypes/compare/v2.11.1...v2.12.0
1277
1404
  [2.11.1]: https://github.com/dmazzella/node-ctypes/compare/v2.11.0...v2.11.1
package/README.md CHANGED
@@ -153,6 +153,16 @@ await executor.close(); // waits for the accepted calls, then stops the thread
153
153
  - Callbacks invoked during the call run on the executor thread: use
154
154
  `threadSafeCallback`, as with `callAsync`.
155
155
 
156
+ An `Executor` also suits many short calls kept in flight. Each `callAsync()`
157
+ queues its own libuv work item, which wakes a worker, and completes
158
+ separately; the executor thread takes the next queued call without being
159
+ woken and delivers the completed calls to JavaScript together. With several
160
+ calls in flight this usually costs less than `callAsync()`: about a third on
161
+ Windows, where waking a thread is expensive, less of a difference elsewhere.
162
+ The calls then run one at a time: for short calls that is usually faster than
163
+ spreading them over the libuv workers, but blocking calls that must overlap
164
+ still need `callAsync()` or one executor each.
165
+
156
166
  ### Structs, unions, bit fields, arrays
157
167
 
158
168
  ```javascript
@@ -995,7 +1005,7 @@ Each example in `examples/` has its own README; see the [index](examples/README.
995
1005
  - [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
996
1006
  - [Accessibility](examples/macos/accessibility/README.md) — macOS UI automation with the Accessibility API
997
1007
  - [COM automation](examples/windows/com/README.md) — shell shortcuts (`IShellLinkW`) and Active Directory (`IDirectorySearch`)
998
- - [Controls](examples/windows/controls/README.md) — Win32 common controls
1008
+ - [Controls](examples/windows/controls/README.md) — a small Win32 application with the common controls
999
1009
  - [LDAP](examples/windows/ldap/README.md) — LDAPv3 paged search (`wldap32`)
1000
1010
  - [Registry](examples/windows/registry/README.md) — `setValue` / `getValue` / `openKey` / `deleteKey`
1001
1011
  - [System tray](examples/windows/tray/README.md) — tray icon + popup menu
@@ -1048,7 +1058,7 @@ npm run bench:koffi # node-ctypes vs Koffi; Node 24+
1048
1058
  npm run bench:ffi # node-ctypes vs node:ffi; Node 26+
1049
1059
  ```
1050
1060
 
1051
- The private test package explicitly approves the install script for Koffi 3.3.3.
1061
+ The private test package explicitly approves the install script for Koffi 3.3.8.
1052
1062
  When upgrading Koffi, review the new version before updating that approval with
1053
1063
  `npm --prefix tests install-scripts approve koffi`; future versions are not
1054
1064
  automatically authorized.
@@ -1139,14 +1149,27 @@ functional/parity test suite.
1139
1149
 
1140
1150
  ### Native backends and upstream libffi
1141
1151
 
1142
- The maintained outgoing paths are the bounded C++ direct invokers and libffi.
1143
- Callbacks use libffi closures and the shared Node-API bridge. The source tree
1144
- stays flat, with backend-specific files prefixed where needed:
1152
+ The maintained outgoing paths are the bounded C++ direct invokers, register-frame
1153
+ calls and libffi. Register-frame calls cover any signature of scalars, pointers
1154
+ and strings up to 32 arguments on AArch64, x86-64 System V and Win64: each
1155
+ argument is converted straight into its register or stack word, and one C++
1156
+ signature per ABI passes the whole frame (on Apple ARM64 the stack arguments
1157
+ are packed by size and natural alignment, as the platform ABI requires).
1158
+ libffi remains for aggregates, other calling conventions
1159
+ and the remaining cases. `CDLL.func()` and prototype calls return the native
1160
+ function itself when the arguments need no JavaScript conversion (scalars,
1161
+ `c_char_p` strings), as Koffi does; objects, `errcheck` and the other
1162
+ signatures are forwarded to the JavaScript converters.
1163
+ Callbacks use libffi closures and the shared Node-API bridge; up to 64 callbacks
1164
+ running inside one synchronous call reuse its handle scope instead of opening
1165
+ their own. The source tree stays flat, with backend-specific files prefixed
1166
+ where needed:
1145
1167
 
1146
1168
  | Files | Responsibility |
1147
1169
  | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
1148
1170
  | [call_abi.h](./src/call_abi.h), [types.h](./src/types.h) | Shared calling conventions, ABI return words and scalar conversions, without libffi headers |
1149
1171
  | [direct_call.h](./src/direct_call.h) | Exact fixed-signature C++ invokers |
1172
+ | [frame_call.h](./src/frame_call.h) | Register-frame calls: argument placement per ABI and one C++ signature per return type |
1150
1173
  | [libffi_types.cc](./src/libffi_types.cc), [libffi_types.h](./src/libffi_types.h) | Primitive mapping and aggregate descriptor factories |
1151
1174
  | [libffi_type_cache.h](./src/libffi_type_cache.h) | Concrete owned aggregate cache used by layout metadata |
1152
1175
  | [libffi_call.cc](./src/libffi_call.cc), [libffi_call.h](./src/libffi_call.h) | Calling conventions, CIFs, reusable plans and worker-owned extra-call interfaces |
@@ -1195,8 +1218,9 @@ libffi, independently of the Node wrapper. Avoid this signature until an upstrea
1195
1218
  fix is available. Its regression is temporarily skipped only on Windows ARM64
1196
1219
  and still runs on other targets. Native calling behavior is unchanged.
1197
1220
 
1198
- `CTYPES_ENABLE_DIRECT_CALLS` remains a build-time control, default ON. Fixed
1199
- direct calls and workers need no CIF; unsupported fixed signatures use libffi,
1221
+ `CTYPES_ENABLE_DIRECT_CALLS` remains a build-time control, default ON, for both
1222
+ the direct invokers and the register-frame calls. Fixed direct calls and workers
1223
+ need no CIF; unsupported fixed signatures use libffi,
1200
1224
  and async inferred/variadic calls own CIFs prepared on the JavaScript thread.
1201
1225
  Workers retain the parent function, metadata and library through completion.
1202
1226
  To compare the direct-enabled and libffi-only builds, follow the
Binary file
Binary file
@@ -57,6 +57,10 @@ import { callOn } from "./executor.js";
57
57
  */
58
58
  export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNativeTypes, native) {
59
59
  const typeKey = createTypeKey();
60
+ // Captured at load so calls are not affected by later patches.
61
+ const reflectApply = Reflect.apply;
62
+ // Library Proxy -> the CDLL instance behind it.
63
+ const libraryTargets = new WeakMap();
60
64
  // Funzione passata a errcheck quando la chiamata passa da un attributo
61
65
  // della libreria (FunctionWrapper).
62
66
  const kErrcheckFunc = Symbol("errcheckFunc");
@@ -97,9 +101,16 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
97
101
  return cachedFunc;
98
102
  };
99
103
 
100
- // Funzione semplice con accessor invece di un Proxy: ogni chiamata
101
- // attraverso un Proxy costava ~20 ns in più.
102
- const func = (...args) => (cachedFunc ?? resolve())(...args);
104
+ // A plain function with accessors instead of a Proxy: each call through
105
+ // a Proxy cost ~20 ns more. The arguments are forwarded as `arguments`,
106
+ // without the array of (...args): called as `lib.name(...)` (through the
107
+ // library's Proxy) V8 does not inline it and the array cost ~60 ns. A
108
+ // method, like an arrow function, is not a constructor.
109
+ const { func } = {
110
+ func() {
111
+ return reflectApply(cachedFunc ?? resolve(), undefined, arguments);
112
+ },
113
+ };
103
114
 
104
115
  Object.defineProperties(func, {
105
116
  address: { get: () => resolve().address },
@@ -149,6 +160,10 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
149
160
  set: () => {},
150
161
  configurable: true,
151
162
  },
163
+ _callOn: {
164
+ get: () => resolve()._callOn,
165
+ configurable: true,
166
+ },
152
167
  });
153
168
 
154
169
  return func;
@@ -178,23 +193,41 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
178
193
  this._use_errno = !!options.use_errno;
179
194
 
180
195
  // Return a proxy to enable Python-like syntax: libc.abs.argtypes = [...]; libc.abs.restype = ...; libc.abs(...)
181
- return new Proxy(this, {
196
+ const wrappers = this._funcWrapperCache;
197
+ const proxy = new Proxy(this, {
182
198
  get(target, prop, receiver) {
199
+ // A function already looked up comes first, as in Python, where
200
+ // __getattr__ stores it on the instance: one Map lookup instead of
201
+ // the `in` walk of the prototype chain, which misses for functions.
202
+ if (typeof prop === "string") {
203
+ const cached = wrappers.get(prop);
204
+ if (cached !== undefined) {
205
+ return cached;
206
+ }
207
+ }
183
208
  // Allow access to existing properties/methods
184
209
  if (prop in target || typeof prop !== "string") {
185
210
  return Reflect.get(target, prop, receiver);
186
211
  }
187
- // Check if we already have a FunctionWrapper for this function name
188
- const cached = target._funcWrapperCache.get(prop);
189
- if (cached !== undefined) {
190
- return cached;
191
- }
192
212
  // Create and cache a new FunctionWrapper
193
213
  const wrapper = new FunctionWrapper(target, prop);
194
- target._funcWrapperCache.set(prop, wrapper);
214
+ wrappers.set(prop, wrapper);
195
215
  return wrapper;
196
216
  },
217
+ // As in Python, a property set later with the name of a function
218
+ // replaces it, and `delete lib.name` forgets the function: the next
219
+ // access creates a new one.
220
+ defineProperty(target, prop, descriptor) {
221
+ wrappers.delete(prop);
222
+ return Reflect.defineProperty(target, prop, descriptor);
223
+ },
224
+ deleteProperty(target, prop) {
225
+ wrappers.delete(prop);
226
+ return Reflect.deleteProperty(target, prop);
227
+ },
197
228
  });
229
+ libraryTargets.set(proxy, this);
230
+ return proxy;
198
231
  }
199
232
 
200
233
  /**
@@ -259,12 +292,12 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
259
292
  const captureHere = convertResult === undefined;
260
293
  const callState = { errcheck: null };
261
294
  let checkedSync;
262
- const checkedCall = (method, args, checked) => {
295
+ const checkedCall = (method, args, checked, target) => {
263
296
  const originalArgs = Array.isArray(args) ? args : Array.prototype.slice.call(args);
264
297
  const func = errcheckFunc();
265
298
  const finish = (result) => checked(convertResult === undefined ? result : convertResult(result), func, originalArgs);
266
299
  const call = method === "call" ? (checkedSync ??= ffiFunc._makeCheckedCall()) : undefined;
267
- return callWithResultHandler(ffiFunc, method, originalArgs, C, finish, hasAdapters || argumentsNeedOwners(originalArgs), call);
300
+ return callWithResultHandler(ffiFunc, method, originalArgs, C, finish, hasAdapters || argumentsNeedOwners(originalArgs), call, target);
268
301
  };
269
302
  const ownedCall = (method, args) => callWithArgumentOwners(ffiFunc, method, args, C);
270
303
  const invoke = (method, args, checked) => {
@@ -274,6 +307,12 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
274
307
 
275
308
  let callMethod = specializeCall(ffiFunc, "call", C, callState, (args, checked) => invoke("call", args, checked), captureHere);
276
309
  let asyncCallMethod = specializeCall(ffiFunc, "callAsync", C, callState, (args, checked) => invoke("callAsync", args, checked), captureHere);
310
+ // callOn(): the same call on the Executor of `target` (this invocation's own).
311
+ let onExecutor = (target, args) => {
312
+ if (captureHere && callState.errcheck !== null) return checkedCall("callAsync", args, callState.errcheck, target);
313
+ if (captureHere && (hasAdapters || argumentsNeedOwners(args))) return callWithArgumentOwners(ffiFunc, "callAsync", args, C, undefined, undefined, undefined, target);
314
+ return ffiFunc.callOn(target, ...convertAll(args));
315
+ };
277
316
 
278
317
  // Result handlers run inside the native call scope, after conversion and
279
318
  // with the hook/arguments captured before any argument adapter executes.
@@ -291,12 +330,19 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
291
330
  if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, C, finish);
292
331
  return rawAsync.apply(this, args).then((result) => finish(result, args));
293
332
  };
333
+ const rawOn = onExecutor;
334
+ onExecutor = (target, args) => {
335
+ if (callState.errcheck !== null) return checkedCall("callAsync", args, callState.errcheck, target);
336
+ if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, C, finish, undefined, undefined, target);
337
+ return rawOn(target, args).then((result) => finish(result, args));
338
+ };
294
339
  }
295
340
 
296
341
  // If use_last_error / use_errno is set on the library, wrap callMethod
297
342
  // so the most-recently-called FFIFunction is remembered on the library.
298
343
  if (this._use_last_error || this._use_errno) {
299
- const self = this;
344
+ // The library itself, not its Proxy: this write runs on every call.
345
+ const self = libraryTargets.get(this) ?? this;
300
346
  const origCall = callMethod;
301
347
  callMethod = function (...args) {
302
348
  self._lastCalledFfi = ffiFunc;
@@ -307,20 +353,37 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
307
353
  self._lastCalledFfi = ffiFunc;
308
354
  return origAsync.apply(this, args);
309
355
  };
356
+ const origOn = onExecutor;
357
+ onExecutor = (target, args) => {
358
+ self._lastCalledFfi = ffiFunc;
359
+ return origOn(target, args);
360
+ };
361
+ }
362
+
363
+ // La funzione restituita: come in Koffi, la funzione nativa stessa
364
+ // (_makeEntry) quando gli argomenti che il JavaScript non converte
365
+ // (primitivi per i parametri scalari, stringhe per c_char_p) bastano.
366
+ // Le altre chiamate (oggetti, errcheck) vanno a callMethod con gli
367
+ // stessi argomenti. Senza il wrapper JS il call site resta monomorfico:
368
+ // le closure di specializeCall condividono il feedback di V8.
369
+ let exposed = callMethod;
370
+ if (convertResult === undefined && !hasAdapters && !this._use_last_error && !this._use_errno && C.every((convert) => convert.passesPrimitives === true || convert.passesStrings === true)) {
371
+ exposed = ffiFunc._makeEntry(callMethod, name) ?? callMethod;
310
372
  }
311
373
 
312
374
  // Python: errcheck riceve la funzione su cui è impostato (l'attributo
313
375
  // della libreria, se passa da lì), qualunque sia il restype.
314
- const errcheckFunc = () => callMethod[kErrcheckFunc] ?? callMethod;
376
+ const errcheckFunc = () => exposed[kErrcheckFunc] ?? exposed;
315
377
 
316
378
  // Aggiungi metadata come proprietà non-enumerable per non interferire
317
- Object.defineProperties(callMethod, {
379
+ Object.defineProperties(exposed, {
318
380
  funcName: { value: name },
319
381
  address: { value: ffiFunc.address },
320
382
  _as_parameter_: { value: ffiFunc.address },
321
383
  _ffi: { value: ffiFunc },
322
384
  callAsync: { value: asyncCallMethod, writable: false, enumerable: false, configurable: false },
323
- callOn: { value: (target, ...args) => callOn(callMethod, target, args), writable: false, enumerable: false, configurable: false },
385
+ callOn: { value: (target, ...args) => callOn(exposed, target, args), writable: false, enumerable: false, configurable: false },
386
+ _callOn: { value: onExecutor },
324
387
  // Esponi errcheck come setter/getter
325
388
  errcheck: {
326
389
  get() {
@@ -330,13 +393,15 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
330
393
  callback = callback ?? null;
331
394
  if (callback !== null && typeof callback !== "function") throw new TypeError("errcheck must be a function or null");
332
395
  callState.errcheck = callback;
396
+ // Con errcheck la funzione nativa passa ogni chiamata al wrapper JS.
397
+ if (exposed !== callMethod) ffiFunc._setEntryDefer(callback !== null);
333
398
  },
334
399
  enumerable: false,
335
400
  configurable: true,
336
401
  },
337
402
  });
338
403
 
339
- return callMethod;
404
+ return exposed;
340
405
  }
341
406
 
342
407
  /**
@@ -50,6 +50,7 @@ export function specializeCall(ffiFunc, method, converters, state, invoke, captu
50
50
  const [C0, C1, C2, C3, C4, C5] = converters;
51
51
  const [N0, N1, N2, N3, N4, N5] = converters.map((convert) => convert.needsOwners ?? needsArgumentOwners);
52
52
  const hasAdapters = converters.some((convert) => convert.requiresOwners);
53
+ const primitivesPass = converters.every((convert) => convert.passesPrimitives === true);
53
54
  const sync = method !== "callAsync";
54
55
  switch (converters.length) {
55
56
  case 0:
@@ -101,9 +102,22 @@ export function specializeCall(ffiFunc, method, converters, state, invoke, captu
101
102
  return ffiFunc[method](C0(a0), C1(a1), C2(a2), C3(a3), C4(a4), C5(a5));
102
103
  };
103
104
  default:
104
- return function (...args) {
105
+ return function () {
105
106
  const checked = captureHere ? state.errcheck : null;
106
- return invoke(args, checked);
107
+ // Scalar parameters receiving primitives need no conversion and no
108
+ // owners: the arguments object goes to the native call as it is.
109
+ if (primitivesPass && checked === null && arguments.length === converters.length) {
110
+ let primitive = true;
111
+ for (let i = 0; i < arguments.length; i++) {
112
+ const value = arguments[i];
113
+ if (value !== null && (typeof value === "object" || typeof value === "function")) {
114
+ primitive = false;
115
+ break;
116
+ }
117
+ }
118
+ if (primitive) return reflectApply(ffiFunc[method], ffiFunc, arguments);
119
+ }
120
+ return invoke(arguments, checked);
107
121
  };
108
122
  }
109
123
  }
@@ -140,15 +154,29 @@ function callOwned3(ffiFunc, method, C0, C1, C2, a0, a1, a2) {
140
154
  }
141
155
  }
142
156
 
157
+ // The native asynchronous entry: on the Executor of `call` (callOn: the
158
+ // target of this invocation only) or, without it, on the libuv pool.
159
+ function invokeAsync(ffiFunc, call, resultHandler, converted) {
160
+ if (call === undefined) return resultHandler === undefined ? ffiFunc.callAsync(...converted) : ffiFunc._callAsyncWithErrcheck(resultHandler, ...converted);
161
+ return resultHandler === undefined ? ffiFunc.callOn(call, ...converted) : ffiFunc._callOnWithErrcheck(call, resultHandler, ...converted);
162
+ }
163
+
143
164
  // The registry is a GC root, including while another converter reenters JS.
144
- export function callWithArgumentOwners(ffiFunc, method, args, converters, finish, resultHandler, checkedCall) {
165
+ // `call`: the callOn target of an asynchronous call.
166
+ export function callWithArgumentOwners(ffiFunc, method, args, converters, finish, resultHandler, checkedCall, call) {
145
167
  const owners = [];
146
168
  // Synchronous calls nest strictly, so a stack avoids hashing a fresh array.
147
169
  activeOwnerStack.push(owners);
148
170
  try {
149
171
  const converted = convertArguments(args, converters, owners);
150
172
  const result =
151
- resultHandler === undefined ? ffiFunc[method](...converted) : checkedCall === undefined ? ffiFunc[method === "callAsync" ? "_callAsyncWithErrcheck" : "_callWithErrcheck"](resultHandler, ...converted) : checkedCall(resultHandler, ...converted);
173
+ method === "callAsync"
174
+ ? invokeAsync(ffiFunc, call, resultHandler, converted)
175
+ : resultHandler === undefined
176
+ ? ffiFunc[method](...converted)
177
+ : checkedCall === undefined
178
+ ? ffiFunc._callWithErrcheck(resultHandler, ...converted)
179
+ : checkedCall(resultHandler, ...converted);
152
180
  if (method === "callAsync") {
153
181
  const completed = finish === undefined ? result : result.then((value) => finish(value, args));
154
182
  activeArgumentOwners.add(owners);
@@ -160,10 +188,11 @@ export function callWithArgumentOwners(ffiFunc, method, args, converters, finish
160
188
  }
161
189
  }
162
190
 
163
- export function callWithResultHandler(ffiFunc, method, args, converters, handler, retainOwners, checkedCall) {
164
- if (retainOwners) return callWithArgumentOwners(ffiFunc, method, args, converters, undefined, handler, checkedCall);
191
+ export function callWithResultHandler(ffiFunc, method, args, converters, handler, retainOwners, checkedCall, call) {
192
+ if (retainOwners) return callWithArgumentOwners(ffiFunc, method, args, converters, undefined, handler, checkedCall, call);
165
193
  if (checkedCall !== undefined) return checkedCall(handler, ...convertArguments(args, converters));
166
- return ffiFunc[method === "callAsync" ? "_callAsyncWithErrcheck" : "_callWithErrcheck"](handler, ...convertArguments(args, converters));
194
+ if (method === "callAsync") return invokeAsync(ffiFunc, call, handler, convertArguments(args, converters));
195
+ return ffiFunc._callWithErrcheck(handler, ...convertArguments(args, converters));
167
196
  }
168
197
 
169
198
  /**
@@ -225,9 +254,20 @@ const isStructType = (t) => t !== null && (typeof t === "function" || typeof t =
225
254
  * An array is rejected, as a Python tuple.
226
255
  */
227
256
  function structArgument(T, index) {
228
- const instance = typeof T === "function" ? (values) => new T(values) : (structArgumentFactories.get(T) ?? ((values) => T.create(values)));
257
+ const factory = typeof T === "function" ? undefined : structArgumentFactories.get(T);
258
+ const instance = typeof T === "function" ? (values) => new T(values) : (factory ?? ((values) => T.create(values)));
229
259
  const coerce = mirrorsActive ? coerceStructValue : coerceObject;
260
+ // The functional struct factory returns its fresh Buffer unconverted.
261
+ const build = factory !== undefined && !mirrorsActive ? (values, owners) => factory(values, coerce, owners) : (values, owners) => coerce(instance(values), owners);
230
262
  const convert = (a, owners) => {
263
+ // A plain object of field values, the common case, skips the generic
264
+ // parameter probes: only `_as_parameter_` and `_buffer` change its meaning.
265
+ // Their presence is tested without reading them, so an adapter getter runs
266
+ // once, in resolveArgument, with its errors normalized there.
267
+ if (a !== null && typeof a === "object" && Object.getPrototypeOf(a) === Object.prototype && !("_as_parameter_" in a) && !("_buffer" in a)) {
268
+ retainArgument(owners, a);
269
+ return build(a, owners);
270
+ }
231
271
  a = resolveArgument(a, owners, index);
232
272
  retainArgument(owners, a);
233
273
  if (Array.isArray(a)) {
@@ -362,6 +402,9 @@ function stringArgument(T, kind, index, native) {
362
402
  return objectMemory(value, owners);
363
403
  },
364
404
  });
405
+ // c_char_p: strings, null and undefined are returned unchanged (the native
406
+ // entry function converts them itself, see Library._createFunction).
407
+ if (!wide) Object.defineProperty(convert, "passesStrings", { value: true });
365
408
  return convert;
366
409
  }
367
410
 
@@ -394,6 +437,8 @@ function scalarArgument(T, kind, index) {
394
437
  };
395
438
  const convert = make(false);
396
439
  Object.defineProperty(convert, "fromParam", { value: make(true) });
440
+ // A primitive value (not an object or a function) is returned unchanged.
441
+ Object.defineProperty(convert, "passesPrimitives", { value: true });
397
442
  return convert;
398
443
  }
399
444
 
@@ -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
- const resultHandler = (result) => checked(finish(result), callMethod, originalArgs);
332
+ const resultHandler = (result) => checked(finish(result), exposed, 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;
@@ -391,7 +411,14 @@ function createFuncPtrType(native, typeName, abi) {
391
411
  },
392
412
  };
393
413
  }
394
- Object.defineProperties(callMethod, {
414
+ // As CDLL.func: the native entry function when the arguments that the
415
+ // JavaScript does not convert are enough (see Library._createFunction);
416
+ // not for a JS callback, whose calls are counted here.
417
+ let exposed = callMethod;
418
+ if (callback === undefined && convertResult === undefined && !hasAdapters && converters.every((convert) => convert.passesPrimitives === true || convert.passesStrings === true)) {
419
+ exposed = ffiFunc._makeEntry(callMethod) ?? callMethod;
420
+ }
421
+ Object.defineProperties(exposed, {
395
422
  ...callbackProperties,
396
423
  name: { value: "callMethod", configurable: true },
397
424
  length: { value: 0, configurable: true },
@@ -406,11 +433,12 @@ function createFuncPtrType(native, typeName, abi) {
406
433
  configurable: false,
407
434
  },
408
435
  callOn: {
409
- value: (target, ...args) => callOn(callMethod, target, args),
436
+ value: (target, ...args) => callOn(exposed, target, args),
410
437
  writable: false,
411
438
  enumerable: false,
412
439
  configurable: false,
413
440
  },
441
+ _callOn: { value: callOnExecutor },
414
442
  errcheck: {
415
443
  get() {
416
444
  return callState.errcheck;
@@ -419,6 +447,7 @@ function createFuncPtrType(native, typeName, abi) {
419
447
  callback = callback ?? null;
420
448
  if (callback !== null && typeof callback !== "function") throw new TypeError("errcheck must be a function or null");
421
449
  callState.errcheck = callback;
450
+ if (exposed !== callMethod) ffiFunc._setEntryDefer(callback !== null);
422
451
  },
423
452
  enumerable: false,
424
453
  configurable: true,
@@ -426,8 +455,8 @@ function createFuncPtrType(native, typeName, abi) {
426
455
  });
427
456
 
428
457
  if (callback !== undefined) keepFunctionOwner(callMethod, callback);
429
- prototypeOwners.set(callMethod, factory);
430
- return callMethod;
458
+ prototypeOwners.set(exposed, factory);
459
+ return exposed;
431
460
  }
432
461
 
433
462
  // Attach metadata + paramflags binding to the factory
@@ -710,10 +710,15 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
710
710
  return buf;
711
711
  };
712
712
  const createFast = writers.every(([, write]) => typeof write === "function") ? createScalar : createBuffer;
713
- structArgumentFactories.set(structDef, (values) => {
713
+ // The Buffer built here is fresh and passed as is; with `convert` the
714
+ // result of a create override goes through it as any other argument.
715
+ structArgumentFactories.set(structDef, (values, convert, owners) => {
714
716
  // A later create override must still run, with the definition as receiver.
715
717
  const current = structDef.create;
716
- if (current !== create) return current.call(structDef, values);
718
+ if (current !== create) {
719
+ const value = current.call(structDef, values);
720
+ return convert === undefined ? value : convert(value, owners);
721
+ }
717
722
  return structDef.set === set ? createFast(values) : createBuffer(values);
718
723
  });
719
724
  const toObject = structDef.toObject;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-ctypes",
3
- "version": "2.12.1",
3
+ "version": "2.13.0",
4
4
  "description": "Python ctypes-like FFI for Node.js using libffi",
5
5
  "author": "Damiano Mazzella",
6
6
  "license": "MIT",