node-ctypes 2.13.1 → 2.13.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 +39 -2
- package/README.md +24 -1171
- package/build/Release/ctypes-darwin-arm64.node +0 -0
- package/build/Release/ctypes-darwin-x64.node +0 -0
- package/build/Release/ctypes-linux-arm64-musl.node +0 -0
- package/build/Release/ctypes-linux-arm64.node +0 -0
- package/build/Release/ctypes-linux-x64-musl.node +0 -0
- package/build/Release/ctypes-linux-x64.node +0 -0
- package/build/Release/ctypes-win32-arm64.node +0 -0
- package/build/Release/ctypes-win32-x64.node +0 -0
- package/package.json +2 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [2.13.2] - 2026-11-15
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
|
|
14
|
+
- **libffi 3.8.1**: the submodule moves from upstream commit `d02afc25` to the
|
|
15
|
+
v3.8.1 tag, with two fixes that node-ctypes could reach on ARM64:
|
|
16
|
+
- a struct larger than 16 bytes (other than an HFA) passed by value after the
|
|
17
|
+
integer registers, after a narrow stack argument on macOS (stack arguments
|
|
18
|
+
are packed there) or with `_align_ = 16` elsewhere, had the pointer to its
|
|
19
|
+
copy in a misaligned stack slot: the C function read another address and
|
|
20
|
+
could crash ([GHSA-h52h-3759-xqm4](https://github.com/libffi/libffi/security/advisories/GHSA-h52h-3759-xqm4)).
|
|
21
|
+
The tests skipped on Darwin ARM64 for this limitation run again;
|
|
22
|
+
- on macOS ARM64, with more than 1024 live callbacks, some orders of
|
|
23
|
+
`release()` wrote into a freed trampoline table
|
|
24
|
+
([GHSA-23hx-9rxv-9qfp](https://github.com/libffi/libffi/security/advisories/GHSA-23hx-9rxv-9qfp)).
|
|
25
|
+
|
|
26
|
+
The other fixes of the release concern types node-ctypes does not expose
|
|
27
|
+
(`long double`, vectors) or platforms and APIs it does not use. The generated
|
|
28
|
+
headers report 3.8.1.
|
|
29
|
+
|
|
30
|
+
### Documentation
|
|
31
|
+
|
|
32
|
+
- **Guides**: the reference sections of the README moved, unchanged, to
|
|
33
|
+
`guides/` (libraries and functions, types, structures, memory, callbacks,
|
|
34
|
+
asynchronous calls, errors, Windows API, TypeScript, Python ctypes parity,
|
|
35
|
+
building and testing), also published on the documentation site. The README
|
|
36
|
+
keeps the quick start, the supported platforms and the list of guides. New
|
|
37
|
+
pages: Getting started (installation, supported platforms, building from
|
|
38
|
+
source), Coming from Koffi (the Koffi API mapped to node-ctypes) and
|
|
39
|
+
Performance (results of the Koffi comparison, with charts, and how to run
|
|
40
|
+
it). The paragraph on direct calls now describes the register-frame calls.
|
|
41
|
+
- **Benchmark charts**: `npm run bench:charts -- report.json` writes static
|
|
42
|
+
SVG charts (ratio summary and one chart per workload group, light and dark)
|
|
43
|
+
from the JSON report of `bench:koffi` or `bench:ffi` (`--output`), into
|
|
44
|
+
`guides/images/` or the `--out` directory.
|
|
45
|
+
|
|
10
46
|
## [2.13.1] - 2026-11-14
|
|
11
47
|
|
|
12
48
|
### Fixed
|
|
@@ -1117,7 +1153,7 @@ number, not string`).
|
|
|
1117
1153
|
|
|
1118
1154
|
2.0 aligns node-ctypes with Python ctypes as closely as the language allows,
|
|
1119
1155
|
so that Python code can be ported with only the changes JavaScript requires.
|
|
1120
|
-
It contains breaking changes: see [Migrating from 1.x](
|
|
1156
|
+
It contains breaking changes: see [Migrating from 1.x](guides/python.md#migrating-from-1x).
|
|
1121
1157
|
|
|
1122
1158
|
### Breaking changes
|
|
1123
1159
|
|
|
@@ -1431,7 +1467,8 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
|
|
|
1431
1467
|
|
|
1432
1468
|
Initial releases.
|
|
1433
1469
|
|
|
1434
|
-
[Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.13.
|
|
1470
|
+
[Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.13.2...HEAD
|
|
1471
|
+
[2.13.2]: https://github.com/dmazzella/node-ctypes/compare/v2.13.1...v2.13.2
|
|
1435
1472
|
[2.13.1]: https://github.com/dmazzella/node-ctypes/compare/v2.13.0...v2.13.1
|
|
1436
1473
|
[2.13.0]: https://github.com/dmazzella/node-ctypes/compare/v2.12.2...v2.13.0
|
|
1437
1474
|
[2.12.2]: https://github.com/dmazzella/node-ctypes/compare/v2.12.1...v2.12.2
|
package/README.md
CHANGED
|
@@ -52,946 +52,38 @@ const p = new Point(3, 4);
|
|
|
52
52
|
console.log(p.x, p.y); // 3 4
|
|
53
53
|
```
|
|
54
54
|
|
|
55
|
-
|
|
56
|
-
<summary>Build from source</summary>
|
|
55
|
+
To build from source, see [Getting started](guides/getting-started.md#building-from-source).
|
|
57
56
|
|
|
58
|
-
|
|
59
|
-
Run these commands from a source checkout:
|
|
57
|
+
## Supported platforms
|
|
60
58
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
59
|
+
| Operating system | x64 | ARM64 | Minimum version |
|
|
60
|
+
| -------------------- | --- | ----- | --------------- |
|
|
61
|
+
| Windows | ✅ | ✅ | |
|
|
62
|
+
| macOS | ✅ | ✅ | macOS 13.5 |
|
|
63
|
+
| Linux, glibc | ✅ | ✅ | glibc 2.28 |
|
|
64
|
+
| Linux, musl (Alpine) | ✅ | ✅ | |
|
|
65
65
|
|
|
66
|
-
|
|
66
|
+
Node.js 24 or later. Details, testing and building from source are in
|
|
67
|
+
[Getting started](guides/getting-started.md).
|
|
67
68
|
|
|
68
69
|
---
|
|
69
70
|
|
|
70
71
|
## Guides
|
|
71
72
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
For Windows `__stdcall` APIs use `WinDLL` instead of `CDLL`. For COM-style
|
|
89
|
-
auto-`HRESULT`-checking use `OleDLL`.
|
|
90
|
-
|
|
91
|
-
Direct native calls are limited to a bounded set of exact scalar C++
|
|
92
|
-
signatures with up to four arguments, on 64-bit little-endian targets using
|
|
93
|
-
the default ABI. By default, other signatures use the existing cached libffi plans/CIFs,
|
|
94
|
-
including pointers and strings whose pointee types and qualifiers are not
|
|
95
|
-
encoded in the native type metadata. Float/double arguments continue to use
|
|
96
|
-
libffi on x86-64. This changes the optimization route, not the JavaScript API.
|
|
97
|
-
Eligible fixed invokers are selected before constructing libffi types, CIFs or
|
|
98
|
-
call plans. Fixed async workers reuse the same selected invoker, with their own
|
|
99
|
-
argument/result storage. Other signatures retain eager fallback setup;
|
|
100
|
-
additional arguments bypass fixed invokers and prepare their libffi metadata
|
|
101
|
-
on the JavaScript thread. Inferred calls use the ordinary ABI; true variadic
|
|
102
|
-
calls preserve the declared named-prefix boundary.
|
|
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
|
-
- `spin` (microseconds, default 50, `0` to disable): after a call the thread
|
|
139
|
-
polls for the next one this long (at most 50 µs) before sleeping, and the JavaScript thread
|
|
140
|
-
waits this long for a call submitted to an idle executor, completing it
|
|
141
|
-
without a round trip through the event loop. Awaited calls in sequence then
|
|
142
|
-
cost a few microseconds instead of tens; its errcheck may run before
|
|
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.
|
|
149
|
-
- A call that has started cannot be interrupted: the signal only removes
|
|
150
|
-
queued calls.
|
|
151
|
-
- On process exit (or worker termination) queued calls are discarded and a
|
|
152
|
-
running call is left to finish on its own.
|
|
153
|
-
- Callbacks invoked during the call run on the executor thread: use
|
|
154
|
-
`threadSafeCallback`, as with `callAsync`.
|
|
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
|
-
|
|
166
|
-
### Structs, unions, bit fields, arrays
|
|
167
|
-
|
|
168
|
-
```javascript
|
|
169
|
-
import { Structure, Union, array, c_int32, c_uint32, c_float, c_char } from "node-ctypes";
|
|
170
|
-
|
|
171
|
-
class Rect extends Structure {
|
|
172
|
-
static _fields_ = [
|
|
173
|
-
["x", c_int32],
|
|
174
|
-
["y", c_int32],
|
|
175
|
-
["w", c_int32],
|
|
176
|
-
["h", c_int32],
|
|
177
|
-
];
|
|
178
|
-
}
|
|
179
|
-
|
|
180
|
-
class Value extends Union {
|
|
181
|
-
static _fields_ = [
|
|
182
|
-
["i", c_int32],
|
|
183
|
-
["f", c_float],
|
|
184
|
-
];
|
|
185
|
-
}
|
|
186
|
-
|
|
187
|
-
// Bit fields: [name, type, bitCount]
|
|
188
|
-
class Flags extends Structure {
|
|
189
|
-
static _fields_ = [
|
|
190
|
-
["enabled", c_uint32, 1],
|
|
191
|
-
["mode", c_uint32, 3],
|
|
192
|
-
["priority", c_uint32, 4],
|
|
193
|
-
];
|
|
194
|
-
}
|
|
195
|
-
|
|
196
|
-
// Arrays: elementType * count (Python: `c_int32 * 5`)
|
|
197
|
-
const IntArr5 = array(c_int32, 5);
|
|
198
|
-
const arr = IntArr5(1, 2, 3, 4, 5); // Python: (c_int32 * 5)(1, 2, 3, 4, 5)
|
|
199
|
-
|
|
200
|
-
// char arrays read and write as strings (Python: bytes)
|
|
201
|
-
const name = array(c_char, 16)();
|
|
202
|
-
name.value = "node"; // .value / .raw as in Python
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
`array(type, n)` reuses the same type while it is alive. Instances, function
|
|
206
|
-
signatures and containing types keep their array types alive; the cache itself
|
|
207
|
-
does not. Unused array types and their length entries can be garbage-collected,
|
|
208
|
-
including arrays of builtin element types.
|
|
209
|
-
|
|
210
|
-
An array type in `argtypes` is passed by address, as in C and Python
|
|
211
|
-
(`fill.argtypes = [c_int32 * 4]`). As in Python, the argument must be an
|
|
212
|
-
instance of an array with the same element type and length; a Buffer or a
|
|
213
|
-
typed array is also accepted as its memory. Other values raise
|
|
214
|
-
`ArgumentError`.
|
|
215
|
-
|
|
216
|
-
Builtin numeric scalars accept numbers, booleans and BigInt; integers wrap to
|
|
217
|
-
their C width, but reject non-integral or non-finite numbers. Use BigInt when
|
|
218
|
-
the original integer needs more precision than a JS number can represent.
|
|
219
|
-
No argument, or `undefined` in a constructor, initializes zero. Explicit
|
|
220
|
-
`null`, strings and arbitrary objects are not implicit numeric conversions.
|
|
221
|
-
Assigning a scalar instance to a field or passing it to a declared numeric
|
|
222
|
-
argument requires a compatible type. The documented numeric-pointer argument
|
|
223
|
-
extensions below are unchanged.
|
|
224
|
-
|
|
225
|
-
`c_bool` and `wintypes.VARIANT_BOOL` use JavaScript truthiness, using `.value`
|
|
226
|
-
for scalar instances rather than treating every instance as true.
|
|
227
|
-
`VARIANT_BOOL` stores true as `-1`, and its results and callback arguments
|
|
228
|
-
are booleans. Boolean bitfields normalize before masking and read as booleans.
|
|
229
|
-
|
|
230
|
-
Nested structs, anonymous fields (`static _anonymous_ = ["data"]`),
|
|
231
|
-
explicit packing (`static _pack_ = 1`), minimum alignment
|
|
232
|
-
(`static _align_ = 16`), self-referential pointers (`POINTER(() => Node)`)
|
|
233
|
-
and subclasses that add fields to their base class all work identically to
|
|
234
|
-
Python. The layout of bit fields follows Python's `_layout_`: `"gcc-sysv"`
|
|
235
|
-
by default, `"ms"` on Windows or with `_pack_`. Bit fields wider than 53
|
|
236
|
-
bits read as BigInt.
|
|
237
|
-
|
|
238
|
-
`_pack_` follows Python's integer conversion and permits zero and non-powers
|
|
239
|
-
of two (for example `3`) with the MS layout. An explicit `_pack_`, including
|
|
240
|
-
zero, is incompatible with `"gcc-sysv"`. Layouts with non-power-of-two
|
|
241
|
-
alignment can be used for memory serialization but are rejected as native
|
|
242
|
-
by-value signatures: they do not describe a valid C ABI alignment.
|
|
243
|
-
|
|
244
|
-
Structures and unions passed or returned by value keep this layout, also
|
|
245
|
-
with `_pack_`: as with GCC and clang, a structure with misaligned fields is
|
|
246
|
-
passed in memory on x86-64 System V (Linux, macOS Intel), where Python
|
|
247
|
-
ctypes passes it in registers and the called function reads wrong values.
|
|
248
|
-
|
|
249
|
-
Each returned structure or union owns a snapshot of its value, including
|
|
250
|
-
results declared with functional `struct()` / `union()` definitions. Array
|
|
251
|
-
views, nested composites and union getters remain valid after later calls,
|
|
252
|
-
reentrant conversion or `errcheck`, and concurrent `callAsync()` jobs.
|
|
253
|
-
Mutating one result does not modify another result's value storage.
|
|
254
|
-
|
|
255
|
-
This is not a deep copy through pointers: pointer fields can still refer to
|
|
256
|
-
the same external memory. Explicit `definition.toObject(buffer)` keeps its
|
|
257
|
-
existing buffer-view behavior. Synchronous low-level native `struct_buffer`
|
|
258
|
-
results are borrowed, reusable storage; public callables snapshot their
|
|
259
|
-
results before any JavaScript result conversion.
|
|
260
|
-
|
|
261
|
-
Low-level native `StructType` descriptors are builders only until consumed.
|
|
262
|
-
Adding a descriptor as a field, constructing an `ArrayType` from it (even at
|
|
263
|
-
length zero), preparing a function/callback signature, or creating/reading a
|
|
264
|
-
native value finalizes the captured layout and its dependencies.
|
|
265
|
-
`addField()` then throws instead of changing sizes, offsets or FFI metadata
|
|
266
|
-
already in use. Build a new descriptor for a different layout.
|
|
267
|
-
`getSize()` and `getAlignment()` alone leave an unused builder open; an
|
|
268
|
-
outer builder can still receive fields after it captures a finalized child.
|
|
269
|
-
Direct by-value self-reference is rejected. Pointers do not capture or
|
|
270
|
-
finalize the pointed-to layout.
|
|
271
|
-
|
|
272
|
-
### Pointers, buffers, and cast
|
|
273
|
-
|
|
274
|
-
```javascript
|
|
275
|
-
import { POINTER, pointer, cast, c_int32, c_void_p } from "node-ctypes";
|
|
276
|
-
|
|
277
|
-
// Pointer to an existing c-data instance (Python: pointer(x))
|
|
278
|
-
const x = new c_int32(42);
|
|
279
|
-
const px = pointer(x);
|
|
280
|
-
px.contents.value; // 42 (Python: px.contents.value — a live c_int32)
|
|
281
|
-
px[0]; // 42 (Python: px[0])
|
|
282
|
-
px[0] = 100;
|
|
283
|
-
x.value; // 100 (same memory)
|
|
284
|
-
|
|
285
|
-
// View existing memory as a typed pointer
|
|
286
|
-
const IntPtr = POINTER(c_int32);
|
|
287
|
-
const p = IntPtr.fromBuffer(someBuffer);
|
|
288
|
-
p[0];
|
|
289
|
-
p[1];
|
|
290
|
-
p[2]; // pointer arithmetic
|
|
291
|
-
|
|
292
|
-
// cast() — Python: cast(ptr, POINTER(T))
|
|
293
|
-
const q = cast(someBuffer, POINTER(c_int32));
|
|
294
|
-
const r = cast(addressAsBigInt, POINTER(MyStruct));
|
|
295
|
-
```
|
|
296
|
-
|
|
297
|
-
A `POINTER(T)` restype returns a pointer object, and a NULL pointer (return
|
|
298
|
-
value or struct field) is `null` — where Python returns a falsy pointer.
|
|
299
|
-
|
|
300
|
-
To hand a raw address to a function, use `c_void_p` as the argtype for
|
|
301
|
-
portable code (Python accepts raw `int` only there). As in Python, values
|
|
302
|
-
that cannot be converted (a plain JS function, an object) raise
|
|
303
|
-
`ArgumentError` instead of passing NULL; `c_void_p` also accepts strings
|
|
304
|
-
(as `char *`, Python `bytes`) and any TypedArray/ArrayBuffer.
|
|
305
|
-
|
|
306
|
-
Declared `POINTER(T)` parameters reject incompatible ctypes instances,
|
|
307
|
-
arrays and pointer types before entering C. Compatible subclasses and arrays
|
|
308
|
-
are accepted, and a matching scalar/structure is passed by reference.
|
|
309
|
-
These implicit scalar/array/NULL conversions apply to direct arguments only.
|
|
310
|
-
To adapt one of these values through `_as_parameter_`, return an explicit
|
|
311
|
-
compatible pointer or `byref` value instead, as in CPython.
|
|
312
|
-
An explicit `cast()` changes the pointer type. Raw addresses and raw
|
|
313
|
-
Buffer/TypedArray/ArrayBuffer memory remain node-ctypes extensions; use
|
|
314
|
-
`c_void_p` for portable raw-address code.
|
|
315
|
-
|
|
316
|
-
`byref(value, byteOffset = 0)` preserves the original owner and supports
|
|
317
|
-
signed byte offsets. In-range references remain Buffer views; references
|
|
318
|
-
outside the object's byte range carry an address and owner. As with raw
|
|
319
|
-
addresses, the caller must ensure such memory is valid before dereferencing.
|
|
320
|
-
Function pointers read from fields or obtained from FFI bindings can be
|
|
321
|
-
assigned back to fields/arrays and passed as pointer arguments. Bare JS
|
|
322
|
-
functions still require `callback()` / a prototype-created callback.
|
|
323
|
-
|
|
324
|
-
### Callbacks
|
|
325
|
-
|
|
326
|
-
```javascript
|
|
327
|
-
import { callback, CFUNCTYPE, c_int32, c_void_p, readValue } from "node-ctypes";
|
|
328
|
-
|
|
329
|
-
// Python-style type: CFUNCTYPE(restype, ...argtypes)
|
|
330
|
-
const CompareFn = CFUNCTYPE(c_int32, c_void_p, c_void_p);
|
|
331
|
-
const cmp = new CompareFn((a, b) => readValue(a, c_int32) - readValue(b, c_int32));
|
|
332
|
-
|
|
333
|
-
// Or the one-shot form:
|
|
334
|
-
const cmp2 = callback((a, b) => readValue(a, c_int32) - readValue(b, c_int32), c_int32, [c_void_p, c_void_p]);
|
|
335
|
-
|
|
336
|
-
// Pass the callback itself (as in Python) or its address `cmp.pointer`.
|
|
337
|
-
qsort(arr, 5, 4, cmp);
|
|
338
|
-
|
|
339
|
-
// CFUNCTYPE types also work as struct fields (read back as a callable).
|
|
340
|
-
|
|
341
|
-
// IMPORTANT: release the trampoline when done. Unlike Python, we cannot
|
|
342
|
-
// rely on GC — the callback holds a native trampoline that C code may
|
|
343
|
-
// still reference.
|
|
344
|
-
cmp.release();
|
|
345
|
-
cmp2.release();
|
|
346
|
-
```
|
|
347
|
-
|
|
348
|
-
`CFUNCTYPE` and `WINFUNCTYPE` weakly intern live prototypes by the complete
|
|
349
|
-
identity and order of their argument/return types, separately for each calling
|
|
350
|
-
convention. Repeated requests reuse the same live prototype, as in Python,
|
|
351
|
-
without keeping abandoned types alive. Callers, callbacks and output bindings
|
|
352
|
-
retain their prototype while they are live.
|
|
353
|
-
|
|
354
|
-
Prototype metadata is shared. Changing its public `restype` / `argtypes`
|
|
355
|
-
metadata does not recompile the captured native signature or alter cache keys;
|
|
356
|
-
request a different signature to change the ABI. Each new caller prepares its
|
|
357
|
-
argument-conversion pipeline and captures its result-check hook independently.
|
|
358
|
-
Existing callers retain their result-check snapshot and their own `errcheck`.
|
|
359
|
-
An installed `from_param` converter still resolves the method at call time,
|
|
360
|
-
as before.
|
|
361
|
-
|
|
362
|
-
Structure, union and scalar-instance arguments received by `callback()`,
|
|
363
|
-
`CFUNCTYPE` and `threadSafeCallback()` are owned snapshots: each one is a
|
|
364
|
-
distinct slice of an 8 KB off-heap pool reserved for callback snapshots.
|
|
365
|
-
Native-call temporaries use a separate pool that is never exposed, so a
|
|
366
|
-
snapshot cannot reveal or alter memory that native code is still using.
|
|
367
|
-
Slices are never reused, so a retained argument keeps its own bytes and
|
|
368
|
-
identity. Detaching a snapshot's `ArrayBuffer` (`transfer()`, a transfer list)
|
|
369
|
-
only affects the snapshots in that pool; later callbacks use a fresh one.
|
|
370
|
-
|
|
371
|
-
- Retaining any slice keeps its whole 8 KB backing `ArrayBuffer` alive. When
|
|
372
|
-
storing many small arguments for a long time, copy them, for example
|
|
373
|
-
`Buffer.from(value._buffer)` or a new instance built from its fields.
|
|
374
|
-
- `value._buffer.buffer` is the whole pool and can contain other callback
|
|
375
|
-
snapshots. Use `_buffer` itself (or `byteOffset` and `length`), and copy
|
|
376
|
-
before handing the underlying `ArrayBuffer` to untrusted code.
|
|
377
|
-
|
|
378
|
-
Values larger than 2 KB, layouts aligned to more than 8 bytes and raw native
|
|
379
|
-
callbacks keep a dedicated allocation.
|
|
380
|
-
|
|
381
|
-
Both callbacks and libraries implement `Symbol.dispose`, so they work
|
|
382
|
-
with the `using` declaration for scope-bound cleanup (also on `throw`):
|
|
383
|
-
|
|
384
|
-
```javascript
|
|
385
|
-
{
|
|
386
|
-
using libc = new CDLL(null);
|
|
387
|
-
using cmp = callback(fn, c_int32, [c_void_p, c_void_p]);
|
|
388
|
-
qsort(arr, 5, 4, cmp);
|
|
389
|
-
} // close() + release() run automatically
|
|
390
|
-
```
|
|
391
|
-
|
|
392
|
-
A bound function keeps its library loaded as long as it is referenced, also
|
|
393
|
-
when the `CDLL` object itself is no longer used. After `close()`, `loaded` is
|
|
394
|
-
false and its bound functions and symbol lookups throw; `close()` itself
|
|
395
|
-
throws while a call to one of them is in progress (from a callback, or a
|
|
396
|
-
pending `callAsync()`). Repeated `close()` calls are harmless.
|
|
397
|
-
|
|
398
|
-
Existing `in_dll()` views keep the underlying module loaded even after
|
|
399
|
-
`close()`. Release of the native library handle is deferred until the last
|
|
400
|
-
dependent view, Buffer, typed array or typed pointer copy is collected; those
|
|
401
|
-
existing views remain usable. Actual physical unloading depends on the OS loader: for example,
|
|
402
|
-
musl keeps shared libraries resident until process exit even after `dlclose()`.
|
|
403
|
-
Raw addresses obtained with `symbol()` do not carry this ownership information.
|
|
404
|
-
|
|
405
|
-
Set `NODE_CTYPES_DEBUG_CALLBACKS=1` to log a stack trace for every
|
|
406
|
-
callback garbage-collected without `.release()`.
|
|
407
|
-
|
|
408
|
-
Callbacks invoked by native threads need `threadSafeCallback()`: the
|
|
409
|
-
JavaScript function runs on the main thread, and the calling thread waits
|
|
410
|
-
for its result (several threads can call it at the same time; each gets the
|
|
411
|
-
result of its own call, `0` if the function throws). Like a timer, a
|
|
412
|
-
thread-safe callback keeps the event loop
|
|
413
|
-
alive until released; `.unref()` lets the process exit when nothing else
|
|
414
|
-
is pending (calls are still delivered while it runs), `.ref()` restores it:
|
|
415
|
-
|
|
416
|
-
```javascript
|
|
417
|
-
const onEvent = threadSafeCallback((code) => console.log("event", code), null, [c_int]).unref();
|
|
418
|
-
startWorker(onEvent); // a native library calling onEvent from its own thread
|
|
419
|
-
```
|
|
420
|
-
|
|
421
|
-
For an embedding runtime that must detach its native thread state before waiting,
|
|
422
|
-
the optional fourth argument can be `{ abi, nativeContext: { suspend, resume, onError, notify? } }`
|
|
423
|
-
instead of the existing ABI string. Each hook accepts a ctypes native function,
|
|
424
|
-
a low-level function handle, or a nonzero BigInt function address:
|
|
425
|
-
|
|
426
|
-
```javascript
|
|
427
|
-
const onRequest = threadSafeCallback(handleRequest, c_int, [c_int], {
|
|
428
|
-
nativeContext: {
|
|
429
|
-
suspend: runtime.func("save_context", c_void_p, []),
|
|
430
|
-
resume: runtime.func("restore_context", null, [c_void_p]),
|
|
431
|
-
onError: runtime.func("install_error", null, [c_void_p]),
|
|
432
|
-
notify: runtime.func("wake_host", null, []),
|
|
433
|
-
},
|
|
434
|
-
});
|
|
435
|
-
```
|
|
436
|
-
|
|
437
|
-
Function objects resolve through `_as_parameter_` or `address` once, when the
|
|
438
|
-
callback is constructed. The hooks are called directly using the default C ABI;
|
|
439
|
-
the function wrapper's JS converters and `errcheck` are not invoked:
|
|
440
|
-
|
|
441
|
-
- `void *suspend(void)` runs on a foreign caller before queueing.
|
|
442
|
-
- `void resume(void *)` restores that caller's saved state after dispatch, including
|
|
443
|
-
queue failure or environment shutdown. Neither hook runs on the Node host fast path.
|
|
444
|
-
- `void onError(void *)` consumes an opaque error pointer on the original caller
|
|
445
|
-
thread, after restoration. During the JS callback, use
|
|
446
|
-
`callback.setNativeError(pointer)` once and return the native API's required error
|
|
447
|
-
sentinel (`NULL`, `-1`, etc.). Error payloads belong to each invocation, including
|
|
448
|
-
concurrent and nested calls; JS exceptions are still reported as documented above.
|
|
449
|
-
- Optional `void notify(void)` runs on the foreign caller after successful queueing,
|
|
450
|
-
while its native state is detached. It may wake the host through the consumer's
|
|
451
|
-
runtime, but must not execute JavaScript itself.
|
|
452
|
-
|
|
453
|
-
`callback.drain()` executes a snapshot of pending calls **on the owning Node
|
|
454
|
-
thread**, returning the number it claimed. Each call executes at most once,
|
|
455
|
-
whether the TSFN or a drain gets there first. Delayed TSFN deliveries retain
|
|
456
|
-
only the shared request state and do not touch completed calls' native arguments.
|
|
457
|
-
The consumer must provide a safe way to reenter the host and call `drain()`;
|
|
458
|
-
calling it before entering a blocking native wait is not sufficient.
|
|
459
|
-
|
|
460
|
-
Hooks must not throw or execute JavaScript. Plain JS functions and known
|
|
461
|
-
JS-backed callback wrappers are rejected; an address cannot prove a function's
|
|
462
|
-
signature, validity or implementation. Supplied function objects are retained by
|
|
463
|
-
the native dispatcher through release and queued delivery cleanup. This does not
|
|
464
|
-
prevent explicitly closing their libraries or releasing their underlying resources;
|
|
465
|
-
raw addresses carry no owner. Keep the callback and the hook libraries
|
|
466
|
-
alive until all native calls have returned; explicit release is rejected while a
|
|
467
|
-
native-context call is active. These hooks do not acquire the host runtime context,
|
|
468
|
-
pump a blocked host event loop automatically, or implement interpreter ownership/subinterpreters.
|
|
469
|
-
The host JS handler must acquire/release its own runtime context around native API
|
|
470
|
-
operations. The ordinary callback path is unchanged when no hooks are supplied.
|
|
471
|
-
|
|
472
|
-
Both callback implementations store narrow integer results in a complete
|
|
473
|
-
libffi `ffi_arg`, with the declared signedness; failures zero that complete
|
|
474
|
-
slot. Floating-point results retain their own storage width. The native
|
|
475
|
-
`Callback` / `ThreadSafeCallback` classes also expose `getPointer()`, which
|
|
476
|
-
throws after release.
|
|
477
|
-
|
|
478
|
-
### Errors: `errno` and `GetLastError`
|
|
479
|
-
|
|
480
|
-
`GetLastError()` / `get_errno()` read a **private thread-local slot** —
|
|
481
|
-
exactly like Python's `ctypes.get_last_error()` / `ctypes.get_errno()`.
|
|
482
|
-
The slot is updated **only** by FFI calls through libraries opened with
|
|
483
|
-
`use_last_error` or `use_errno`; unflagged calls leave it unchanged. As in Python
|
|
484
|
-
those calls swap it with the system value: the function sees the value set
|
|
485
|
-
with `set_errno()` / `set_last_error()`, the value it leaves becomes the
|
|
486
|
-
private one, and the system value is restored after the call.
|
|
487
|
-
|
|
488
|
-
```javascript
|
|
489
|
-
const user32 = new WinDLL("user32.dll", { use_last_error: true });
|
|
490
|
-
const FindWindow = user32.func("FindWindowW", c_void_p, [c_wchar_p, c_wchar_p]);
|
|
491
|
-
FindWindow("NoSuchClass", null);
|
|
492
|
-
|
|
493
|
-
GetLastError(); // top-level (Python: ctypes.get_last_error)
|
|
494
|
-
user32.get_last_error(); // per-library alias
|
|
495
|
-
```
|
|
496
|
-
|
|
497
|
-
The snapshot is captured in native code immediately after the native call,
|
|
498
|
-
whether direct or through libffi, before any other JS can clobber it. To read the raw system
|
|
499
|
-
error instead, call `GetLastError` via FFI like any other function.
|
|
500
|
-
|
|
501
|
-
### Windows API
|
|
502
|
-
|
|
503
|
-
`wintypes` is Python's `ctypes.wintypes`: the same types (BOOL, BYTE,
|
|
504
|
-
WORD, DWORD, HANDLE, HWND, LPARAM, WPARAM, LPCWSTR, …), structures (`RECT`,
|
|
505
|
-
`POINT`, `SIZE`, `MSG`, `FILETIME`, `WIN32_FIND_DATAW`, …) and pointer types
|
|
506
|
-
(`LPDWORD = POINTER(DWORD)`, `LPRECT`, `PHANDLE`, …), plus common extras
|
|
507
|
-
(`LRESULT`, `UINT_PTR`, `LSTATUS`, …).
|
|
508
|
-
|
|
509
|
-
```javascript
|
|
510
|
-
import { WinDLL, Structure, POINTER, byref, wintypes } from "node-ctypes";
|
|
511
|
-
const { WORD, HWND, BOOL, RECT, LPRECT } = wintypes;
|
|
512
|
-
|
|
513
|
-
const kernel32 = new WinDLL("kernel32.dll");
|
|
514
|
-
|
|
515
|
-
class SYSTEMTIME extends Structure {
|
|
516
|
-
static _fields_ = [
|
|
517
|
-
["wYear", WORD],
|
|
518
|
-
["wMonth", WORD],
|
|
519
|
-
["wDayOfWeek", WORD],
|
|
520
|
-
["wDay", WORD],
|
|
521
|
-
["wHour", WORD],
|
|
522
|
-
["wMinute", WORD],
|
|
523
|
-
["wSecond", WORD],
|
|
524
|
-
["wMilliseconds", WORD],
|
|
525
|
-
];
|
|
526
|
-
}
|
|
527
|
-
|
|
528
|
-
kernel32.GetLocalTime.argtypes = [POINTER(SYSTEMTIME)];
|
|
529
|
-
kernel32.GetLocalTime.restype = null;
|
|
530
|
-
const st = new SYSTEMTIME();
|
|
531
|
-
kernel32.GetLocalTime(byref(st));
|
|
532
|
-
|
|
533
|
-
const user32 = new WinDLL("user32.dll");
|
|
534
|
-
user32.GetClientRect.argtypes = [HWND, LPRECT];
|
|
535
|
-
user32.GetClientRect.restype = BOOL;
|
|
536
|
-
const rect = new RECT();
|
|
537
|
-
user32.GetClientRect(hwnd, byref(rect));
|
|
538
|
-
rect.right - rect.left; // LONG (c_long) values are BigInt
|
|
539
|
-
```
|
|
540
|
-
|
|
541
|
-
### Error checking (`errcheck`)
|
|
542
|
-
|
|
543
|
-
Set `fn.errcheck = (result, func, args) => ...` to check or replace a result,
|
|
544
|
-
or set it to `null` to clear it. For `lib.func()`, library attributes and
|
|
545
|
-
`CFUNCTYPE` / `WINFUNCTYPE` callers, `func` is the public callable and `args`
|
|
546
|
-
contains the original, unconverted arguments. Result conversion and any
|
|
547
|
-
`OleDLL` HRESULT check run before the hook.
|
|
548
|
-
|
|
549
|
-
Each invocation captures its hook before argument adapters or getters run.
|
|
550
|
-
Replacing or clearing it affects later invocations, including reentrant calls,
|
|
551
|
-
not the call already in progress or a pending `callAsync()` job.
|
|
552
|
-
|
|
553
|
-
Hooks do not prevent otherwise unreachable functions and libraries from being
|
|
554
|
-
garbage-collected, even when they reference the function itself. Active calls
|
|
555
|
-
and workers retain their captured hook through result checking; `close()` is
|
|
556
|
-
still rejected while that checking runs.
|
|
557
|
-
|
|
558
|
-
The low-level native handle's `setErrcheck()` API instead passes the native
|
|
559
|
-
handle as `func`, invoked with `.call()`, not a directly callable function.
|
|
560
|
-
|
|
561
|
-
### Scalar subclasses and result hooks
|
|
562
|
-
|
|
563
|
-
Builtin scalar types return ordinary JS values. A subclass instead produces
|
|
564
|
-
an instance containing the original C bytes, without invoking its constructor,
|
|
565
|
-
public buffer factory or writer. Derived scalar fields, array elements,
|
|
566
|
-
pointer indexing and callback arguments likewise expose typed instances;
|
|
567
|
-
memory views remain live, including in mirror mode.
|
|
568
|
-
|
|
569
|
-
The result pipeline is:
|
|
570
|
-
`C bytes -> restype representation -> _check_retval_ -> errcheck -> OUT/INOUT`.
|
|
571
|
-
A static `_check_retval_` receives the represented result and can replace it
|
|
572
|
-
or throw. It is captured when the function is bound; reassigning an attribute's
|
|
573
|
-
`restype` rebuilds that binding.
|
|
574
|
-
|
|
575
|
-
```javascript
|
|
576
|
-
class CheckedInt extends c_int32 {
|
|
577
|
-
static _check_retval_(value) {
|
|
578
|
-
return value.value + 100;
|
|
579
|
-
}
|
|
580
|
-
}
|
|
581
|
-
const checkedAbs = libc.func("abs", CheckedInt, [c_int32]);
|
|
582
|
-
checkedAbs(-7); // 107
|
|
583
|
-
```
|
|
584
|
-
|
|
585
|
-
Explicit `HRESULT` validation runs before `errcheck` with all loaders and
|
|
586
|
-
prototype callers, not only `OleDLL`. An error in result checking prevents
|
|
587
|
-
both `errcheck` and output conversion.
|
|
588
|
-
`OleDLL` attributes and `func(name)` default to `HRESULT`; other loaders
|
|
589
|
-
default to `c_int`. An explicit restype always overrides the default.
|
|
590
|
-
|
|
591
|
-
### Output parameters (`paramflags`)
|
|
592
|
-
|
|
593
|
-
When at least one `out` param is declared, the call returns **only the
|
|
594
|
-
out-params** (single value, or array if >1) — the `restype` is
|
|
595
|
-
discarded. To also inspect it (e.g. a thread ID or success flag), attach an
|
|
596
|
-
`errcheck`:
|
|
597
|
-
|
|
598
|
-
```javascript
|
|
599
|
-
const { DWORD, HWND, LPDWORD } = wintypes;
|
|
600
|
-
const proto = WINFUNCTYPE(DWORD, HWND, LPDWORD);
|
|
601
|
-
const fn = proto.bind(user32, "GetWindowThreadProcessId", [
|
|
602
|
-
{ dir: "in", name: "hWnd" },
|
|
603
|
-
{ dir: "out", name: "pid" },
|
|
604
|
-
]);
|
|
605
|
-
|
|
606
|
-
const pid = fn(hwnd); // positional; thread ID is discarded
|
|
607
|
-
const p2 = fn({ hWnd: hwnd }); // or named-args
|
|
608
|
-
|
|
609
|
-
fn.errcheck = (threadId, func, args) => {
|
|
610
|
-
if (!threadId) throw new Error("call failed");
|
|
611
|
-
return args; // continue returning the PID from the output instance
|
|
612
|
-
};
|
|
613
|
-
const p3 = await fn.callAsync(hwnd);
|
|
614
|
-
|
|
615
|
-
fn.errcheck = (threadId, func, args) => {
|
|
616
|
-
if (!threadId) throw new Error("call failed");
|
|
617
|
-
return { threadId, processId: args[1].value };
|
|
618
|
-
};
|
|
619
|
-
const ids = fn(hwnd); // inspect both the return value and the output parameter
|
|
620
|
-
```
|
|
621
|
-
|
|
622
|
-
As in Python, the value returned by `errcheck` is the result of the call,
|
|
623
|
-
unless it is `args` itself: then the out-params are returned. Here `args`
|
|
624
|
-
is the expanded argument list, with out-params as instances.
|
|
625
|
-
|
|
626
|
-
These bindings have their own hook, independent of any cached `lib.func()`
|
|
627
|
-
binding, and support `callAsync()` with the same output processing and
|
|
628
|
-
per-call hook snapshot. Adapter temporaries stay alive through that processing,
|
|
629
|
-
also when the hook throws.
|
|
630
|
-
|
|
631
|
-
OUT conversion invokes the output instance's `__ctypes_from_outparam__()`.
|
|
632
|
-
By default a builtin scalar yields its value, while a scalar subclass yields
|
|
633
|
-
the instance. Override the method for custom output conversion.
|
|
634
|
-
|
|
635
|
-
Use `{ dir: "inout", name: "value" }`, or tuple flag `3`, to pass an existing
|
|
636
|
-
instance and return that exact instance after C modifies it. INOUT does not
|
|
637
|
-
call `__ctypes_from_outparam__`; positional, named and default arguments use
|
|
638
|
-
the same rule. Mixed outputs preserve parameter order. If `errcheck` returns
|
|
639
|
-
anything other than the original `args`, neither OUT nor INOUT unpacking runs.
|
|
640
|
-
|
|
641
|
-
### Sharing memory with existing buffers
|
|
642
|
-
|
|
643
|
-
```javascript
|
|
644
|
-
// Zero-copy view over a Node Buffer (Python: Structure.from_buffer)
|
|
645
|
-
const r = RECT.from_buffer(packet, 16);
|
|
646
|
-
|
|
647
|
-
// Wrap an externally-allocated pointer (Python: Structure.from_address)
|
|
648
|
-
const r2 = RECT.from_address(malloc_result);
|
|
649
|
-
|
|
650
|
-
// Bind a C-exported global (Python: c_int.in_dll)
|
|
651
|
-
const tz = c_int32.in_dll(libc, "_timezone");
|
|
652
|
-
|
|
653
|
-
// Raw bytes at an address (Python: (c_ubyte * n).from_address(addr));
|
|
654
|
-
// `bytes._buffer` is a Buffer over that memory, as Python's memoryview()
|
|
655
|
-
const bytes = array(c_uint8, 64).from_address(malloc_result);
|
|
656
|
-
const view = new Float32Array(bytes._buffer.buffer, bytes._buffer.byteOffset, 16);
|
|
657
|
-
```
|
|
658
|
-
|
|
659
|
-
Typed pointers read from fields or array elements, and views derived from
|
|
660
|
-
them, retain their known memory owners. Typed assignments and
|
|
661
|
-
`from_buffer_copy()` preserve known pointer references, including overlapping
|
|
662
|
-
and self-copies; replacing a pointer releases its previous reference.
|
|
663
|
-
|
|
664
|
-
Raw copies (`memmove()`, Buffer methods) do not transfer ownership metadata.
|
|
665
|
-
Likewise, `from_address()` given a raw address cannot discover its allocation
|
|
666
|
-
or library: the caller must keep that memory valid. Keeping a known owner
|
|
667
|
-
alive does not take over responsibility for freeing externally allocated
|
|
668
|
-
memory or explicitly releasing callbacks.
|
|
669
|
-
|
|
670
|
-
`memmove()` and `memset()` return the destination address as BigInt, including
|
|
671
|
-
zero-length operations (`0n` for a NULL destination with count zero).
|
|
672
|
-
Counts must be non-negative safe integers. Copies/fills involving JS memory
|
|
673
|
-
still stop at its end; raw native addresses remain the caller's responsibility.
|
|
674
|
-
Scalar `from_buffer()` / `from_buffer_copy()` validate byte size and offset
|
|
675
|
-
before producing an instance and accept Buffer, typed views and ctypes memory.
|
|
676
|
-
|
|
677
|
-
Do not detach (`ArrayBuffer.prototype.transfer()`, a `postMessage` /
|
|
678
|
-
`structuredClone` transfer list) memory passed to a call that is still running:
|
|
679
|
-
a pending `callAsync()`, or the outer call while a callback runs. Native code
|
|
680
|
-
keeps its address and may access memory that now belongs to another
|
|
681
|
-
`ArrayBuffer` or has been released. Node-API cannot prevent the detach, so
|
|
682
|
-
node-ctypes reports it instead. A synchronous call during which a JavaScript
|
|
683
|
-
callback ran throws `argument N: memory was detached ...` after native code
|
|
684
|
-
returns, and a `callAsync()` whose Buffer, typed array, DataView or ArrayBuffer
|
|
685
|
-
argument was detached rejects. The check covers those arguments as passed,
|
|
686
|
-
not addresses stored inside structures or obtained with `addressof()`.
|
|
687
|
-
|
|
688
|
-
### Electron
|
|
689
|
-
|
|
690
|
-
Electron does not allow Buffers over memory that V8 did not allocate, so a
|
|
691
|
-
Buffer _view_ of native memory cannot exist there. node-ctypes detects this
|
|
692
|
-
when it loads (`EXTERNAL_BUFFERS` is `false`) and keeps the same API:
|
|
693
|
-
|
|
694
|
-
- instances on native memory (`from_address`, `in_dll`, `pointer.contents`,
|
|
695
|
-
`p[i]`, pointer fields) work on a copy that is re-read before every access
|
|
696
|
-
and written back after every assignment, so they still see what C writes
|
|
697
|
-
and C sees what JavaScript writes;
|
|
698
|
-
- passed to a C function, `addressof()`, `pointer()`, `memmove()` and
|
|
699
|
-
`memset()`, such an instance uses the original address;
|
|
700
|
-
- the `_buffer` of such an instance is the copy: a typed array or Buffer
|
|
701
|
-
method over it does not read or write native memory. Use the instance
|
|
702
|
-
(`arr[i]`, `s.field`) or `memmove()`.
|
|
703
|
-
|
|
704
|
-
Only the bytes of the accessed field are copied, one native call per read
|
|
705
|
-
or write; instances on ordinary Buffers (`new Point()`, `c_int(5)`) do not
|
|
706
|
-
need this native-memory synchronization. Set `NODE_CTYPES_NO_EXTERNAL_BUFFERS=1`
|
|
707
|
-
to run in this mode on Node.js.
|
|
708
|
-
|
|
709
|
-
### Adapter protocols: `_as_parameter_` and `from_param`
|
|
710
|
-
|
|
711
|
-
```javascript
|
|
712
|
-
// Instance protocol: auto-unwrap on call
|
|
713
|
-
class Handle {
|
|
714
|
-
constructor(h) {
|
|
715
|
-
this._as_parameter_ = h;
|
|
716
|
-
}
|
|
717
|
-
}
|
|
718
|
-
user32.CloseHandle(new Handle(hwnd));
|
|
719
|
-
|
|
720
|
-
// Class protocol: custom conversion in argtypes
|
|
721
|
-
class StrLen extends c_int32 {
|
|
722
|
-
static from_param(s) {
|
|
723
|
-
return typeof s === "string" ? s.length : s;
|
|
724
|
-
}
|
|
725
|
-
}
|
|
726
|
-
const abs = libc.func("abs", c_int32, [StrLen]);
|
|
727
|
-
abs("hello"); // 5
|
|
728
|
-
```
|
|
729
|
-
|
|
730
|
-
As in Python, `from_param` receives the argument as passed (also with
|
|
731
|
-
`CFUNCTYPE` prototypes), its result is converted as the declared type, and
|
|
732
|
-
an error it throws becomes `ArgumentError` (`"argument 1: RangeError: ..."`).
|
|
733
|
-
|
|
734
|
-
Non-pointer scalar CData arguments are read from their backing bytes, not an
|
|
735
|
-
overridden public `.value` getter. Each value is snapshotted before converting
|
|
736
|
-
the next argument, even without `argtypes`. A scalar `from_param` converter may
|
|
737
|
-
return a CData instance of another class when its native scalar kind matches
|
|
738
|
-
the declared type.
|
|
739
|
-
|
|
740
|
-
Objects passed through argument adapters and the objects produced by their
|
|
741
|
-
conversions stay alive while later arguments are converted and until the
|
|
742
|
-
result and `errcheck` have been processed. With `callAsync()`, those temporary
|
|
743
|
-
owners stay alive until its Promise settles. The native worker also retains
|
|
744
|
-
memory passed by value or as an integer address, including values materialized
|
|
745
|
-
by getters.
|
|
746
|
-
|
|
747
|
-
`_as_parameter_` chains are resolved recursively, including results of
|
|
748
|
-
`from_param`, with intermediate owners retained. As in CPython, an adapter may
|
|
749
|
-
be visited again when a stateful getter eventually returns a usable value;
|
|
750
|
-
object identity alone is not rejected as a cycle, and there is no fixed
|
|
751
|
-
128-step limit. Non-terminating recursion raises an argument conversion error.
|
|
752
|
-
The available recursion depth and stack-error wording follow the JavaScript
|
|
753
|
-
runtime, rather than CPython's runtime-specific recursion guard.
|
|
754
|
-
|
|
755
|
-
This only covers the call: if C stores a pointer for later use, or returns a
|
|
756
|
-
pointer into an argument's memory, keep the source object referenced for as
|
|
757
|
-
long as that pointer is used. Callbacks still require explicit `.release()`.
|
|
758
|
-
|
|
759
|
-
### Big-endian structures
|
|
760
|
-
|
|
761
|
-
```javascript
|
|
762
|
-
class NetHeader extends BigEndianStructure {
|
|
763
|
-
static _fields_ = [
|
|
764
|
-
["magic", c_uint32],
|
|
765
|
-
["length", c_uint32],
|
|
766
|
-
];
|
|
767
|
-
}
|
|
768
|
-
const h = new NetHeader();
|
|
769
|
-
h.magic = 0x12345678; // stored as 12 34 56 78 on the wire
|
|
770
|
-
```
|
|
771
|
-
|
|
772
|
-
`LittleEndianStructure`, `BigEndianUnion`, `LittleEndianUnion` work the
|
|
773
|
-
same way. Byte order is per-class — nested structs keep their own.
|
|
774
|
-
|
|
775
|
-
Primitive arrays also follow their containing class's byte order, recursively
|
|
776
|
-
for multidimensional arrays, including floats and wide-character arrays.
|
|
777
|
-
Arrays of structures keep the element structure's own byte order. The same
|
|
778
|
-
array type can be shared with native/little-endian containers without being
|
|
779
|
-
modified. Raw Buffer and typed-memory copies still copy bytes, not values
|
|
780
|
-
converted between byte orders.
|
|
781
|
-
|
|
782
|
-
### TypeScript
|
|
783
|
-
|
|
784
|
-
Argument and return types are inferred from declared type classes such as
|
|
785
|
-
`c_int32` and `c_size_t`. A literal tuple (`as const`) preserves argument types:
|
|
786
|
-
|
|
787
|
-
```ts
|
|
788
|
-
const libc = new CDLL(null);
|
|
789
|
-
const strlen = libc.func("strlen", c_size_t, [c_char_p] as const);
|
|
790
|
-
const n: bigint = strlen("hello"); // typed as bigint, not any
|
|
791
|
-
```
|
|
792
|
-
|
|
793
|
-
`static _fields_ = [["x", c_int32]]` compiles as written in Python (no
|
|
794
|
-
`as const`). For typed struct fields use `defineStruct` instead of
|
|
795
|
-
`extends Structure`:
|
|
796
|
-
|
|
797
|
-
```ts
|
|
798
|
-
class Point extends defineStruct({ x: c_int32, y: c_int32 }) {
|
|
799
|
-
distance() {
|
|
800
|
-
return Math.sqrt(this.x ** 2 + this.y ** 2);
|
|
801
|
-
}
|
|
802
|
-
}
|
|
803
|
-
const p = new Point({ x: 3, y: 4 }); // p.x, p.y typed as number
|
|
804
|
-
```
|
|
805
|
-
|
|
806
|
-
`struct()` / `union()` fields, `POINTER()` targets and arrays of numeric
|
|
807
|
-
types are typed too; a `null` return type is `void`:
|
|
808
|
-
|
|
809
|
-
```ts
|
|
810
|
-
const PointDef = struct({ x: c_int32, y: c_double });
|
|
811
|
-
PointDef.get(buf, "y"); // number
|
|
812
|
-
POINTER(c_int32).fromAddress(addr)[0]; // number (.contents: c_int32 instance)
|
|
813
|
-
array(c_int32, 4).create([1, 2, 3, 4])[0]; // number
|
|
814
|
-
libc.func("srand", null, [c_uint32]); // returns undefined
|
|
815
|
-
```
|
|
816
|
-
|
|
817
|
-
---
|
|
818
|
-
|
|
819
|
-
## API reference
|
|
820
|
-
|
|
821
|
-
### Primitive types
|
|
822
|
-
|
|
823
|
-
| Type | Aliases | Size | Notes |
|
|
824
|
-
| ----------- | ------------- | -------- | --------------------------------------------- |
|
|
825
|
-
| `c_int8` | `c_byte` | 1 | |
|
|
826
|
-
| `c_uint8` | `c_ubyte` | 1 | |
|
|
827
|
-
| `c_int16` | `c_short` | 2 | |
|
|
828
|
-
| `c_uint16` | `c_ushort` | 2 | |
|
|
829
|
-
| `c_int32` | `c_int` | 4 | |
|
|
830
|
-
| `c_uint32` | `c_uint` | 4 | |
|
|
831
|
-
| `c_int64` | `c_longlong` | 8 | |
|
|
832
|
-
| `c_uint64` | `c_ulonglong` | 8 | |
|
|
833
|
-
| `c_long` | | platform | 4 on Windows, 8 on Unix 64-bit; BigInt values |
|
|
834
|
-
| `c_ulong` | | platform | mirrors `c_long`; BigInt values |
|
|
835
|
-
| `c_float` | | 4 | |
|
|
836
|
-
| `c_double` | | 8 | |
|
|
837
|
-
| `c_bool` | | 1 | |
|
|
838
|
-
| `c_char` | | 1 | 1-char string (Python `bytes`); also 0..255 |
|
|
839
|
-
| `c_wchar` | | 2 or 4 | 1-char string; 2 on Windows, 4 on Unix |
|
|
840
|
-
| `c_char_p` | | pointer | `char *` (NUL-terminated) |
|
|
841
|
-
| `c_wchar_p` | | pointer | `wchar_t *` (NUL-terminated wide) |
|
|
842
|
-
| `c_void_p` | `c_voidp` | pointer | opaque pointer / `HANDLE` |
|
|
843
|
-
| `c_time_t` | | 8 | `time_t` (`SIZEOF_TIME_T`) |
|
|
844
|
-
| `c_size_t` | | pointer | pointer-sized unsigned integer |
|
|
845
|
-
| `c_ssize_t` | | pointer | pointer-sized signed integer |
|
|
846
|
-
| `HRESULT` | | 4 | `c_int32` subclass — auto-raise on `OleDLL` |
|
|
847
|
-
|
|
848
|
-
Plus the Win32 types, structures and pointer types of `ctypes.wintypes` under `wintypes`.
|
|
849
|
-
|
|
850
|
-
### Library loaders
|
|
851
|
-
|
|
852
|
-
- `CDLL(name, mode?)` or `CDLL(name, { mode?, use_errno?, use_last_error? })` — C calling convention; `mode` is the `dlopen` flag (`RTLD_GLOBAL`, `RTLD_LOCAL`, `DEFAULT_MODE`)
|
|
853
|
-
- `WinDLL(name, ...)` — Windows `__stdcall`
|
|
854
|
-
- `OleDLL(name, ...)` — like `WinDLL`, auto-raises on negative `HRESULT`
|
|
855
|
-
- `find_library(name)` — cross-platform name resolution
|
|
856
|
-
- `cdll.<libname>`, `windll.<libname>` — lazy namespaces; `cdll.LoadLibrary(name)`, `new LibraryLoader(CDLL)`
|
|
857
|
-
- Functions without `restype` return `c_int`; without `argtypes` the arguments are converted from their JS values (as Python)
|
|
858
|
-
|
|
859
|
-
### Type constructors
|
|
860
|
-
|
|
861
|
-
- `struct({...})` / `class extends Structure` — composite struct types
|
|
862
|
-
- `class extends Union` — union types
|
|
863
|
-
- `array(type, n)` / `ARRAY(type, n)` — Python's `type * n`; callable: `array(c_int, 3)(1, 2, 3)`; elements can be simple types, structures, arrays, `POINTER(T)` and `CFUNCTYPE` types
|
|
864
|
-
- `POINTER(type)` — pointer-to-type; accepts a thunk `POINTER(() => T)`
|
|
865
|
-
- `pointer(instance)` — pointer to an existing c-data instance
|
|
866
|
-
- `CFUNCTYPE(restype, ...argtypes)` — function pointer type: `proto(jsFn)` (callback), `proto(address)`, `proto([name, lib], paramflags?)` (Python: `proto((name, dll), paramflags)`)
|
|
867
|
-
- `WINFUNCTYPE(restype, ...argtypes)` — `__stdcall` callback type
|
|
868
|
-
- `defineStruct({...})` — typed-TS variant of `struct`
|
|
869
|
-
|
|
870
|
-
### Memory & introspection
|
|
871
|
-
|
|
872
|
-
- `sizeof(type)` / `alignment(type)` — in bytes
|
|
873
|
-
- `addressof(obj)` → BigInt
|
|
874
|
-
- `byref(obj, byteOffset = 0)` — lightweight reference with a signed byte offset
|
|
875
|
-
- `cast(ptr, type)` — reinterpret a pointer as another type
|
|
876
|
-
- `memmove(dst, src, n)` / `memset(dst, val, n)` — buffers, ctypes instances, pointers or addresses; return the destination address as BigInt
|
|
877
|
-
- `readValue(ptr, type, offset?)` / `writeValue(ptr, type, val, offset?)`
|
|
878
|
-
- `create_string_buffer(init, size?)` / `c_buffer` / `create_unicode_buffer(init, size?)` — with `.value` (and `.raw`)
|
|
879
|
-
- `string_at(addr, size?)` / `wstring_at(addr, size?)` — exactly `size` units, or up to the NUL
|
|
880
|
-
|
|
881
|
-
With an explicit byte count, `string_at` returns a lossless Latin1 string:
|
|
882
|
-
`Buffer.from(string_at(addr, n), "latin1")` recovers all `n` original bytes,
|
|
883
|
-
including embedded NUL and invalid UTF-8. Without a count it retains the
|
|
884
|
-
UTF-8 text representation. `wstring_at` counts native wide-character units.
|
|
885
|
-
|
|
886
|
-
### Error slots
|
|
887
|
-
|
|
888
|
-
- `get_errno()` / `set_errno(v)`
|
|
889
|
-
- `GetLastError()` / `SetLastError(v)` / `FormatError(code)`, Python names `get_last_error()` / `set_last_error(v)` (all platforms)
|
|
890
|
-
- `ArgumentError` — raised for arguments that do not match `argtypes` (`"argument N: TypeError: ..."`)
|
|
891
|
-
- Per-library: `lib.get_last_error()` / `lib.get_errno()`
|
|
892
|
-
|
|
893
|
-
### Structure helpers
|
|
894
|
-
|
|
895
|
-
- `T.from_buffer(buf, offset?)` — zero-copy view
|
|
896
|
-
- `T.from_buffer_copy(buf, offset?)` — independent copy
|
|
897
|
-
- `T.from_address(addr)` — wrap raw pointer
|
|
898
|
-
- `T.in_dll(lib, name)` — bind to exported global
|
|
899
|
-
- `T._as_parameter_` / `T.from_param(v)` — adapter protocols
|
|
900
|
-
|
|
901
|
-
---
|
|
902
|
-
|
|
903
|
-
## Python ctypes parity & differences
|
|
904
|
-
|
|
905
|
-
### Supported Python ctypes behavior
|
|
906
|
-
|
|
907
|
-
Structs, unions, bit fields (`_layout_` `"gcc-sysv"` / `"ms"`), anonymous
|
|
908
|
-
fields, `_pack_`, `_align_`, subclasses of structures and unions, nested layouts,
|
|
909
|
-
structures and unions by value (a struct `restype` returns an instance),
|
|
910
|
-
arrays (also of arrays, pointers and function pointers), pointers and
|
|
911
|
-
pointer arithmetic (also `POINTER(POINTER(T))`), callbacks (`CFUNCTYPE` /
|
|
912
|
-
`WINFUNCTYPE`, also as struct fields), `prototype((name, dll), paramflags)`,
|
|
913
|
-
`from_buffer` / `from_buffer_copy` / `from_address` / `in_dll`,
|
|
914
|
-
`_as_parameter_` / `from_param`, `paramflags` out-params, `errcheck`,
|
|
915
|
-
`use_errno` / `use_last_error`, `OleDLL` + `HRESULT` auto-raise,
|
|
916
|
-
`BigEndianStructure` / `LittleEndianStructure` and union variants,
|
|
917
|
-
`ctypes.wintypes`, keepalive of objects assigned to fields (`_objects`).
|
|
918
|
-
|
|
919
|
-
### Differences
|
|
920
|
-
|
|
921
|
-
- **Callbacks must be released** with `.release()`. GC cannot detect when
|
|
922
|
-
C code still holds the pointer; relying on it causes use-after-free.
|
|
923
|
-
- **No automatic memory management** for returned pointers.
|
|
924
|
-
- **Both class and functional syntax**: `class extends Structure`
|
|
925
|
-
(Python-like) and `struct({...})` (functional) are both supported.
|
|
926
|
-
- **Use type classes** such as `c_int32`, rather than string names such as
|
|
927
|
-
`"int32"`, for the Python-compatible, typed API.
|
|
928
|
-
- **`bytes` are JS strings**: `c_char` values, `c_char * n` arrays and
|
|
929
|
-
fields, `c_char_p` and `create_string_buffer().value` use strings (UTF-8)
|
|
930
|
-
where Python uses `bytes`; `.raw` is a `Buffer`.
|
|
931
|
-
- **NULL pointers are `null`**, where Python returns a falsy pointer object.
|
|
932
|
-
- **`c_char_p` / `c_wchar_p` accept raw addresses** (BigInt/number) as
|
|
933
|
-
argtypes. Python is stricter (raises `TypeError` on `int`). For
|
|
934
|
-
portable code use `c_void_p` there; both libraries accept it.
|
|
935
|
-
- **`get_last_error()` / `set_last_error()`** exist on every platform
|
|
936
|
-
(Python: Windows only), so the same code runs everywhere.
|
|
937
|
-
- **64-bit and pointer-sized integers** (`c_int64`, `c_uint64`,
|
|
938
|
-
`c_size_t`, `c_ssize_t`) also accept `null` (as 0) and a `Buffer`
|
|
939
|
-
or `ArrayBuffer` (as its address) as arguments.
|
|
940
|
-
- **Variadic arguments follow the C promotions**: a `c_float`, `c_int8`,
|
|
941
|
-
`c_char`, … instance passed beyond `argtypes` is passed as `double` /
|
|
942
|
-
`int`, where Python fails (`ffi_prep_cif_var failed`).
|
|
943
|
-
- **A plain object is accepted for a structure argument** passed by value
|
|
944
|
-
(fields by name).
|
|
945
|
-
- **`c_wchar` also accepts a code point** (`new c_wchar(0x4E2D)`), where
|
|
946
|
-
Python requires a 1-character string.
|
|
947
|
-
- **`memmove()` / `memset()` stop at the end of JS memory** (Buffer, typed
|
|
948
|
-
array, `ArrayBuffer`) instead of writing past it.
|
|
949
|
-
- **Integer types reject non-integral numbers** (`3.7`, `NaN`) as Python
|
|
950
|
-
rejects floats; JS has no int/float distinction, so `3.0` is accepted.
|
|
951
|
-
- **Floating-point scalars accept BigInt in the range `-2**63` to `2**64-1`**,
|
|
952
|
-
converted to a JS number; larger BigInts raise a range error. This applies
|
|
953
|
-
consistently to constructors, fields and function arguments.
|
|
954
|
-
- **Array instances are Buffers whose Array methods work on the elements**
|
|
955
|
-
(`slice`, `map`, `includes`, …, as Python sequences); the Buffer methods
|
|
956
|
-
(`readInt32LE`, `subarray`, …) work on the bytes.
|
|
957
|
-
- **Array index reads follow JavaScript bounds behavior**: out-of-range
|
|
958
|
-
indices return `undefined`; negative indices do not wrap around as in Python.
|
|
959
|
-
- **Unions by value on x86-64 System V** are passed with the ABI rules;
|
|
960
|
-
Python passes them in the wrong registers (libffi#33).
|
|
961
|
-
- **Structure/Union fields are accessors of the class**, as Python fields
|
|
962
|
-
are descriptors (`vars(s)` is empty): `Object.keys(s)` and `{ ...s }` do
|
|
963
|
-
not list them; use `s.toObject()`. `JSON.stringify(s)` and
|
|
964
|
-
`console.log(s)` show the fields.
|
|
965
|
-
|
|
966
|
-
### Not supported
|
|
967
|
-
|
|
968
|
-
- **`ctypes.resize(instance, size)`** — Structure/Union instances use a
|
|
969
|
-
Node `Buffer`, and Buffers aren't resizable in place.
|
|
970
|
-
Work-around: `new MyStruct(myBuffer)` with a pre-sized buffer.
|
|
971
|
-
- **`c_longdouble`** (80/128-bit float, `ffi_type_longdouble`) — rarely
|
|
972
|
-
used; use a native wrapper that converts to supported types, or access
|
|
973
|
-
storage through pointers/bytes. Declaring a `long double` ABI value as
|
|
974
|
-
`c_double` is not a portable substitute.
|
|
975
|
-
|
|
976
|
-
### Migrating from 1.x
|
|
977
|
-
|
|
978
|
-
2.0 follows Python ctypes more closely. Code relying on the 1.x behavior
|
|
979
|
-
needs these changes:
|
|
980
|
-
|
|
981
|
-
| 1.x | 2.0 (as Python) |
|
|
982
|
-
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
983
|
-
| `ptr.contents` returned the value | returns a live instance: `ptr.contents.value` (simple types), `ptr.contents.x` (structs); `ptr[0]` still returns the value |
|
|
984
|
-
| `POINTER(T)` restype returned a `bigint` address | returns a pointer object (`null` for NULL); use `.address` for the number |
|
|
985
|
-
| NULL `POINTER` struct fields were pointer objects | they are `null` |
|
|
986
|
-
| `c_char` values were numbers | 1-character strings; `c_char * n` fields read/write as strings |
|
|
987
|
-
| invalid `c_char` values were truncated | `TypeError` (`"one character bytes, bytearray, or an integer in range(256) expected, not ..."`) |
|
|
988
|
-
| wrong argument types raised `TypeError` | raise `ArgumentError` (a `TypeError` subclass), message `"argument N: TypeError: ..."` |
|
|
989
|
-
| unsupported pointer arguments (functions, plain objects) passed NULL | raise `ArgumentError` (`"'function' object cannot be interpreted as ctypes.c_void_p"`) |
|
|
990
|
-
| functions without `restype` / `argtypes` | default `restype` is `c_int`; without `argtypes` the call uses the fixed-argument ABI |
|
|
991
|
-
| `create_string_buffer(init)` | also takes `size` and returns a Buffer with `.value` / `.raw` |
|
|
992
|
-
| `c_long` / `c_ulong` (and `BOOL`, `LONG`, `DWORD`, `ULONG`) fields and `.value` were numbers on Windows | `BigInt` on every platform, like function results; writes accept numbers and BigInt |
|
|
993
|
-
| `wintypes.CHAR` was `c_ubyte`; `LPDWORD`, `PDWORD`, `LPBYTE`, `PBYTE`, `PHKEY` were `c_void_p` | as Python: `CHAR = c_char` and pointer types are `POINTER(T)` (fields and results are pointer objects) |
|
|
994
|
-
| `string_at(addr, n)` / `wstring_at(addr, n)` stopped at the first NUL | read exactly `n` units; without `n`, `wstring_at` reads up to the NUL (no 256-character limit) |
|
|
73
|
+
- [Getting started](guides/getting-started.md) — installation, supported platforms, building from source
|
|
74
|
+
- [Libraries and functions](guides/functions.md) — loading libraries, declaring and calling functions, adapters
|
|
75
|
+
- [Types](guides/types.md) — the C types, their sizes and JavaScript values, scalar subclasses
|
|
76
|
+
- [Structures, unions and arrays](guides/structures.md) — layouts, bit fields, packing, byte order
|
|
77
|
+
- [Pointers and memory](guides/memory.md) — pointers, `cast`, shared buffers, native memory, Electron
|
|
78
|
+
- [Callbacks](guides/callbacks.md) — C calling JavaScript, also from other threads
|
|
79
|
+
- [Asynchronous calls](guides/async.md) — `callAsync` and the `Executor`
|
|
80
|
+
- [Errors and results](guides/errors.md) — `errno`, `GetLastError`, `errcheck`, output parameters
|
|
81
|
+
- [Windows API](guides/windows.md) — `wintypes`
|
|
82
|
+
- [TypeScript](guides/typescript.md) — typed signatures and structures
|
|
83
|
+
- [Python ctypes parity](guides/python.md) — supported behavior, differences, migrating from 1.x
|
|
84
|
+
- [Coming from Koffi](guides/from-koffi.md) — the Koffi API mapped to node-ctypes
|
|
85
|
+
- [Performance](guides/performance.md) — comparisons with Koffi and how to run them
|
|
86
|
+
- [Building, testing and internals](guides/contributing.md) — tests, native backends, release validation
|
|
995
87
|
|
|
996
88
|
---
|
|
997
89
|
|
|
@@ -1012,245 +104,6 @@ Each example in `examples/` has its own README; see the [index](examples/README.
|
|
|
1012
104
|
|
|
1013
105
|
---
|
|
1014
106
|
|
|
1015
|
-
## Tests & docs
|
|
1016
|
-
|
|
1017
|
-
From the repository root, `npm --prefix tests test` first builds a small C library (`tests/fixtures/`, into
|
|
1018
|
-
`build/fixture/`) used by the tests of structures by value, array parameters
|
|
1019
|
-
and reentrant calls; `npm run build:test-fixture` builds it alone. Matched
|
|
1020
|
-
Python/JavaScript contracts live under `tests/cpython_parity/`, divided by domain,
|
|
1021
|
-
and load the same library. Node-specific async, representation and GC checks
|
|
1022
|
-
live under `tests/node_specific/`; genuine Python-only scheduling checks live
|
|
1023
|
-
under `tests/python_specific/`. The former `common/` and `windows/` suites have
|
|
1024
|
-
been migrated into these domains.
|
|
1025
|
-
|
|
1026
|
-
Paired JavaScript uses the Python-shaped API: `Structure`/`Union` classes,
|
|
1027
|
-
`ARRAY`, library attributes with `argtypes`/`restype`, and `CFUNCTYPE` bindings.
|
|
1028
|
-
The structural guard checks neighboring files and matching class/method IDs
|
|
1029
|
-
using the existing TypeScript parser and Python AST; runtime assertions remain
|
|
1030
|
-
independent checks against CPython, not a claim based on file names alone.
|
|
1031
|
-
|
|
1032
|
-
```bash
|
|
1033
|
-
npm install
|
|
1034
|
-
npm run build
|
|
1035
|
-
npm --prefix tests install
|
|
1036
|
-
npm --prefix tests test # functional/parity tests
|
|
1037
|
-
NODE_CTYPES_NO_EXTERNAL_BUFFERS=1 npm --prefix tests test # mirrored native memory
|
|
1038
|
-
npm --prefix tests run test:parity # matched CPython and JS contracts
|
|
1039
|
-
npm --prefix tests run test:parity:check # paired file/case/discovery/style guard
|
|
1040
|
-
npm --prefix tests run test:python # all Python references
|
|
1041
|
-
npm run test:types # TypeScript declarations
|
|
1042
|
-
npm run docs # TypeDoc API site in docs/
|
|
1043
|
-
npm run docs:serve # preview
|
|
1044
|
-
```
|
|
1045
|
-
|
|
1046
|
-
See the [test suite guide](tests/README.md) for paired-case conventions,
|
|
1047
|
-
runtime differences and focused commands.
|
|
1048
|
-
|
|
1049
|
-
### Performance comparisons
|
|
1050
|
-
|
|
1051
|
-
There are two JavaScript comparisons, both against another FFI library.
|
|
1052
|
-
From the repository root, after building node-ctypes:
|
|
1053
|
-
|
|
1054
|
-
```bash
|
|
1055
|
-
npm --prefix tests install # includes Koffi
|
|
1056
|
-
npm run build:test-fixture # shared C functions for both libraries
|
|
1057
|
-
npm run bench:koffi # node-ctypes vs Koffi; Node 24+
|
|
1058
|
-
npm run bench:ffi # node-ctypes vs node:ffi; Node 26+
|
|
1059
|
-
```
|
|
1060
|
-
|
|
1061
|
-
The private test package explicitly approves the install script for Koffi 3.3.8.
|
|
1062
|
-
When upgrading Koffi, review the new version before updating that approval with
|
|
1063
|
-
`npm --prefix tests install-scripts approve koffi`; future versions are not
|
|
1064
|
-
automatically authorized.
|
|
1065
|
-
|
|
1066
|
-
`bench:ffi` adds `--experimental-ffi` automatically. Both comparisons
|
|
1067
|
-
print a table grouped by workload and automatically generate HTML reports:
|
|
1068
|
-
|
|
1069
|
-
- `tests/benchmarks/results/koffi.html`
|
|
1070
|
-
- `tests/benchmarks/results/node-ffi.html`
|
|
1071
|
-
|
|
1072
|
-
These paths are relative to the repository root, regardless of the working
|
|
1073
|
-
directory. Each successful run replaces its previous report; generated results
|
|
1074
|
-
are ignored by Git. Open the HTML file directly in a browser: it is responsive
|
|
1075
|
-
and self-contained, with native HTML/CSS bar charts and no browser JavaScript,
|
|
1076
|
-
external resources or server requirements.
|
|
1077
|
-
|
|
1078
|
-
| Column | Meaning |
|
|
1079
|
-
| ------------------------ | ----------------------------------------------------- |
|
|
1080
|
-
| Case | The same operation and inputs for both libraries |
|
|
1081
|
-
| node-ctypes / competitor | Median time +/- MAD (dispersion), in ns per operation |
|
|
1082
|
-
| Ratio | node-ctypes time divided by competitor time |
|
|
1083
|
-
|
|
1084
|
-
A ratio of `0.50x` means node-ctypes took half the time; `2.00x` means it
|
|
1085
|
-
took twice the time. Lower times are better. There is no overall score
|
|
1086
|
-
combining unrelated calls, memory access and asynchronous scheduling.
|
|
1087
|
-
In the charts, **shorter bars are better**. Each workload group shares a linear
|
|
1088
|
-
scale starting at zero; different groups use different scales. Bars show
|
|
1089
|
-
medians, with +/- MAD whiskers (not confidence intervals). Each library also
|
|
1090
|
-
shows its total measured operation count and elapsed time across the samples.
|
|
1091
|
-
|
|
1092
|
-
Reports record library/runtime versions, CPU, OS/kernel, buffer mode, start/
|
|
1093
|
-
finish timestamps and Git revision/working-tree status. Missing CPU or Git
|
|
1094
|
-
metadata produces an explicit warning rather than invented values.
|
|
1095
|
-
|
|
1096
|
-
Both comparisons cover narrow scalars, mixed GP/FP stack arguments, short/long
|
|
1097
|
-
strings, buffer arguments, field reads, scalar callbacks and 64-callback C loops.
|
|
1098
|
-
The node:ffi comparison includes 25 workloads. Koffi also covers structures by value,
|
|
1099
|
-
variadic calls and async calls with 1/8 calls in flight. Cases without an
|
|
1100
|
-
equivalent documented node:ffi API are listed as **not compared**, not
|
|
1101
|
-
emulated with a different native signature.
|
|
1102
|
-
|
|
1103
|
-
Inferred rows omit node-ctypes `argtypes`, while both competitors use explicit
|
|
1104
|
-
fixed signatures for the same C functions: these rows include node-ctypes
|
|
1105
|
-
inference overhead, not equivalent automatic-inference APIs.
|
|
1106
|
-
The node:ffi bool row passes numeric `1` and compares normalized Number results:
|
|
1107
|
-
node:ffi represents bool arguments/results as uint8 values, whereas node-ctypes
|
|
1108
|
-
returns a JavaScript Boolean. Koffi's bool row uses Boolean input/output.
|
|
1109
|
-
The thread-safe scalar callback rows measure node-ctypes dispatch on its host
|
|
1110
|
-
thread against a competitor callback on the same thread, not cross-thread handoff.
|
|
1111
|
-
The C-loop times are per batch of 64 completed callbacks, not per callback.
|
|
1112
|
-
|
|
1113
|
-
The `CFUNCTYPE` rows measure calls through an already-bound node-ctypes
|
|
1114
|
-
prototype, against an independently bound competitor function with the same
|
|
1115
|
-
C signature. Bindings are separate to avoid sharing optimization feedback
|
|
1116
|
-
with the direct-call rows. These cases do not include prototype construction
|
|
1117
|
-
or callback registration.
|
|
1118
|
-
|
|
1119
|
-
Both sides call the same C fixture and verify results before/after timing.
|
|
1120
|
-
String contents are encoded on every call; node-ctypes reuses scratch storage,
|
|
1121
|
-
not previously encoded strings. Measurements describe warmed repeated calls,
|
|
1122
|
-
not cold-start allocation costs.
|
|
1123
|
-
String lengths, narrow/inferred-stack i64 results and C-loop sums are compared
|
|
1124
|
-
as Numbers, including conversion where the API returns BigInt; wide integers
|
|
1125
|
-
are BigInt in both APIs. Structures are plain
|
|
1126
|
-
objects. Async times include scheduling and are reported per completed call,
|
|
1127
|
-
with the concurrency shown in the case name.
|
|
1128
|
-
|
|
1129
|
-
Defaults are nine samples of at least 250 ms per library after warmup,
|
|
1130
|
-
alternating library order. Each native signature has a separate call-site to
|
|
1131
|
-
avoid mixing V8 optimization feedback between cases.
|
|
1132
|
-
Each row is printed when its measurements finish.
|
|
1133
|
-
Run comparisons serially, not concurrently. Optional arguments:
|
|
1134
|
-
|
|
1135
|
-
```bash
|
|
1136
|
-
npm run bench:koffi -- --filter string,callback
|
|
1137
|
-
npm run bench:ffi -- --samples 11 --duration 500
|
|
1138
|
-
npm run bench:koffi -- --output comparison.json
|
|
1139
|
-
```
|
|
1140
|
-
|
|
1141
|
-
`--output comparison.json` additionally saves medians, dispersion and all sample
|
|
1142
|
-
durations/operation counts as JSON, and writes `comparison.html` next to it
|
|
1143
|
-
instead of the default HTML report. Parent directories are created automatically.
|
|
1144
|
-
HTML generation runs only after all measurements finish.
|
|
1145
|
-
`benchmark_koffi.js` and `benchmark_node_ffi.js` define the actual side-by-side
|
|
1146
|
-
comparisons; `runner.js` shares timing, table output and HTML generation without
|
|
1147
|
-
extra dependencies or a separate renderer script. Benchmarks are not run by the
|
|
1148
|
-
functional/parity test suite.
|
|
1149
|
-
|
|
1150
|
-
### Native backends and upstream libffi
|
|
1151
|
-
|
|
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:
|
|
1167
|
-
|
|
1168
|
-
| Files | Responsibility |
|
|
1169
|
-
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
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 |
|
|
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 |
|
|
1173
|
-
| [libffi_types.cc](./src/libffi_types.cc), [libffi_types.h](./src/libffi_types.h) | Primitive mapping and aggregate descriptor factories |
|
|
1174
|
-
| [libffi_type_cache.h](./src/libffi_type_cache.h) | Concrete owned aggregate cache used by layout metadata |
|
|
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 |
|
|
1176
|
-
| [libffi_callback.cc](./src/libffi_callback.cc), [libffi_callback.h](./src/libffi_callback.h) | Closure preparation, allocation and release |
|
|
1177
|
-
| [function.cc](./src/function.cc), [function.h](./src/function.h) | Node-API call orchestration, marshalling, hooks and sync/async ownership |
|
|
1178
|
-
| [callback.cc](./src/callback.cc), [callback.h](./src/callback.h) | Shared callback conversions, TSFN delivery, native-context hooks and lifetime |
|
|
1179
|
-
|
|
1180
|
-
CMake discovers native files with `file(GLOB_RECURSE ... CONFIGURE_DEPENDS ...)`.
|
|
1181
|
-
The public layouts retain their physical size/alignment; the libffi descriptor
|
|
1182
|
-
cache in `layout.h` is intentionally concrete rather than ABI-agnostic.
|
|
1183
|
-
High-level callback snapshot pooling and cached struct/array readers remain:
|
|
1184
|
-
slices are never recycled, retained views have independent bytes and identity,
|
|
1185
|
-
and custom getters, mirrored synchronization and Node-API ownership are preserved.
|
|
1186
|
-
|
|
1187
|
-
**Temporary dependency pin.** The unmodified
|
|
1188
|
-
[libffi submodule](https://github.com/libffi/libffi/tree/d02afc25e8ea3aac9e78e227748e1fd7c9f14c82) is pinned to upstream commit
|
|
1189
|
-
[`d02afc25e8ea3aac9e78e227748e1fd7c9f14c82`](https://github.com/libffi/libffi/commit/d02afc25e8ea3aac9e78e227748e1fd7c9f14c82),
|
|
1190
|
-
after the v3.8.0 release. Generated version fields still report 3.8.0; the
|
|
1191
|
-
gitlink, not that version string, identifies the exact dependency source.
|
|
1192
|
-
This includes the Darwin GP-composite stack-slot
|
|
1193
|
-
[fix](https://github.com/libffi/libffi/commit/2472245a3430b9d24f085b7654e896e074bceb82)
|
|
1194
|
-
and its [compiler/ABI guard adjustment](https://github.com/libffi/libffi/commit/3365ad8b968a9b742922b6f1188462fe6ce142ec):
|
|
1195
|
-
small GP composites use aligned, whole-word stack slots in outgoing calls and
|
|
1196
|
-
closures, without widening ctypes buffers or changing scalar/HFA packing.
|
|
1197
|
-
This follows the compiler's C ABI rather than reproducing broken padding in
|
|
1198
|
-
older libffi builds, including those used by some Python installations.
|
|
1199
|
-
|
|
1200
|
-
Return to an official tag containing these fixes when released. After changing
|
|
1201
|
-
the submodule revision, run `npm run generate-ffi-headers`, rebuild and repeat
|
|
1202
|
-
the ABI/parity tests. Do not patch the vendored libffi internals.
|
|
1203
|
-
|
|
1204
|
-
**Darwin ARM64 upstream limitation.** When all GP registers are
|
|
1205
|
-
occupied, a byte-aligned non-HFA struct larger than 16 bytes after a narrow
|
|
1206
|
-
stack scalar can still misalign its indirect pointer and subsequent arguments.
|
|
1207
|
-
A callee dereferencing that pointer can crash. The upstream update does not
|
|
1208
|
-
resolve this case and this project does not disguise it by altering layouts.
|
|
1209
|
-
[test_function_abi.js](./tests/node_specific/test_function_abi.js) retains a
|
|
1210
|
-
safe C stack-tag probe for sync/async calls, temporarily skipped only on Darwin
|
|
1211
|
-
ARM64 until an upstream fix is available. The test remains active on other
|
|
1212
|
-
targets. Other supported GP/HFA/large-aggregate cases and ordinary/thread-safe
|
|
1213
|
-
callback ABI tests run normally.
|
|
1214
|
-
|
|
1215
|
-
**Windows ARM64 variadic HFA limitation.** A named HFA argument containing four
|
|
1216
|
-
doubles (32 bytes) in a variadic call triggers an access violation in upstream
|
|
1217
|
-
libffi, independently of the Node wrapper. Avoid this signature until an upstream
|
|
1218
|
-
fix is available. Its regression is temporarily skipped only on Windows ARM64
|
|
1219
|
-
and still runs on other targets. Native calling behavior is unchanged.
|
|
1220
|
-
|
|
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,
|
|
1224
|
-
and async inferred/variadic calls own CIFs prepared on the JavaScript thread.
|
|
1225
|
-
Workers retain the parent function, metadata and library through completion.
|
|
1226
|
-
To compare the direct-enabled and libffi-only builds, follow the
|
|
1227
|
-
[native validation commands](./tests/README.md#native-backends-and-abi-regressions).
|
|
1228
|
-
|
|
1229
|
-
### Release validation
|
|
1230
|
-
|
|
1231
|
-
The workflow retains the eight Node 24 native build targets (Windows/macOS,
|
|
1232
|
-
x64/ARM64, and Linux glibc/musl). C++20 conformance is checked with
|
|
1233
|
-
`-pedantic-errors` on GCC/Clang and `/permissive-` on MSVC; vendor optimization
|
|
1234
|
-
and the node-addon-api integration remain unchanged.
|
|
1235
|
-
|
|
1236
|
-
Three runtime-control jobs reuse the built artifacts on Node 26 without
|
|
1237
|
-
rebuilding the addon, running the functional parity suite normally and with
|
|
1238
|
-
mirrored buffers. A Linux job runs the focused Python 3.15
|
|
1239
|
-
reference tests in addition to the Python 3.14 reference coverage.
|
|
1240
|
-
|
|
1241
|
-
The package assembler requires all eight nonempty binaries and includes
|
|
1242
|
-
declarations, README, changelog and license. It fails on missing/unknown
|
|
1243
|
-
artifacts or a stale output directory. Publish depends on the runtime gates,
|
|
1244
|
-
requires a pushed tag matching the manifest version exactly, and uses `next`
|
|
1245
|
-
for prereleases instead of `latest`. Manual workflow runs never publish.
|
|
1246
|
-
These are configured gates, not a substitute for a successful native CI run.
|
|
1247
|
-
|
|
1248
|
-
`npm --prefix tests test` builds the fixture and runs the suite;
|
|
1249
|
-
`npm --prefix tests run test:js` reuses an already-built fixture/addon.
|
|
1250
|
-
Both use the documented `--test-timeout` runner option.
|
|
1251
|
-
|
|
1252
|
-
---
|
|
1253
|
-
|
|
1254
107
|
## License
|
|
1255
108
|
|
|
1256
109
|
MIT. Built with [libffi](https://github.com/libffi/libffi),
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "node-ctypes",
|
|
3
|
-
"version": "2.13.
|
|
3
|
+
"version": "2.13.2",
|
|
4
4
|
"description": "Python ctypes-like FFI for Node.js using libffi",
|
|
5
5
|
"author": "Damiano Mazzella",
|
|
6
6
|
"license": "MIT",
|
|
@@ -34,6 +34,7 @@
|
|
|
34
34
|
"test:types": "tsc -p tests/types/tsconfig.json",
|
|
35
35
|
"bench:koffi": "node tests/benchmarks/benchmark_koffi.js",
|
|
36
36
|
"bench:ffi": "node --experimental-ffi tests/benchmarks/benchmark_node_ffi.js",
|
|
37
|
+
"bench:charts": "node tests/benchmarks/charts.js",
|
|
37
38
|
"docs": "typedoc",
|
|
38
39
|
"docs:serve": "typedoc && npx serve docs"
|
|
39
40
|
},
|