node-ctypes 2.6.0 → 2.7.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,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.7.0] - 2026-11-03
11
+
12
+ ### Changed
13
+
14
+ - **Callback dispatch**: `callback()` and `threadSafeCallback()` invoke the
15
+ JavaScript handler directly, like CPython's `tp_call`. Own `call` or `apply`
16
+ properties on the handler are no longer consulted. The receiver stays
17
+ `undefined` and the handler gets exactly the declared arguments.
18
+ - **Callback wrappers as arguments**: a `callback()` / `threadSafeCallback()`
19
+ wrapper passes its own code pointer even through an object derived with
20
+ `Object.create()` or a Proxy that redefines `_as_parameter_`. This matches
21
+ CPython and `CFUNCTYPE` instances.
22
+
23
+ ### Performance
24
+
25
+ - **Native entry point**: `FFIFunction` calls use a raw Node-API callback that
26
+ reads up to eight arguments with one `napi_get_cb_info` and tries the simple
27
+ call path before building a `Napi::CallbackInfo`.
28
+ - **Structures by value**: plain-object arguments of scalar-only `struct()`
29
+ definitions are written by precompiled field writers into an off-heap
30
+ transient buffer. Structures up to 16 bytes use the simple call path. Scalar-only
31
+ results are read in place without a copy, unless `toObject` is overridden.
32
+ Measured `{x,y}` argument: about 1.3x Koffi, down from 4.3x. Return: about 0.9x,
33
+ down from 1.3x.
34
+ - **Argument owners**: synchronous calls keep conversion owners on a LIFO stack
35
+ instead of a `Set`. Calls with one to three owner-bearing arguments skip
36
+ intermediate arrays.
37
+ - **Callbacks**: wrappers are resolved through an internal brand. Handlers with
38
+ up to three arguments are called without a rest array. Numeric results are
39
+ converted with a single V8 read.
40
+ - **Variadic numbers**: classified and written to the argument slot with a
41
+ single read.
42
+
10
43
  ## [2.6.0] - 2026-10-30
11
44
 
12
45
  ### Added
@@ -1018,7 +1051,8 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
1018
1051
 
1019
1052
  Initial releases.
1020
1053
 
1021
- [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.6.0...HEAD
1054
+ [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.7.0...HEAD
1055
+ [2.7.0]: https://github.com/dmazzella/node-ctypes/compare/v2.6.0...v2.7.0
1022
1056
  [2.6.0]: https://github.com/dmazzella/node-ctypes/compare/v2.5.0...v2.6.0
1023
1057
  [2.5.0]: https://github.com/dmazzella/node-ctypes/compare/v2.4.0...v2.5.0
1024
1058
  [2.4.0]: https://github.com/dmazzella/node-ctypes/compare/v2.3.0...v2.4.0
Binary file
Binary file
@@ -56,6 +56,7 @@
56
56
  import { _toNativeReturnType, _toNativeTypes } from "./types.js";
57
57
  import { adaptCallbackFunction, scalarResult } from "./conversions.js";
58
58
  import { trackCallback } from "./callback-tracker.js";
59
+ import { callbackPointer } from "../structures/helpers/common.js";
59
60
 
60
61
  function nativeContextHook(value, name, owners) {
61
62
  if (value !== null && (typeof value === "object" || typeof value === "function")) {
@@ -196,6 +197,7 @@ export function callback(fn, returnType, argTypes = [], native, abi = undefined)
196
197
  return cb.pointer;
197
198
  },
198
199
  });
200
+ Object.defineProperty(wrapper, callbackPointer, { value: cb.pointer });
199
201
  return trackCallback(wrapper, fn, "callback");
200
202
  }
201
203
 
@@ -357,5 +359,6 @@ export function threadSafeCallback(fn, returnType, argTypes = [], native, option
357
359
  return cb.pointer;
358
360
  },
359
361
  });
362
+ Object.defineProperty(wrapper, callbackPointer, { value: cb.pointer });
360
363
  return trackCallback(wrapper, fn, "threadSafeCallback");
361
364
  }
@@ -10,9 +10,11 @@ import { mirrorAddress, mirrorsActive, refresh } from "../memory/mirror.js";
10
10
  import { ArgumentError } from "../platform/errors.js";
11
11
  import { encodeWide } from "../memory/buffer.js";
12
12
  import { buildWrapper } from "../structures/helpers/wrap.js";
13
- import { activeArgumentOwners as argumentOwnerRegistry, byrefOwners, isScalarSubclass, resolveParameter, scalarView, structArgumentFactories } from "../structures/helpers/common.js";
13
+ import { activeArgumentOwners as argumentOwnerRegistry, activeOwnerStack, byrefOwners, isScalarSubclass, resolveParameter, scalarView, structArgumentFactories, structResultReaders } from "../structures/helpers/common.js";
14
14
 
15
15
  const activeArgumentOwners = argumentOwnerRegistry;
16
+ // Captured at load so callback dispatch is not affected by later patches.
17
+ const reflectApply = Reflect.apply;
16
18
 
17
19
  function retainArgument(owners, value) {
18
20
  if (owners !== undefined && value !== null && (typeof value === "object" || typeof value === "function")) owners.push(value);
@@ -34,7 +36,9 @@ export function argumentsNeedOwners(args) {
34
36
  // The general fallback receives the hook snapshot taken before any owner probe.
35
37
  export function specializeCall(ffiFunc, method, converters, state, invoke, captureHere = true) {
36
38
  const [C0, C1, C2, C3, C4, C5] = converters;
39
+ const [N0, N1, N2, N3, N4, N5] = converters.map((convert) => convert.needsOwners ?? needsArgumentOwners);
37
40
  const hasAdapters = converters.some((convert) => convert.requiresOwners);
41
+ const sync = method !== "callAsync";
38
42
  switch (converters.length) {
39
43
  case 0:
40
44
  return function () {
@@ -46,43 +50,42 @@ export function specializeCall(ffiFunc, method, converters, state, invoke, captu
46
50
  return function (a0) {
47
51
  const checked = captureHere ? state.errcheck : null;
48
52
  if (checked !== null || arguments.length !== 1) return invoke(arguments, checked);
49
- if (captureHere && (hasAdapters || needsArgumentOwners(a0))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
53
+ if (captureHere && (hasAdapters || N0(a0))) return sync ? callOwned1(ffiFunc, method, C0, a0) : callWithArgumentOwners(ffiFunc, method, arguments, converters);
50
54
  return ffiFunc[method](C0(a0));
51
55
  };
52
56
  case 2:
53
57
  return function (a0, a1) {
54
58
  const checked = captureHere ? state.errcheck : null;
55
59
  if (checked !== null || arguments.length !== 2) return invoke(arguments, checked);
56
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
60
+ if (captureHere && (hasAdapters || N0(a0) || N1(a1))) return sync ? callOwned2(ffiFunc, method, C0, C1, a0, a1) : callWithArgumentOwners(ffiFunc, method, arguments, converters);
57
61
  return ffiFunc[method](C0(a0), C1(a1));
58
62
  };
59
63
  case 3:
60
64
  return function (a0, a1, a2) {
61
65
  const checked = captureHere ? state.errcheck : null;
62
66
  if (checked !== null || arguments.length !== 3) return invoke(arguments, checked);
63
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
67
+ if (captureHere && (hasAdapters || N0(a0) || N1(a1) || N2(a2))) return sync ? callOwned3(ffiFunc, method, C0, C1, C2, a0, a1, a2) : callWithArgumentOwners(ffiFunc, method, arguments, converters);
64
68
  return ffiFunc[method](C0(a0), C1(a1), C2(a2));
65
69
  };
66
70
  case 4:
67
71
  return function (a0, a1, a2, a3) {
68
72
  const checked = captureHere ? state.errcheck : null;
69
73
  if (checked !== null || arguments.length !== 4) return invoke(arguments, checked);
70
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2) || needsArgumentOwners(a3))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
74
+ if (captureHere && (hasAdapters || N0(a0) || N1(a1) || N2(a2) || N3(a3))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
71
75
  return ffiFunc[method](C0(a0), C1(a1), C2(a2), C3(a3));
72
76
  };
73
77
  case 5:
74
78
  return function (a0, a1, a2, a3, a4) {
75
79
  const checked = captureHere ? state.errcheck : null;
76
80
  if (checked !== null || arguments.length !== 5) return invoke(arguments, checked);
77
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2) || needsArgumentOwners(a3) || needsArgumentOwners(a4))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
81
+ if (captureHere && (hasAdapters || N0(a0) || N1(a1) || N2(a2) || N3(a3) || N4(a4))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
78
82
  return ffiFunc[method](C0(a0), C1(a1), C2(a2), C3(a3), C4(a4));
79
83
  };
80
84
  case 6:
81
85
  return function (a0, a1, a2, a3, a4, a5) {
82
86
  const checked = captureHere ? state.errcheck : null;
83
87
  if (checked !== null || arguments.length !== 6) return invoke(arguments, checked);
84
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2) || needsArgumentOwners(a3) || needsArgumentOwners(a4) || needsArgumentOwners(a5)))
85
- return callWithArgumentOwners(ffiFunc, method, arguments, converters);
88
+ if (captureHere && (hasAdapters || N0(a0) || N1(a1) || N2(a2) || N3(a3) || N4(a4) || N5(a5))) return callWithArgumentOwners(ffiFunc, method, arguments, converters);
86
89
  return ffiFunc[method](C0(a0), C1(a1), C2(a2), C3(a3), C4(a4), C5(a5));
87
90
  };
88
91
  default:
@@ -93,24 +96,55 @@ export function specializeCall(ffiFunc, method, converters, state, invoke, captu
93
96
  }
94
97
  }
95
98
 
99
+ // Synchronous owned calls nest strictly: the owners array is a stack entry
100
+ // and the converters run without an intermediate argument array.
101
+ function callOwned1(ffiFunc, method, C0, a0) {
102
+ const owners = [];
103
+ activeOwnerStack.push(owners);
104
+ try {
105
+ return ffiFunc[method](C0(a0, owners));
106
+ } finally {
107
+ activeOwnerStack.pop();
108
+ }
109
+ }
110
+
111
+ function callOwned2(ffiFunc, method, C0, C1, a0, a1) {
112
+ const owners = [];
113
+ activeOwnerStack.push(owners);
114
+ try {
115
+ return ffiFunc[method](C0(a0, owners), C1(a1, owners));
116
+ } finally {
117
+ activeOwnerStack.pop();
118
+ }
119
+ }
120
+
121
+ function callOwned3(ffiFunc, method, C0, C1, C2, a0, a1, a2) {
122
+ const owners = [];
123
+ activeOwnerStack.push(owners);
124
+ try {
125
+ return ffiFunc[method](C0(a0, owners), C1(a1, owners), C2(a2, owners));
126
+ } finally {
127
+ activeOwnerStack.pop();
128
+ }
129
+ }
130
+
96
131
  // The registry is a GC root, including while another converter reenters JS.
97
132
  export function callWithArgumentOwners(ffiFunc, method, args, converters, finish, resultHandler, checkedCall) {
98
133
  const owners = [];
99
- activeArgumentOwners.add(owners);
100
- let pending = false;
134
+ // Synchronous calls nest strictly, so a stack avoids hashing a fresh array.
135
+ activeOwnerStack.push(owners);
101
136
  try {
102
137
  const converted = convertArguments(args, converters, owners);
103
138
  const result =
104
139
  resultHandler === undefined ? ffiFunc[method](...converted) : checkedCall === undefined ? ffiFunc[method === "callAsync" ? "_callAsyncWithErrcheck" : "_callWithErrcheck"](resultHandler, ...converted) : checkedCall(resultHandler, ...converted);
105
140
  if (method === "callAsync") {
106
141
  const completed = finish === undefined ? result : result.then((value) => finish(value, args));
107
- const promise = completed.finally(() => activeArgumentOwners.delete(owners));
108
- pending = true;
109
- return promise;
142
+ activeArgumentOwners.add(owners);
143
+ return completed.finally(() => activeArgumentOwners.delete(owners));
110
144
  }
111
145
  return finish === undefined ? result : finish(result, args);
112
146
  } finally {
113
- if (!pending) activeArgumentOwners.delete(owners);
147
+ activeOwnerStack.pop();
114
148
  }
115
149
  }
116
150
 
@@ -181,7 +215,7 @@ const isStructType = (t) => t !== null && (typeof t === "function" || typeof t =
181
215
  function structArgument(T, index) {
182
216
  const instance = typeof T === "function" ? (values) => new T(values) : (structArgumentFactories.get(T) ?? ((values) => T.create(values)));
183
217
  const coerce = mirrorsActive ? coerceStructValue : coerceObject;
184
- return (a, owners) => {
218
+ const convert = (a, owners) => {
185
219
  a = resolveArgument(a, owners, index);
186
220
  retainArgument(owners, a);
187
221
  if (Array.isArray(a)) {
@@ -193,6 +227,10 @@ function structArgument(T, index) {
193
227
  }
194
228
  return coerce(a, owners);
195
229
  };
230
+ // A plain object of field values becomes a fresh Buffer passed directly to
231
+ // the call, so nothing else needs to stay reachable.
232
+ convert.needsOwners = (a) => needsArgumentOwners(a) && !(Object.getPrototypeOf(a) === Object.prototype && !("_buffer" in a) && !("_as_parameter_" in a));
233
+ return convert;
196
234
  }
197
235
 
198
236
  /**
@@ -494,7 +532,7 @@ export function resultConverter(restype) {
494
532
  return (r) => new restype(copyResultBytes(r));
495
533
  }
496
534
  if (restype !== null && typeof restype === "object" && restype._isStructType === true) {
497
- return (r) => restype.toObject(copyResultBytes(r));
535
+ return structResultReaders.get(restype) ?? ((r) => restype.toObject(copyResultBytes(r)));
498
536
  }
499
537
  return undefined;
500
538
  }
@@ -564,11 +602,23 @@ export function adaptCallbackFunction(fn, argTypes, returnType, native) {
564
602
  return result !== null && (typeof result === "object" || typeof result === "function") ? coerceValue(result) : result;
565
603
  };
566
604
  if (!hasScalars && !hasVariants && !hasPointers && !hasStructs) {
567
- return function (...args) {
568
- return convertResult(fn.apply(this, args));
569
- };
605
+ // The native trampoline passes exactly argTypes.length values with an
606
+ // undefined receiver. Like CPython (tp_call), the handler is invoked
607
+ // directly: own `call`/`apply` properties are not consulted.
608
+ switch (argTypes.length) {
609
+ case 0:
610
+ return () => convertResult(fn());
611
+ case 1:
612
+ return (a0) => convertResult(fn(a0));
613
+ case 2:
614
+ return (a0, a1) => convertResult(fn(a0, a1));
615
+ case 3:
616
+ return (a0, a1, a2) => convertResult(fn(a0, a1, a2));
617
+ default:
618
+ return (...args) => convertResult(reflectApply(fn, undefined, args));
619
+ }
570
620
  }
571
- return function (...args) {
621
+ return (...args) => {
572
622
  if (hasScalars) {
573
623
  for (let i = 0; i < scalarTypes.length; i++) {
574
624
  if (scalarTypes[i] !== null) args[i] = scalarView(scalarTypes[i], args[i]);
@@ -592,7 +642,7 @@ export function adaptCallbackFunction(fn, argTypes, returnType, native) {
592
642
  if (structViews[i] !== null) args[i] = structViews[i](args[i]);
593
643
  }
594
644
  }
595
- return convertResult(fn.apply(this, args));
645
+ return convertResult(reflectApply(fn, undefined, args));
596
646
  };
597
647
  }
598
648
 
@@ -70,6 +70,30 @@ export function alloc(size) {
70
70
  return Buffer.alloc(size);
71
71
  }
72
72
 
73
+ const kTransientPoolSize = 8192;
74
+ let transientPool = new ArrayBuffer(kTransientPoolSize);
75
+ let transientOffset = 0;
76
+
77
+ /**
78
+ * Zero-filled buffer for a value that only lives for one native call. A small
79
+ * Buffer.alloc lives on the V8 heap and must be externalized when native code
80
+ * reads it; slices of an off-heap pool avoid that. Slices are never reused, so
81
+ * a fresh pool is already zeroed.
82
+ *
83
+ * @param {number} size - Size in bytes to allocate
84
+ * @returns {Buffer} Zero-initialized buffer
85
+ */
86
+ export function allocTransient(size) {
87
+ if (size > kTransientPoolSize >>> 2) return Buffer.alloc(size);
88
+ if (transientOffset + size > kTransientPoolSize) {
89
+ transientPool = new ArrayBuffer(kTransientPoolSize);
90
+ transientOffset = 0;
91
+ }
92
+ const buf = Buffer.from(transientPool, transientOffset, size);
93
+ transientOffset += (size + 7) & ~7;
94
+ return buf;
95
+ }
96
+
73
97
  /**
74
98
  * Creates a buffer containing a null-terminated C string.
75
99
  *
@@ -3,11 +3,22 @@ import { POINTER_SIZE } from "../../platform/constants.js";
3
3
 
4
4
  const simpleTypes = new WeakSet();
5
5
  export const activeArgumentOwners = new Set();
6
+ // GC roots of in-progress synchronous conversions, released in LIFO order.
7
+ export const activeOwnerStack = [];
6
8
  export const byrefOwners = new WeakMap();
7
9
  export const structArgumentFactories = new WeakMap();
10
+ export const structResultReaders = new WeakMap();
11
+ // Brand of callback wrappers: their constant pointer (the `_as_parameter_`
12
+ // value), read without the generic parameter probes.
13
+ export const callbackPointer = Symbol("callbackPointer");
8
14
 
9
15
  export function resolveParameter(value, owners) {
10
16
  if (value === null || (typeof value !== "object" && typeof value !== "function")) return value;
17
+ const pointer = value[callbackPointer];
18
+ if (pointer !== undefined) {
19
+ if (owners !== undefined) owners.push(value);
20
+ return pointer;
21
+ }
11
22
  if (owners !== undefined) owners.push(value);
12
23
  if (ArrayBuffer.isView(value) && !("_as_parameter_" in value)) return value;
13
24
  if (value._isSimpleCDataInstance === true || value._pointerType !== undefined || value._arrayType !== undefined || value._structDef !== undefined || byrefOwners.has(value)) return value;
@@ -18,11 +29,11 @@ export function resolveParameter(value, owners) {
18
29
 
19
30
  // Resolver-only memory operations also retain parents while nested getters can collect.
20
31
  const retained = [value];
21
- activeArgumentOwners.add(retained);
32
+ activeOwnerStack.push(retained);
22
33
  try {
23
34
  return resolveParameter(parameter, retained);
24
35
  } finally {
25
- activeArgumentOwners.delete(retained);
36
+ activeOwnerStack.pop();
26
37
  }
27
38
  }
28
39
 
@@ -37,7 +37,8 @@ import { bitFieldAccessors } from "./bitfield.js";
37
37
  import { computeLayout, isGccLayout, normalizePack } from "./layout.js";
38
38
  import { buildWrapper } from "./wrap.js";
39
39
  import { isMirror, syncDefinition } from "../../memory/mirror.js";
40
- import { copyInstance, fieldEntries, fieldsOf, funcPtrFieldType, isScalarSubclass, pointerOwner, scalarReader, simpleFieldWriter, structArgumentFactories, writePointerField } from "./common.js";
40
+ import { allocTransient } from "../../memory/buffer.js";
41
+ import { copyInstance, fieldEntries, fieldsOf, funcPtrFieldType, isScalarSubclass, pointerOwner, scalarReader, simpleFieldWriter, structArgumentFactories, structResultReaders, writePointerField } from "./common.js";
41
42
 
42
43
  /**
43
44
  * Creates a struct type definition with proper alignment and padding.
@@ -695,11 +696,41 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
695
696
 
696
697
  if (fieldDefs.every((field) => !field.isBitField && !field.isNested && !field.isArray && !field.isPointer && !field.type._isPointerValued && !isScalarSubclass(field.type))) {
697
698
  const create = structDef.create;
699
+ const set = structDef.set;
700
+ // Only scalar fields: `set` would resolve each name to its precompiled writer.
701
+ const writers = fieldDefs.map((field) => [field.name, fieldWriters[field.name]]);
702
+ const createScalar = (values) => {
703
+ const buf = allocTransient(totalSize);
704
+ for (let i = 0; i < writers.length; i++) {
705
+ const [name, write] = writers[i];
706
+ if (!Object.hasOwn(values, name)) continue;
707
+ const value = values[name];
708
+ if (value !== undefined) write(buf, value);
709
+ }
710
+ return buf;
711
+ };
712
+ const createFast = writers.every(([, write]) => typeof write === "function") ? createScalar : createBuffer;
698
713
  structArgumentFactories.set(structDef, (values) => {
699
714
  // A later create override must still run, with the definition as receiver.
700
715
  const current = structDef.create;
701
- return current === create ? createBuffer(values) : current.call(structDef, values);
716
+ if (current !== create) return current.call(structDef, values);
717
+ return structDef.set === set ? createFast(values) : createBuffer(values);
702
718
  });
719
+ const toObject = structDef.toObject;
720
+ const readers = fieldDefs.map((field) => [field.name, fieldReaders[field.name]]);
721
+ if (readers.every(([name, read]) => name !== "__proto__" && typeof read === "function")) {
722
+ // Scalar readers return primitives without reentering, so the native
723
+ // result buffer can be read in place; a toObject override gets a copy.
724
+ structResultReaders.set(structDef, (bytes) => {
725
+ if (structDef.toObject !== toObject) return structDef.toObject(Buffer.from(bytes));
726
+ const result = {};
727
+ for (let i = 0; i < readers.length; i++) {
728
+ const [name, read] = readers[i];
729
+ result[name] = read(bytes);
730
+ }
731
+ return result;
732
+ });
733
+ }
703
734
  }
704
735
 
705
736
  return syncDefinition(structDef);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-ctypes",
3
- "version": "2.6.0",
3
+ "version": "2.7.0",
4
4
  "description": "Python ctypes-like FFI for Node.js using libffi",
5
5
  "author": "Damiano Mazzella",
6
6
  "license": "MIT",