node-ctypes 2.3.0 → 2.4.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 +932 -0
- package/README.md +446 -99
- 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/lib/core/Library.js +79 -62
- package/lib/core/callback.js +7 -3
- package/lib/core/conversions.js +226 -34
- package/lib/core/funcptr.js +115 -57
- package/lib/core/types.js +7 -2
- package/lib/index.d.ts +119 -54
- package/lib/index.js +10 -8
- package/lib/memory/buffer.js +39 -8
- package/lib/memory/operations.js +4 -6
- package/lib/memory/pointer.js +105 -38
- package/lib/platform/win_types.js +8 -3
- package/lib/structures/Structure.js +8 -39
- package/lib/structures/helpers/array.js +31 -12
- package/lib/structures/helpers/bitfield.js +17 -8
- package/lib/structures/helpers/common.js +218 -29
- package/lib/structures/helpers/layout.js +17 -3
- package/lib/structures/helpers/struct.js +25 -26
- package/lib/structures/helpers/union.js +32 -22
- package/lib/types/SimpleCData.js +11 -32
- package/lib/types/primitives.js +34 -16
- package/lib/utils/cache.js +34 -2
- package/package.json +3 -1
package/README.md
CHANGED
|
@@ -5,10 +5,19 @@
|
|
|
5
5
|
[](https://github.com/dmazzella/node-ctypes/actions/workflows/build.yml)
|
|
6
6
|
[](https://opensource.org/licenses/MIT)
|
|
7
7
|
|
|
8
|
-
**Python ctypes for Node.js.** A foreign function interface built
|
|
9
|
-
[
|
|
8
|
+
**Python ctypes for Node.js.** A foreign function interface built with C++20,
|
|
9
|
+
[node-addon-api](https://github.com/nodejs/node-addon-api) and
|
|
10
|
+
[libffi](https://github.com/libffi/libffi).
|
|
10
11
|
If you know Python ctypes, you already know node-ctypes.
|
|
11
12
|
|
|
13
|
+
## Support
|
|
14
|
+
|
|
15
|
+
Development help is welcome: issues, pull requests and discussions are all appreciated.
|
|
16
|
+
|
|
17
|
+
> [!TIP]
|
|
18
|
+
> If you find **node-ctypes** useful, consider :star: this project
|
|
19
|
+
> and why not ... [Buy me a coffee](https://www.buymeacoffee.com/damianomazp) :smile:
|
|
20
|
+
|
|
12
21
|
---
|
|
13
22
|
|
|
14
23
|
## Quick start
|
|
@@ -21,14 +30,14 @@ Prebuilt binaries ship for Windows, macOS 13.5+ and Linux (glibc 2.28+ or musl /
|
|
|
21
30
|
Alpine), on x64 and ARM64 — wherever Node 24 runs.
|
|
22
31
|
|
|
23
32
|
```javascript
|
|
24
|
-
import { CDLL, Structure, c_int32, c_char_p } from "node-ctypes";
|
|
33
|
+
import { CDLL, Structure, c_int32, c_size_t, c_char_p } from "node-ctypes";
|
|
25
34
|
|
|
26
35
|
// 1. Load a shared library
|
|
27
36
|
const libc = new CDLL(process.platform === "win32" ? "msvcrt" : null);
|
|
28
37
|
|
|
29
38
|
// 2. Declare a function signature
|
|
30
|
-
const strlen = libc.func("strlen",
|
|
31
|
-
console.log(strlen("hello")); //
|
|
39
|
+
const strlen = libc.func("strlen", c_size_t, [c_char_p]);
|
|
40
|
+
console.log(strlen("hello")); // 5n
|
|
32
41
|
|
|
33
42
|
// 3. Declare a struct
|
|
34
43
|
class Point extends Structure {
|
|
@@ -44,7 +53,8 @@ console.log(p.x, p.y); // 3 4
|
|
|
44
53
|
<details>
|
|
45
54
|
<summary>Build from source</summary>
|
|
46
55
|
|
|
47
|
-
Requires Node.js >= 24, CMake >= 3.15, and a C++ compiler.
|
|
56
|
+
Requires Node.js >= 24, CMake >= 3.15, and a C++20 compiler and standard library.
|
|
57
|
+
Run these commands from a source checkout:
|
|
48
58
|
|
|
49
59
|
```bash
|
|
50
60
|
npm install
|
|
@@ -76,6 +86,13 @@ abs2(-42); // 42
|
|
|
76
86
|
For Windows `__stdcall` APIs use `WinDLL` instead of `CDLL`. For COM-style
|
|
77
87
|
auto-`HRESULT`-checking use `OleDLL`.
|
|
78
88
|
|
|
89
|
+
Direct native calls are limited to a bounded set of exact scalar C++
|
|
90
|
+
signatures with up to four arguments, on 64-bit little-endian targets using
|
|
91
|
+
the default ABI. Other signatures use the existing cached libffi plans/CIFs,
|
|
92
|
+
including pointers and strings whose pointee types and qualifiers are not
|
|
93
|
+
encoded in the native type metadata. Float/double arguments continue to use
|
|
94
|
+
libffi on x86-64. This changes the optimization route, not the JavaScript API.
|
|
95
|
+
|
|
79
96
|
### Structs, unions, bit fields, arrays
|
|
80
97
|
|
|
81
98
|
```javascript
|
|
@@ -115,12 +132,31 @@ const name = array(c_char, 16)();
|
|
|
115
132
|
name.value = "node"; // .value / .raw as in Python
|
|
116
133
|
```
|
|
117
134
|
|
|
135
|
+
`array(type, n)` reuses the same type while it is alive. Instances, function
|
|
136
|
+
signatures and containing types keep their array types alive; the cache itself
|
|
137
|
+
does not. Unused array types and their length entries can be garbage-collected,
|
|
138
|
+
including arrays of builtin element types.
|
|
139
|
+
|
|
118
140
|
An array type in `argtypes` is passed by address, as in C and Python
|
|
119
141
|
(`fill.argtypes = [c_int32 * 4]`). As in Python, the argument must be an
|
|
120
142
|
instance of an array with the same element type and length; a Buffer or a
|
|
121
143
|
typed array is also accepted as its memory. Other values raise
|
|
122
144
|
`ArgumentError`.
|
|
123
145
|
|
|
146
|
+
Builtin numeric scalars accept numbers, booleans and BigInt; integers wrap to
|
|
147
|
+
their C width, but reject non-integral or non-finite numbers. Use BigInt when
|
|
148
|
+
the original integer needs more precision than a JS number can represent.
|
|
149
|
+
No argument, or `undefined` in a constructor, initializes zero. Explicit
|
|
150
|
+
`null`, strings and arbitrary objects are not implicit numeric conversions.
|
|
151
|
+
Assigning a scalar instance to a field or passing it to a declared numeric
|
|
152
|
+
argument requires a compatible type. The documented numeric-pointer argument
|
|
153
|
+
extensions below are unchanged.
|
|
154
|
+
|
|
155
|
+
`c_bool` and `wintypes.VARIANT_BOOL` use JavaScript truthiness, using `.value`
|
|
156
|
+
for scalar instances rather than treating every instance as true.
|
|
157
|
+
`VARIANT_BOOL` stores true as `-1`, and its results and callback arguments
|
|
158
|
+
are booleans. Boolean bitfields normalize before masking and read as booleans.
|
|
159
|
+
|
|
124
160
|
Nested structs, anonymous fields (`static _anonymous_ = ["data"]`),
|
|
125
161
|
explicit packing (`static _pack_ = 1`), minimum alignment
|
|
126
162
|
(`static _align_ = 16`), self-referential pointers (`POINTER(() => Node)`)
|
|
@@ -129,11 +165,40 @@ Python. The layout of bit fields follows Python's `_layout_`: `"gcc-sysv"`
|
|
|
129
165
|
by default, `"ms"` on Windows or with `_pack_`. Bit fields wider than 53
|
|
130
166
|
bits read as BigInt.
|
|
131
167
|
|
|
168
|
+
`_pack_` follows Python's integer conversion and permits zero and non-powers
|
|
169
|
+
of two (for example `3`) with the MS layout. An explicit `_pack_`, including
|
|
170
|
+
zero, is incompatible with `"gcc-sysv"`. Layouts with non-power-of-two
|
|
171
|
+
alignment can be used for memory serialization but are rejected as native
|
|
172
|
+
by-value signatures: they do not describe a valid C ABI alignment.
|
|
173
|
+
|
|
132
174
|
Structures and unions passed or returned by value keep this layout, also
|
|
133
175
|
with `_pack_`: as with GCC and clang, a structure with misaligned fields is
|
|
134
176
|
passed in memory on x86-64 System V (Linux, macOS Intel), where Python
|
|
135
177
|
ctypes passes it in registers and the called function reads wrong values.
|
|
136
178
|
|
|
179
|
+
Each returned structure or union owns a snapshot of its value, including
|
|
180
|
+
results declared with functional `struct()` / `union()` definitions. Array
|
|
181
|
+
views, nested composites and union getters remain valid after later calls,
|
|
182
|
+
reentrant conversion or `errcheck`, and concurrent `callAsync()` jobs.
|
|
183
|
+
Mutating one result does not modify another result's value storage.
|
|
184
|
+
|
|
185
|
+
This is not a deep copy through pointers: pointer fields can still refer to
|
|
186
|
+
the same external memory. Explicit `definition.toObject(buffer)` keeps its
|
|
187
|
+
existing buffer-view behavior. Synchronous low-level native `struct_buffer`
|
|
188
|
+
results are borrowed, reusable storage; public callables snapshot their
|
|
189
|
+
results before any JavaScript result conversion.
|
|
190
|
+
|
|
191
|
+
Low-level native `StructType` descriptors are builders only until consumed.
|
|
192
|
+
Adding a descriptor as a field, constructing an `ArrayType` from it (even at
|
|
193
|
+
length zero), preparing a function/callback signature, or creating/reading a
|
|
194
|
+
native value finalizes the captured layout and its dependencies.
|
|
195
|
+
`addField()` then throws instead of changing sizes, offsets or FFI metadata
|
|
196
|
+
already in use. Build a new descriptor for a different layout.
|
|
197
|
+
`getSize()` and `getAlignment()` alone leave an unused builder open; an
|
|
198
|
+
outer builder can still receive fields after it captures a finalized child.
|
|
199
|
+
Direct by-value self-reference is rejected. Pointers do not capture or
|
|
200
|
+
finalize the pointed-to layout.
|
|
201
|
+
|
|
137
202
|
### Pointers, buffers, and cast
|
|
138
203
|
|
|
139
204
|
```javascript
|
|
@@ -143,14 +208,16 @@ import { POINTER, pointer, cast, c_int32, c_void_p } from "node-ctypes";
|
|
|
143
208
|
const x = new c_int32(42);
|
|
144
209
|
const px = pointer(x);
|
|
145
210
|
px.contents.value; // 42 (Python: px.contents.value — a live c_int32)
|
|
146
|
-
px[0];
|
|
211
|
+
px[0]; // 42 (Python: px[0])
|
|
147
212
|
px[0] = 100;
|
|
148
|
-
x.value;
|
|
213
|
+
x.value; // 100 (same memory)
|
|
149
214
|
|
|
150
215
|
// View existing memory as a typed pointer
|
|
151
216
|
const IntPtr = POINTER(c_int32);
|
|
152
217
|
const p = IntPtr.fromBuffer(someBuffer);
|
|
153
|
-
p[0];
|
|
218
|
+
p[0];
|
|
219
|
+
p[1];
|
|
220
|
+
p[2]; // pointer arithmetic
|
|
154
221
|
|
|
155
222
|
// cast() — Python: cast(ptr, POINTER(T))
|
|
156
223
|
const q = cast(someBuffer, POINTER(c_int32));
|
|
@@ -166,6 +233,21 @@ that cannot be converted (a plain JS function, an object) raise
|
|
|
166
233
|
`ArgumentError` instead of passing NULL; `c_void_p` also accepts strings
|
|
167
234
|
(as `char *`, Python `bytes`) and any TypedArray/ArrayBuffer.
|
|
168
235
|
|
|
236
|
+
Declared `POINTER(T)` parameters reject incompatible ctypes instances,
|
|
237
|
+
arrays and pointer types before entering C. Compatible subclasses and arrays
|
|
238
|
+
are accepted, and a matching scalar/structure is passed by reference.
|
|
239
|
+
An explicit `cast()` changes the pointer type. Raw addresses and raw
|
|
240
|
+
Buffer/TypedArray/ArrayBuffer memory remain node-ctypes extensions; use
|
|
241
|
+
`c_void_p` for portable raw-address code.
|
|
242
|
+
|
|
243
|
+
`byref(value, byteOffset = 0)` preserves the original owner and supports
|
|
244
|
+
signed byte offsets. In-range references remain Buffer views; references
|
|
245
|
+
outside the object's byte range carry an address and owner. As with raw
|
|
246
|
+
addresses, the caller must ensure such memory is valid before dereferencing.
|
|
247
|
+
Function pointers read from fields or obtained from FFI bindings can be
|
|
248
|
+
assigned back to fields/arrays and passed as pointer arguments. Bare JS
|
|
249
|
+
functions still require `callback()` / a prototype-created callback.
|
|
250
|
+
|
|
169
251
|
### Callbacks
|
|
170
252
|
|
|
171
253
|
```javascript
|
|
@@ -176,11 +258,7 @@ const CompareFn = CFUNCTYPE(c_int32, c_void_p, c_void_p);
|
|
|
176
258
|
const cmp = new CompareFn((a, b) => readValue(a, c_int32) - readValue(b, c_int32));
|
|
177
259
|
|
|
178
260
|
// Or the one-shot form:
|
|
179
|
-
const cmp2 = callback(
|
|
180
|
-
(a, b) => readValue(a, c_int32) - readValue(b, c_int32),
|
|
181
|
-
c_int32,
|
|
182
|
-
[c_void_p, c_void_p]
|
|
183
|
-
);
|
|
261
|
+
const cmp2 = callback((a, b) => readValue(a, c_int32) - readValue(b, c_int32), c_int32, [c_void_p, c_void_p]);
|
|
184
262
|
|
|
185
263
|
// Pass the callback itself (as in Python) or its address `cmp.pointer`.
|
|
186
264
|
qsort(arr, 5, 4, cmp);
|
|
@@ -191,8 +269,23 @@ qsort(arr, 5, 4, cmp);
|
|
|
191
269
|
// rely on GC — the callback holds a libffi closure that native code may
|
|
192
270
|
// still reference.
|
|
193
271
|
cmp.release();
|
|
272
|
+
cmp2.release();
|
|
194
273
|
```
|
|
195
274
|
|
|
275
|
+
`CFUNCTYPE` and `WINFUNCTYPE` weakly intern live prototypes by the complete
|
|
276
|
+
identity and order of their argument/return types, separately for each calling
|
|
277
|
+
convention. Repeated requests reuse the same live prototype, as in Python,
|
|
278
|
+
without keeping abandoned types alive. Callers, callbacks and output bindings
|
|
279
|
+
retain their prototype while they are live.
|
|
280
|
+
|
|
281
|
+
Prototype metadata is shared. Changing its public `restype` / `argtypes`
|
|
282
|
+
metadata does not recompile the captured native signature or alter cache keys;
|
|
283
|
+
request a different signature to change the ABI. Each new caller prepares its
|
|
284
|
+
argument-conversion pipeline and captures its result-check hook independently.
|
|
285
|
+
Existing callers retain their result-check snapshot and their own `errcheck`.
|
|
286
|
+
An installed `from_param` converter still resolves the method at call time,
|
|
287
|
+
as before.
|
|
288
|
+
|
|
196
289
|
Both callbacks and libraries implement `Symbol.dispose`, so they work
|
|
197
290
|
with the `using` declaration for scope-bound cleanup (also on `throw`):
|
|
198
291
|
|
|
@@ -204,10 +297,18 @@ with the `using` declaration for scope-bound cleanup (also on `throw`):
|
|
|
204
297
|
} // close() + release() run automatically
|
|
205
298
|
```
|
|
206
299
|
|
|
207
|
-
A function keeps its library loaded as long as it is referenced, also
|
|
208
|
-
the `CDLL` object itself is no longer used. After `close()`,
|
|
209
|
-
|
|
210
|
-
to one of them is in progress (from a callback, or a
|
|
300
|
+
A bound function keeps its library loaded as long as it is referenced, also
|
|
301
|
+
when the `CDLL` object itself is no longer used. After `close()`, `loaded` is
|
|
302
|
+
false and its bound functions and symbol lookups throw; `close()` itself
|
|
303
|
+
throws while a call to one of them is in progress (from a callback, or a
|
|
304
|
+
pending `callAsync()`). Repeated `close()` calls are harmless.
|
|
305
|
+
|
|
306
|
+
Existing `in_dll()` views keep the underlying module loaded even after
|
|
307
|
+
`close()`. Release of the native library handle is deferred until the last
|
|
308
|
+
dependent view, Buffer, typed array or typed pointer copy is collected; those
|
|
309
|
+
existing views remain usable. Actual physical unloading depends on the OS loader: for example,
|
|
310
|
+
musl keeps shared libraries resident until process exit even after `dlclose()`.
|
|
311
|
+
Raw addresses obtained with `symbol()` do not carry this ownership information.
|
|
211
312
|
|
|
212
313
|
Set `NODE_CTYPES_DEBUG_CALLBACKS=1` to log a stack trace for every
|
|
213
314
|
callback garbage-collected without `.release()`.
|
|
@@ -225,12 +326,18 @@ const onEvent = threadSafeCallback((code) => console.log("event", code), null, [
|
|
|
225
326
|
startWorker(onEvent); // a native library calling onEvent from its own thread
|
|
226
327
|
```
|
|
227
328
|
|
|
329
|
+
Both callback implementations store narrow integer results in a complete
|
|
330
|
+
libffi `ffi_arg`, with the declared signedness; failures zero that complete
|
|
331
|
+
slot. Floating-point results retain their own storage width. The native
|
|
332
|
+
`Callback` / `ThreadSafeCallback` classes also expose `getPointer()`, which
|
|
333
|
+
throws after release.
|
|
334
|
+
|
|
228
335
|
### Errors: `errno` and `GetLastError`
|
|
229
336
|
|
|
230
337
|
`GetLastError()` / `get_errno()` read a **private thread-local slot** —
|
|
231
338
|
exactly like Python's `ctypes.get_last_error()` / `ctypes.get_errno()`.
|
|
232
|
-
The slot is
|
|
233
|
-
`use_last_error` or `use_errno`;
|
|
339
|
+
The slot is updated **only** by FFI calls through libraries opened with
|
|
340
|
+
`use_last_error` or `use_errno`; unflagged calls leave it unchanged. As in Python
|
|
234
341
|
those calls swap it with the system value: the function sees the value set
|
|
235
342
|
with `set_errno()` / `set_last_error()`, the value it leaves becomes the
|
|
236
343
|
private one, and the system value is restored after the call.
|
|
@@ -240,12 +347,12 @@ const user32 = new WinDLL("user32.dll", { use_last_error: true });
|
|
|
240
347
|
const FindWindow = user32.func("FindWindowW", c_void_p, [c_wchar_p, c_wchar_p]);
|
|
241
348
|
FindWindow("NoSuchClass", null);
|
|
242
349
|
|
|
243
|
-
GetLastError();
|
|
244
|
-
user32.get_last_error();
|
|
350
|
+
GetLastError(); // top-level (Python: ctypes.get_last_error)
|
|
351
|
+
user32.get_last_error(); // per-library alias
|
|
245
352
|
```
|
|
246
353
|
|
|
247
|
-
The snapshot is captured
|
|
248
|
-
|
|
354
|
+
The snapshot is captured in native code immediately after the native call,
|
|
355
|
+
whether direct or through libffi, before any other JS can clobber it. To read the raw system
|
|
249
356
|
error instead, call `GetLastError` via FFI like any other function.
|
|
250
357
|
|
|
251
358
|
### Windows API
|
|
@@ -264,8 +371,14 @@ const kernel32 = new WinDLL("kernel32.dll");
|
|
|
264
371
|
|
|
265
372
|
class SYSTEMTIME extends Structure {
|
|
266
373
|
static _fields_ = [
|
|
267
|
-
["wYear", WORD],
|
|
268
|
-
["
|
|
374
|
+
["wYear", WORD],
|
|
375
|
+
["wMonth", WORD],
|
|
376
|
+
["wDayOfWeek", WORD],
|
|
377
|
+
["wDay", WORD],
|
|
378
|
+
["wHour", WORD],
|
|
379
|
+
["wMinute", WORD],
|
|
380
|
+
["wSecond", WORD],
|
|
381
|
+
["wMilliseconds", WORD],
|
|
269
382
|
];
|
|
270
383
|
}
|
|
271
384
|
|
|
@@ -282,32 +395,105 @@ user32.GetClientRect(hwnd, byref(rect));
|
|
|
282
395
|
rect.right - rect.left; // LONG (c_long) values are BigInt
|
|
283
396
|
```
|
|
284
397
|
|
|
398
|
+
### Error checking (`errcheck`)
|
|
399
|
+
|
|
400
|
+
Set `fn.errcheck = (result, func, args) => ...` to check or replace a result,
|
|
401
|
+
or set it to `null` to clear it. For `lib.func()`, library attributes and
|
|
402
|
+
`CFUNCTYPE` / `WINFUNCTYPE` callers, `func` is the public callable and `args`
|
|
403
|
+
contains the original, unconverted arguments. Result conversion and any
|
|
404
|
+
`OleDLL` HRESULT check run before the hook.
|
|
405
|
+
|
|
406
|
+
Each invocation captures its hook before argument adapters or getters run.
|
|
407
|
+
Replacing or clearing it affects later invocations, including reentrant calls,
|
|
408
|
+
not the call already in progress or a pending `callAsync()` job.
|
|
409
|
+
|
|
410
|
+
Hooks do not prevent otherwise unreachable functions and libraries from being
|
|
411
|
+
garbage-collected, even when they reference the function itself. Active calls
|
|
412
|
+
and workers retain their captured hook through result checking; `close()` is
|
|
413
|
+
still rejected while that checking runs.
|
|
414
|
+
|
|
415
|
+
The low-level native handle's `setErrcheck()` API instead passes the native
|
|
416
|
+
handle as `func`, invoked with `.call()`, not a directly callable function.
|
|
417
|
+
|
|
418
|
+
### Scalar subclasses and result hooks
|
|
419
|
+
|
|
420
|
+
Builtin scalar types return ordinary JS values. A subclass instead produces
|
|
421
|
+
an instance containing the original C bytes, without invoking its constructor,
|
|
422
|
+
public buffer factory or writer. Derived scalar fields, array elements,
|
|
423
|
+
pointer indexing and callback arguments likewise expose typed instances;
|
|
424
|
+
memory views remain live, including in mirror mode.
|
|
425
|
+
|
|
426
|
+
The result pipeline is:
|
|
427
|
+
`C bytes -> restype representation -> _check_retval_ -> errcheck -> OUT/INOUT`.
|
|
428
|
+
A static `_check_retval_` receives the represented result and can replace it
|
|
429
|
+
or throw. It is captured when the function is bound; reassigning an attribute's
|
|
430
|
+
`restype` rebuilds that binding.
|
|
431
|
+
|
|
432
|
+
```javascript
|
|
433
|
+
class CheckedInt extends c_int32 {
|
|
434
|
+
static _check_retval_(value) {
|
|
435
|
+
return value.value + 100;
|
|
436
|
+
}
|
|
437
|
+
}
|
|
438
|
+
const checkedAbs = libc.func("abs", CheckedInt, [c_int32]);
|
|
439
|
+
checkedAbs(-7); // 107
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
Explicit `HRESULT` validation runs before `errcheck` with all loaders and
|
|
443
|
+
prototype callers, not only `OleDLL`. An error in result checking prevents
|
|
444
|
+
both `errcheck` and output conversion.
|
|
445
|
+
`OleDLL` attributes and `func(name)` default to `HRESULT`; other loaders
|
|
446
|
+
default to `c_int`. An explicit restype always overrides the default.
|
|
447
|
+
|
|
285
448
|
### Output parameters (`paramflags`)
|
|
286
449
|
|
|
287
450
|
When at least one `out` param is declared, the call returns **only the
|
|
288
451
|
out-params** (single value, or array if >1) — the `restype` is
|
|
289
|
-
discarded. To also inspect it (e.g. a
|
|
452
|
+
discarded. To also inspect it (e.g. a thread ID or success flag), attach an
|
|
290
453
|
`errcheck`:
|
|
291
454
|
|
|
292
455
|
```javascript
|
|
293
|
-
const
|
|
456
|
+
const { DWORD, HWND, LPDWORD } = wintypes;
|
|
457
|
+
const proto = WINFUNCTYPE(DWORD, HWND, LPDWORD);
|
|
294
458
|
const fn = proto.bind(user32, "GetWindowThreadProcessId", [
|
|
295
459
|
{ dir: "in", name: "hWnd" },
|
|
296
460
|
{ dir: "out", name: "pid" },
|
|
297
|
-
{ dir: "out", name: "tid" },
|
|
298
461
|
]);
|
|
299
462
|
|
|
300
|
-
const
|
|
301
|
-
const
|
|
463
|
+
const pid = fn(hwnd); // positional; thread ID is discarded
|
|
464
|
+
const p2 = fn({ hWnd: hwnd }); // or named-args
|
|
465
|
+
|
|
466
|
+
fn.errcheck = (threadId, func, args) => {
|
|
467
|
+
if (!threadId) throw new Error("call failed");
|
|
468
|
+
return args; // continue returning the PID from the output instance
|
|
469
|
+
};
|
|
470
|
+
const p3 = await fn.callAsync(hwnd);
|
|
302
471
|
|
|
303
|
-
fn.errcheck = (
|
|
304
|
-
if (!
|
|
305
|
-
return
|
|
472
|
+
fn.errcheck = (threadId, func, args) => {
|
|
473
|
+
if (!threadId) throw new Error("call failed");
|
|
474
|
+
return { threadId, processId: args[1].value };
|
|
306
475
|
};
|
|
476
|
+
const ids = fn(hwnd); // inspect both the return value and the output parameter
|
|
307
477
|
```
|
|
308
478
|
|
|
309
479
|
As in Python, the value returned by `errcheck` is the result of the call,
|
|
310
|
-
unless it is `args` itself: then the out-params are returned.
|
|
480
|
+
unless it is `args` itself: then the out-params are returned. Here `args`
|
|
481
|
+
is the expanded argument list, with out-params as instances.
|
|
482
|
+
|
|
483
|
+
These bindings have their own hook, independent of any cached `lib.func()`
|
|
484
|
+
binding, and support `callAsync()` with the same output processing and
|
|
485
|
+
per-call hook snapshot. Adapter temporaries stay alive through that processing,
|
|
486
|
+
also when the hook throws.
|
|
487
|
+
|
|
488
|
+
OUT conversion invokes the output instance's `__ctypes_from_outparam__()`.
|
|
489
|
+
By default a builtin scalar yields its value, while a scalar subclass yields
|
|
490
|
+
the instance. Override the method for custom output conversion.
|
|
491
|
+
|
|
492
|
+
Use `{ dir: "inout", name: "value" }`, or tuple flag `3`, to pass an existing
|
|
493
|
+
instance and return that exact instance after C modifies it. INOUT does not
|
|
494
|
+
call `__ctypes_from_outparam__`; positional, named and default arguments use
|
|
495
|
+
the same rule. Mixed outputs preserve parameter order. If `errcheck` returns
|
|
496
|
+
anything other than the original `args`, neither OUT nor INOUT unpacking runs.
|
|
311
497
|
|
|
312
498
|
### Sharing memory with existing buffers
|
|
313
499
|
|
|
@@ -327,10 +513,28 @@ const bytes = array(c_uint8, 64).from_address(malloc_result);
|
|
|
327
513
|
const view = new Float32Array(bytes._buffer.buffer, bytes._buffer.byteOffset, 16);
|
|
328
514
|
```
|
|
329
515
|
|
|
516
|
+
Typed pointers read from fields or array elements, and views derived from
|
|
517
|
+
them, retain their known memory owners. Typed assignments and
|
|
518
|
+
`from_buffer_copy()` preserve known pointer references, including overlapping
|
|
519
|
+
and self-copies; replacing a pointer releases its previous reference.
|
|
520
|
+
|
|
521
|
+
Raw copies (`memmove()`, Buffer methods) do not transfer ownership metadata.
|
|
522
|
+
Likewise, `from_address()` given a raw address cannot discover its allocation
|
|
523
|
+
or library: the caller must keep that memory valid. Keeping a known owner
|
|
524
|
+
alive does not take over responsibility for freeing externally allocated
|
|
525
|
+
memory or explicitly releasing callbacks.
|
|
526
|
+
|
|
527
|
+
`memmove()` and `memset()` return the destination address as BigInt, including
|
|
528
|
+
zero-length operations (`0n` for a NULL destination with count zero).
|
|
529
|
+
Counts must be non-negative safe integers. Copies/fills involving JS memory
|
|
530
|
+
still stop at its end; raw native addresses remain the caller's responsibility.
|
|
531
|
+
Scalar `from_buffer()` / `from_buffer_copy()` validate byte size and offset
|
|
532
|
+
before producing an instance and accept Buffer, typed views and ctypes memory.
|
|
533
|
+
|
|
330
534
|
### Electron
|
|
331
535
|
|
|
332
536
|
Electron does not allow Buffers over memory that V8 did not allocate, so a
|
|
333
|
-
Buffer
|
|
537
|
+
Buffer _view_ of native memory cannot exist there. node-ctypes detects this
|
|
334
538
|
when it loads (`EXTERNAL_BUFFERS` is `false`) and keeps the same API:
|
|
335
539
|
|
|
336
540
|
- instances on native memory (`from_address`, `in_dll`, `pointer.contents`,
|
|
@@ -344,8 +548,8 @@ when it loads (`EXTERNAL_BUFFERS` is `false`) and keeps the same API:
|
|
|
344
548
|
(`arr[i]`, `s.field`) or `memmove()`.
|
|
345
549
|
|
|
346
550
|
Only the bytes of the accessed field are copied, one native call per read
|
|
347
|
-
or write
|
|
348
|
-
|
|
551
|
+
or write; instances on ordinary Buffers (`new Point()`, `c_int(5)`) do not
|
|
552
|
+
need this native-memory synchronization. Set `NODE_CTYPES_NO_EXTERNAL_BUFFERS=1`
|
|
349
553
|
to run in this mode on Node.js.
|
|
350
554
|
|
|
351
555
|
### Adapter protocols: `_as_parameter_` and `from_param`
|
|
@@ -353,13 +557,17 @@ to run in this mode on Node.js.
|
|
|
353
557
|
```javascript
|
|
354
558
|
// Instance protocol: auto-unwrap on call
|
|
355
559
|
class Handle {
|
|
356
|
-
constructor(h) {
|
|
560
|
+
constructor(h) {
|
|
561
|
+
this._as_parameter_ = h;
|
|
562
|
+
}
|
|
357
563
|
}
|
|
358
564
|
user32.CloseHandle(new Handle(hwnd));
|
|
359
565
|
|
|
360
566
|
// Class protocol: custom conversion in argtypes
|
|
361
567
|
class StrLen extends c_int32 {
|
|
362
|
-
static from_param(s) {
|
|
568
|
+
static from_param(s) {
|
|
569
|
+
return typeof s === "string" ? s.length : s;
|
|
570
|
+
}
|
|
363
571
|
}
|
|
364
572
|
const abs = libc.func("abs", c_int32, [StrLen]);
|
|
365
573
|
abs("hello"); // 5
|
|
@@ -369,6 +577,22 @@ As in Python, `from_param` receives the argument as passed (also with
|
|
|
369
577
|
`CFUNCTYPE` prototypes), its result is converted as the declared type, and
|
|
370
578
|
an error it throws becomes `ArgumentError` (`"argument 1: RangeError: ..."`).
|
|
371
579
|
|
|
580
|
+
Objects passed through argument adapters and the objects produced by their
|
|
581
|
+
conversions stay alive while later arguments are converted and until the
|
|
582
|
+
result and `errcheck` have been processed. With `callAsync()`, those temporary
|
|
583
|
+
owners stay alive until its Promise settles. The native worker also retains
|
|
584
|
+
memory passed by value or as an integer address, including values materialized
|
|
585
|
+
by getters.
|
|
586
|
+
|
|
587
|
+
`_as_parameter_` chains are resolved recursively, including results of
|
|
588
|
+
`from_param`, with intermediate owners retained. Cycles and chains exceeding
|
|
589
|
+
128 adapter steps raise explicit argument errors, rather than overflowing
|
|
590
|
+
the stack or silently passing an incorrect pointer.
|
|
591
|
+
|
|
592
|
+
This only covers the call: if C stores a pointer for later use, or returns a
|
|
593
|
+
pointer into an argument's memory, keep the source object referenced for as
|
|
594
|
+
long as that pointer is used. Callbacks still require explicit `.release()`.
|
|
595
|
+
|
|
372
596
|
### Big-endian structures
|
|
373
597
|
|
|
374
598
|
```javascript
|
|
@@ -385,14 +609,21 @@ h.magic = 0x12345678; // stored as 12 34 56 78 on the wire
|
|
|
385
609
|
`LittleEndianStructure`, `BigEndianUnion`, `LittleEndianUnion` work the
|
|
386
610
|
same way. Byte order is per-class — nested structs keep their own.
|
|
387
611
|
|
|
612
|
+
Primitive arrays also follow their containing class's byte order, recursively
|
|
613
|
+
for multidimensional arrays, including floats and wide-character arrays.
|
|
614
|
+
Arrays of structures keep the element structure's own byte order. The same
|
|
615
|
+
array type can be shared with native/little-endian containers without being
|
|
616
|
+
modified. Raw Buffer and typed-memory copies still copy bytes, not values
|
|
617
|
+
converted between byte orders.
|
|
618
|
+
|
|
388
619
|
### TypeScript
|
|
389
620
|
|
|
390
|
-
Argument and return types are
|
|
391
|
-
tuple (`as const`)
|
|
621
|
+
Argument and return types are inferred from declared type classes such as
|
|
622
|
+
`c_int32` and `c_size_t`. A literal tuple (`as const`) preserves argument types:
|
|
392
623
|
|
|
393
624
|
```ts
|
|
394
625
|
const libc = new CDLL(null);
|
|
395
|
-
const strlen = libc.func("strlen",
|
|
626
|
+
const strlen = libc.func("strlen", c_size_t, [c_char_p] as const);
|
|
396
627
|
const n: bigint = strlen("hello"); // typed as bigint, not any
|
|
397
628
|
```
|
|
398
629
|
|
|
@@ -402,7 +633,9 @@ const n: bigint = strlen("hello"); // typed as bigint, not any
|
|
|
402
633
|
|
|
403
634
|
```ts
|
|
404
635
|
class Point extends defineStruct({ x: c_int32, y: c_int32 }) {
|
|
405
|
-
distance() {
|
|
636
|
+
distance() {
|
|
637
|
+
return Math.sqrt(this.x ** 2 + this.y ** 2);
|
|
638
|
+
}
|
|
406
639
|
}
|
|
407
640
|
const p = new Point({ x: 3, y: 4 }); // p.x, p.y typed as number
|
|
408
641
|
```
|
|
@@ -412,10 +645,10 @@ types are typed too; a `null` return type is `void`:
|
|
|
412
645
|
|
|
413
646
|
```ts
|
|
414
647
|
const PointDef = struct({ x: c_int32, y: c_double });
|
|
415
|
-
PointDef.get(buf, "y");
|
|
416
|
-
POINTER(c_int32).fromAddress(addr)[0];
|
|
417
|
-
array(c_int32, 4).create([1, 2, 3, 4])[0];
|
|
418
|
-
libc.func("srand", null, [c_uint32]);
|
|
648
|
+
PointDef.get(buf, "y"); // number
|
|
649
|
+
POINTER(c_int32).fromAddress(addr)[0]; // number (.contents: c_int32 instance)
|
|
650
|
+
array(c_int32, 4).create([1, 2, 3, 4])[0]; // number
|
|
651
|
+
libc.func("srand", null, [c_uint32]); // returns undefined
|
|
419
652
|
```
|
|
420
653
|
|
|
421
654
|
---
|
|
@@ -424,30 +657,30 @@ libc.func("srand", null, [c_uint32]); // returns undefined
|
|
|
424
657
|
|
|
425
658
|
### Primitive types
|
|
426
659
|
|
|
427
|
-
| Type | Aliases
|
|
428
|
-
| ----------- |
|
|
429
|
-
| `c_int8` | `c_byte`
|
|
430
|
-
| `c_uint8` | `c_ubyte`
|
|
431
|
-
| `c_int16` | `c_short`
|
|
432
|
-
| `c_uint16` | `c_ushort`
|
|
433
|
-
| `c_int32` | `c_int`
|
|
434
|
-
| `c_uint32` | `c_uint`
|
|
435
|
-
| `c_int64` | `c_longlong`
|
|
436
|
-
| `c_uint64` | `c_ulonglong`
|
|
437
|
-
| `c_long` |
|
|
438
|
-
| `c_ulong` |
|
|
439
|
-
| `c_float` |
|
|
440
|
-
| `c_double` |
|
|
441
|
-
| `c_bool` |
|
|
442
|
-
| `c_char` |
|
|
443
|
-
| `c_wchar` |
|
|
444
|
-
| `c_char_p` |
|
|
445
|
-
| `c_wchar_p` |
|
|
446
|
-
| `c_void_p` | `c_voidp`
|
|
447
|
-
| `c_time_t` |
|
|
448
|
-
| `c_size_t` |
|
|
449
|
-
| `c_ssize_t` |
|
|
450
|
-
| `HRESULT` |
|
|
660
|
+
| Type | Aliases | Size | Notes |
|
|
661
|
+
| ----------- | ------------- | -------- | --------------------------------------------- |
|
|
662
|
+
| `c_int8` | `c_byte` | 1 | |
|
|
663
|
+
| `c_uint8` | `c_ubyte` | 1 | |
|
|
664
|
+
| `c_int16` | `c_short` | 2 | |
|
|
665
|
+
| `c_uint16` | `c_ushort` | 2 | |
|
|
666
|
+
| `c_int32` | `c_int` | 4 | |
|
|
667
|
+
| `c_uint32` | `c_uint` | 4 | |
|
|
668
|
+
| `c_int64` | `c_longlong` | 8 | |
|
|
669
|
+
| `c_uint64` | `c_ulonglong` | 8 | |
|
|
670
|
+
| `c_long` | | platform | 4 on Windows, 8 on Unix 64-bit; BigInt values |
|
|
671
|
+
| `c_ulong` | | platform | mirrors `c_long`; BigInt values |
|
|
672
|
+
| `c_float` | | 4 | |
|
|
673
|
+
| `c_double` | | 8 | |
|
|
674
|
+
| `c_bool` | | 1 | |
|
|
675
|
+
| `c_char` | | 1 | 1-char string (Python `bytes`); also 0..255 |
|
|
676
|
+
| `c_wchar` | | 2 or 4 | 1-char string; 2 on Windows, 4 on Unix |
|
|
677
|
+
| `c_char_p` | | pointer | `char *` (NUL-terminated) |
|
|
678
|
+
| `c_wchar_p` | | pointer | `wchar_t *` (NUL-terminated wide) |
|
|
679
|
+
| `c_void_p` | `c_voidp` | pointer | opaque pointer / `HANDLE` |
|
|
680
|
+
| `c_time_t` | | 8 | `time_t` (`SIZEOF_TIME_T`) |
|
|
681
|
+
| `c_size_t` | | pointer | pointer-sized unsigned integer |
|
|
682
|
+
| `c_ssize_t` | | pointer | pointer-sized signed integer |
|
|
683
|
+
| `HRESULT` | | 4 | `c_int32` subclass — auto-raise on `OleDLL` |
|
|
451
684
|
|
|
452
685
|
Plus the Win32 types, structures and pointer types of `ctypes.wintypes` under `wintypes`.
|
|
453
686
|
|
|
@@ -475,9 +708,9 @@ Plus the Win32 types, structures and pointer types of `ctypes.wintypes` under `w
|
|
|
475
708
|
|
|
476
709
|
- `sizeof(type)` / `alignment(type)` — in bytes
|
|
477
710
|
- `addressof(obj)` → BigInt
|
|
478
|
-
- `byref(obj)` — lightweight
|
|
711
|
+
- `byref(obj, byteOffset = 0)` — lightweight reference with a signed byte offset
|
|
479
712
|
- `cast(ptr, type)` — reinterpret a pointer as another type
|
|
480
|
-
- `memmove(dst, src, n)` / `memset(dst, val, n)` — buffers, ctypes instances, pointers or addresses
|
|
713
|
+
- `memmove(dst, src, n)` / `memset(dst, val, n)` — buffers, ctypes instances, pointers or addresses; return the destination address as BigInt
|
|
481
714
|
- `readValue(ptr, type, offset?)` / `writeValue(ptr, type, val, offset?)`
|
|
482
715
|
- `create_string_buffer(init, size?)` / `c_buffer` / `create_unicode_buffer(init, size?)` — with `.value` (and `.raw`)
|
|
483
716
|
- `string_at(addr, size?)` / `wstring_at(addr, size?)` — exactly `size` units, or up to the NUL
|
|
@@ -522,8 +755,8 @@ pointer arithmetic (also `POINTER(POINTER(T))`), callbacks (`CFUNCTYPE` /
|
|
|
522
755
|
- **No automatic memory management** for returned pointers.
|
|
523
756
|
- **Both class and functional syntax**: `class extends Structure`
|
|
524
757
|
(Python-like) and `struct({...})` (functional) are both supported.
|
|
525
|
-
- **
|
|
526
|
-
|
|
758
|
+
- **Use type classes** such as `c_int32`, rather than string names such as
|
|
759
|
+
`"int32"`, for the Python-compatible, typed API.
|
|
527
760
|
- **`bytes` are JS strings**: `c_char` values, `c_char * n` arrays and
|
|
528
761
|
fields, `c_char_p` and `create_string_buffer().value` use strings (UTF-8)
|
|
529
762
|
where Python uses `bytes`; `.raw` is a `Buffer`.
|
|
@@ -535,7 +768,7 @@ pointer arithmetic (also `POINTER(POINTER(T))`), callbacks (`CFUNCTYPE` /
|
|
|
535
768
|
(Python: Windows only), so the same code runs everywhere.
|
|
536
769
|
- **64-bit and pointer-sized integers** (`c_int64`, `c_uint64`,
|
|
537
770
|
`c_size_t`, `c_ssize_t`) also accept `null` (as 0) and a `Buffer`
|
|
538
|
-
(as its address) as arguments.
|
|
771
|
+
or `ArrayBuffer` (as its address) as arguments.
|
|
539
772
|
- **Variadic arguments follow the C promotions**: a `c_float`, `c_int8`,
|
|
540
773
|
`c_char`, … instance passed beyond `argtypes` is passed as `double` /
|
|
541
774
|
`int`, where Python fails (`ffi_prep_cif_var failed`).
|
|
@@ -547,9 +780,14 @@ pointer arithmetic (also `POINTER(POINTER(T))`), callbacks (`CFUNCTYPE` /
|
|
|
547
780
|
array, `ArrayBuffer`) instead of writing past it.
|
|
548
781
|
- **Integer types reject non-integral numbers** (`3.7`, `NaN`) as Python
|
|
549
782
|
rejects floats; JS has no int/float distinction, so `3.0` is accepted.
|
|
783
|
+
- **Floating-point scalars accept BigInt in the range `-2**63` to `2**64-1`**,
|
|
784
|
+
converted to a JS number; larger BigInts raise a range error. This applies
|
|
785
|
+
consistently to constructors, fields and function arguments.
|
|
550
786
|
- **Array instances are Buffers whose Array methods work on the elements**
|
|
551
787
|
(`slice`, `map`, `includes`, …, as Python sequences); the Buffer methods
|
|
552
788
|
(`readInt32LE`, `subarray`, …) work on the bytes.
|
|
789
|
+
- **Array index reads follow JavaScript bounds behavior**: out-of-range
|
|
790
|
+
indices return `undefined`; negative indices do not wrap around as in Python.
|
|
553
791
|
- **Unions by value on x86-64 System V** are passed with the ABI rules;
|
|
554
792
|
Python passes them in the wrong registers (libffi#33).
|
|
555
793
|
- **Structure/Union fields are accessors of the class**, as Python fields
|
|
@@ -563,27 +801,29 @@ pointer arithmetic (also `POINTER(POINTER(T))`), callbacks (`CFUNCTYPE` /
|
|
|
563
801
|
Node `Buffer`, and Buffers aren't resizable in place.
|
|
564
802
|
Work-around: `new MyStruct(myBuffer)` with a pre-sized buffer.
|
|
565
803
|
- **`c_longdouble`** (80/128-bit float, `ffi_type_longdouble`) — rarely
|
|
566
|
-
used;
|
|
804
|
+
used; use a native wrapper that converts to supported types, or access
|
|
805
|
+
storage through pointers/bytes. Declaring a `long double` ABI value as
|
|
806
|
+
`c_double` is not a portable substitute.
|
|
567
807
|
|
|
568
808
|
### Migrating from 1.x
|
|
569
809
|
|
|
570
810
|
2.0 follows Python ctypes more closely. Code relying on the 1.x behavior
|
|
571
811
|
needs these changes:
|
|
572
812
|
|
|
573
|
-
| 1.x
|
|
574
|
-
|
|
|
575
|
-
| `ptr.contents` returned the value
|
|
576
|
-
| `POINTER(T)` restype returned a `bigint` address
|
|
577
|
-
| NULL `POINTER` struct fields were pointer objects
|
|
578
|
-
| `c_char` values were numbers
|
|
579
|
-
| invalid `c_char` values were truncated
|
|
580
|
-
| wrong argument types raised `TypeError`
|
|
581
|
-
| unsupported pointer arguments (functions, plain objects) passed NULL
|
|
582
|
-
| functions without `restype` / `argtypes`
|
|
583
|
-
| `create_string_buffer(init)`
|
|
584
|
-
| `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
|
|
585
|
-
| `wintypes.CHAR` was `c_ubyte`; `LPDWORD`, `PDWORD`, `LPBYTE`, `PBYTE`, `PHKEY` were `c_void_p`
|
|
586
|
-
| `string_at(addr, n)` / `wstring_at(addr, n)` stopped at the first NUL
|
|
813
|
+
| 1.x | 2.0 (as Python) |
|
|
814
|
+
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
815
|
+
| `ptr.contents` returned the value | returns a live instance: `ptr.contents.value` (simple types), `ptr.contents.x` (structs); `ptr[0]` still returns the value |
|
|
816
|
+
| `POINTER(T)` restype returned a `bigint` address | returns a pointer object (`null` for NULL); use `.address` for the number |
|
|
817
|
+
| NULL `POINTER` struct fields were pointer objects | they are `null` |
|
|
818
|
+
| `c_char` values were numbers | 1-character strings; `c_char * n` fields read/write as strings |
|
|
819
|
+
| invalid `c_char` values were truncated | `TypeError` (`"one character bytes, bytearray, or an integer in range(256) expected, not ..."`) |
|
|
820
|
+
| wrong argument types raised `TypeError` | raise `ArgumentError` (a `TypeError` subclass), message `"argument N: TypeError: ..."` |
|
|
821
|
+
| unsupported pointer arguments (functions, plain objects) passed NULL | raise `ArgumentError` (`"'function' object cannot be interpreted as ctypes.c_void_p"`) |
|
|
822
|
+
| functions without `restype` / `argtypes` | default `restype` is `c_int`; without `argtypes` the call uses the fixed-argument ABI |
|
|
823
|
+
| `create_string_buffer(init)` | also takes `size` and returns a Buffer with `.value` / `.raw` |
|
|
824
|
+
| `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 |
|
|
825
|
+
| `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) |
|
|
826
|
+
| `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) |
|
|
587
827
|
|
|
588
828
|
---
|
|
589
829
|
|
|
@@ -604,22 +844,129 @@ Each example in `examples/` has its own README; see the [index](examples/README.
|
|
|
604
844
|
|
|
605
845
|
## Tests & docs
|
|
606
846
|
|
|
607
|
-
`npm test` first builds a small C library (`tests/fixtures/`, into
|
|
847
|
+
From the repository root, `npm --prefix tests test` first builds a small C library (`tests/fixtures/`, into
|
|
608
848
|
`build/fixture/`) used by the tests of structures by value, array parameters
|
|
609
849
|
and reentrant calls; `npm run build:test-fixture` builds it alone. Python
|
|
610
850
|
twins of the tests (`tests/common/*.py`) load the same library.
|
|
611
851
|
|
|
612
852
|
```bash
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
npm
|
|
616
|
-
npm
|
|
617
|
-
npm
|
|
853
|
+
npm install
|
|
854
|
+
npm run build
|
|
855
|
+
npm --prefix tests install
|
|
856
|
+
npm --prefix tests test # functional/parity tests
|
|
857
|
+
NODE_CTYPES_NO_EXTERNAL_BUFFERS=1 npm --prefix tests test # mirrored native memory
|
|
858
|
+
npm run test:types # TypeScript declarations
|
|
859
|
+
npm run docs # TypeDoc API site in docs/
|
|
860
|
+
npm run docs:serve # preview
|
|
618
861
|
```
|
|
619
862
|
|
|
620
|
-
See [tests/common/](tests/common
|
|
863
|
+
See [tests/common/](https://github.com/dmazzella/node-ctypes/tree/main/tests/common) for runnable examples alongside
|
|
621
864
|
parallel Python ctypes implementations.
|
|
622
865
|
|
|
866
|
+
### Performance comparisons
|
|
867
|
+
|
|
868
|
+
There are two JavaScript comparisons, both against another FFI library.
|
|
869
|
+
From the repository root, after building node-ctypes:
|
|
870
|
+
|
|
871
|
+
```bash
|
|
872
|
+
npm --prefix tests install # includes Koffi
|
|
873
|
+
npm run build:test-fixture # shared C functions for both libraries
|
|
874
|
+
npm run bench:koffi # node-ctypes vs Koffi; Node 24+
|
|
875
|
+
npm run bench:ffi # node-ctypes vs node:ffi; Node 26+
|
|
876
|
+
```
|
|
877
|
+
|
|
878
|
+
The private test package explicitly approves the install script for Koffi 3.3.3.
|
|
879
|
+
When upgrading Koffi, review the new version before updating that approval with
|
|
880
|
+
`npm --prefix tests install-scripts approve koffi`; future versions are not
|
|
881
|
+
automatically authorized.
|
|
882
|
+
|
|
883
|
+
`bench:ffi` adds `--experimental-ffi` automatically. Both comparisons
|
|
884
|
+
print a table grouped by workload and automatically generate HTML reports:
|
|
885
|
+
|
|
886
|
+
- `tests/benchmarks/results/koffi.html`
|
|
887
|
+
- `tests/benchmarks/results/node-ffi.html`
|
|
888
|
+
|
|
889
|
+
These paths are relative to the repository root, regardless of the working
|
|
890
|
+
directory. Each successful run replaces its previous report; generated results
|
|
891
|
+
are ignored by Git. Open the HTML file directly in a browser: it is responsive
|
|
892
|
+
and self-contained, with native HTML/CSS bar charts and no browser JavaScript,
|
|
893
|
+
external resources or server requirements.
|
|
894
|
+
|
|
895
|
+
| Column | Meaning |
|
|
896
|
+
| ------------------------ | ----------------------------------------------------- |
|
|
897
|
+
| Case | The same operation and inputs for both libraries |
|
|
898
|
+
| node-ctypes / competitor | Median time +/- MAD (dispersion), in ns per operation |
|
|
899
|
+
| Ratio | node-ctypes time divided by competitor time |
|
|
900
|
+
|
|
901
|
+
A ratio of `0.50x` means node-ctypes took half the time; `2.00x` means it
|
|
902
|
+
took twice the time. Lower times are better. There is no overall score
|
|
903
|
+
combining unrelated calls, memory access and asynchronous scheduling.
|
|
904
|
+
In the charts, **shorter bars are better**. Each workload group shares a linear
|
|
905
|
+
scale starting at zero; different groups use different scales. Bars show
|
|
906
|
+
medians, with +/- MAD whiskers (not confidence intervals). Each library also
|
|
907
|
+
shows its total measured operation count and elapsed time across the samples.
|
|
908
|
+
|
|
909
|
+
Reports record library/runtime versions, CPU, OS/kernel, buffer mode, start/
|
|
910
|
+
finish timestamps and Git revision/working-tree status. Missing CPU or Git
|
|
911
|
+
metadata produces an explicit warning rather than invented values.
|
|
912
|
+
|
|
913
|
+
The comparisons cover scalars, mixed arguments, short/long strings, buffer
|
|
914
|
+
arguments, field reads and callbacks. Koffi also covers structures by value,
|
|
915
|
+
variadic calls and async calls with 1/8 calls in flight. Cases without an
|
|
916
|
+
equivalent documented node:ffi API are listed as **not compared**, not
|
|
917
|
+
emulated with a different native signature.
|
|
918
|
+
|
|
919
|
+
Both sides call the same C fixture and verify results before/after timing.
|
|
920
|
+
String lengths are compared as Numbers, including conversion where the API
|
|
921
|
+
returns BigInt; wide integers are BigInt in both APIs. Structures are plain
|
|
922
|
+
objects. Async times include scheduling and are reported per completed call,
|
|
923
|
+
with the concurrency shown in the case name.
|
|
924
|
+
|
|
925
|
+
Defaults are nine samples of at least 250 ms per library after warmup,
|
|
926
|
+
alternating library order. Each native signature has a separate call-site to
|
|
927
|
+
avoid mixing V8 optimization feedback between cases.
|
|
928
|
+
Each row is printed when its measurements finish.
|
|
929
|
+
Run comparisons serially, not concurrently. Optional arguments:
|
|
930
|
+
|
|
931
|
+
```bash
|
|
932
|
+
npm run bench:koffi -- --filter string,callback
|
|
933
|
+
npm run bench:ffi -- --samples 11 --duration 500
|
|
934
|
+
npm run bench:koffi -- --output comparison.json
|
|
935
|
+
```
|
|
936
|
+
|
|
937
|
+
`--output comparison.json` additionally saves medians, dispersion and all sample
|
|
938
|
+
durations/operation counts as JSON, and writes `comparison.html` next to it
|
|
939
|
+
instead of the default HTML report. Parent directories are created automatically.
|
|
940
|
+
HTML generation runs only after all measurements finish.
|
|
941
|
+
`benchmark_koffi.js` and `benchmark_node_ffi.js` define the actual side-by-side
|
|
942
|
+
comparisons; `runner.js` shares timing, table output and HTML generation without
|
|
943
|
+
extra dependencies or a separate renderer script. There is no separate
|
|
944
|
+
self-benchmark command, and benchmarks are not run by the functional/parity
|
|
945
|
+
test suite.
|
|
946
|
+
|
|
947
|
+
### Release validation
|
|
948
|
+
|
|
949
|
+
The workflow retains the eight Node 24 native build targets (Windows/macOS,
|
|
950
|
+
x64/ARM64, and Linux glibc/musl). C++20 conformance is checked with
|
|
951
|
+
`-pedantic-errors` on GCC/Clang and `/permissive-` on MSVC; vendor optimization
|
|
952
|
+
and the node-addon-api integration remain unchanged.
|
|
953
|
+
|
|
954
|
+
Three runtime-control jobs reuse the built artifacts on Node 26 without
|
|
955
|
+
rebuilding the addon, running the functional parity suite normally and with
|
|
956
|
+
mirrored buffers. A Linux job runs the focused Python 3.15
|
|
957
|
+
reference tests in addition to the Python 3.14 reference coverage.
|
|
958
|
+
|
|
959
|
+
The package assembler requires all eight nonempty binaries and includes
|
|
960
|
+
declarations, README, changelog and license. It fails on missing/unknown
|
|
961
|
+
artifacts or a stale output directory. Publish depends on the runtime gates,
|
|
962
|
+
requires a pushed tag matching the manifest version exactly, and uses `next`
|
|
963
|
+
for prereleases instead of `latest`. Manual workflow runs never publish.
|
|
964
|
+
These are configured gates, not a substitute for a successful native CI run.
|
|
965
|
+
|
|
966
|
+
`npm --prefix tests test` builds the fixture and runs the suite;
|
|
967
|
+
`npm --prefix tests run test:js` reuses an already-built fixture/addon.
|
|
968
|
+
Both use the documented `--test-timeout` runner option.
|
|
969
|
+
|
|
623
970
|
---
|
|
624
971
|
|
|
625
972
|
## License
|