node-ctypes 2.4.0 → 2.6.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 +117 -1
- package/README.md +94 -8
- 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 +39 -83
- package/lib/core/callback.js +54 -7
- package/lib/core/conversions.js +159 -26
- package/lib/core/funcptr.js +91 -27
- package/lib/index.d.ts +82 -13
- package/lib/memory/buffer.js +23 -5
- package/lib/memory/pointer.js +42 -36
- package/lib/structures/Structure.js +52 -6
- package/lib/structures/helpers/common.js +18 -13
- package/lib/structures/helpers/struct.js +42 -26
- package/lib/structures/helpers/union.js +4 -4
- package/lib/types/primitives.js +3 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,120 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [2.6.0] - 2026-10-30
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **Native callback contexts**: opt into `suspend`, `resume` and `onError`
|
|
15
|
+
hooks through the fourth `threadSafeCallback()` argument. Foreign callers
|
|
16
|
+
detach their native state before waiting and restore it on the original
|
|
17
|
+
thread before consuming an opaque error supplied with `setNativeError()`.
|
|
18
|
+
Error payloads are isolated per invocation, including concurrent and nested
|
|
19
|
+
calls.
|
|
20
|
+
- **Cooperative callback dispatch**: optional native `notify` hooks can wake
|
|
21
|
+
the consumer's host runtime; `drain()` processes a snapshot of pending calls
|
|
22
|
+
on the owning Node thread. Atomic claiming prevents duplicate execution
|
|
23
|
+
between drains and TSFN delivery, and late deliveries do not access completed
|
|
24
|
+
calls' native arguments. These primitives do not pump a blocked event loop
|
|
25
|
+
automatically.
|
|
26
|
+
- **Electron + React example**: a real native system clock and process-ID check
|
|
27
|
+
in `examples/cross-platform/electron-app`, with node-ctypes confined to the main process,
|
|
28
|
+
typed sandboxed IPC and no renderer Node polyfill. Native `malloc`/clock/view/
|
|
29
|
+
`free` reads exercise automatic synchronized mirrors when Electron disables
|
|
30
|
+
external buffers. Local dependency packaging keeps the addon outside ASAR;
|
|
31
|
+
real macOS ARM64 development and standalone packaged-app checks passed without
|
|
32
|
+
an Electron-specific addon rebuild.
|
|
33
|
+
|
|
34
|
+
### Changed
|
|
35
|
+
|
|
36
|
+
- **Explicit native hook functions**: accept ctypes native function objects,
|
|
37
|
+
low-level function handles and raw BigInt addresses. Resolve hook addresses
|
|
38
|
+
once and retain supplied function objects through release and queued delivery
|
|
39
|
+
cleanup. Plain JavaScript functions and known JavaScript-backed callback
|
|
40
|
+
wrappers are rejected; native hooks bypass JavaScript converters and
|
|
41
|
+
`errcheck`. Explicit library closure remains the consumer's responsibility.
|
|
42
|
+
- **Callback lifecycle**: represent validated native contexts with C++20
|
|
43
|
+
`std::optional` and restore caller state through a noncopyable, nonmovable
|
|
44
|
+
RAII scope, including a saved state equal to `nullptr`. Reject explicit
|
|
45
|
+
release while a native-context invocation is active.
|
|
46
|
+
- **Public types and documentation**: expose the native-context options,
|
|
47
|
+
error-transfer and drain methods, and native address metadata on library
|
|
48
|
+
attribute functions. Document ownership, thread constraints and dispatch
|
|
49
|
+
flows, with regressions for concurrency, reentry, GC and null-state
|
|
50
|
+
restoration. Existing ABI-string options and callbacks without native
|
|
51
|
+
contexts retain their behavior; the new hooks require a matching rebuilt
|
|
52
|
+
addon, not only updated JavaScript wrappers.
|
|
53
|
+
|
|
54
|
+
## [2.5.0] - 2026-10-26
|
|
55
|
+
|
|
56
|
+
### Fixed
|
|
57
|
+
|
|
58
|
+
- **Portable CI validation**: large BigInt-to-float conversion no longer requires
|
|
59
|
+
the floating-point `from_chars` overload introduced in macOS 26, preserving
|
|
60
|
+
the macOS 13.5 deployment target and integer rounding/overflow checks. Paired
|
|
61
|
+
Linux lookup tests accept musl's `libm` alias to `libc` and verify the resolved
|
|
62
|
+
libraries by calling their correctly declared functions. Windows references
|
|
63
|
+
resolve the explicit `msvcrt` library and accept absolute DLL paths instead of
|
|
64
|
+
assuming CPython implements Node's `"c"` alias or returns bare file names.
|
|
65
|
+
|
|
66
|
+
### Changed
|
|
67
|
+
|
|
68
|
+
- **Parity tests**: migrate the complete former `common/` and `windows/`
|
|
69
|
+
suites into domain-based `cpython_parity/` pairs, `node_specific/` regressions
|
|
70
|
+
and genuine `python_specific/` scheduling checks. Paired JS uses Python-shaped
|
|
71
|
+
classes, `ARRAY`, attribute bindings and `CFUNCTYPE`, with corresponding
|
|
72
|
+
class/method IDs, input matrices and actual C signatures. A structural AST
|
|
73
|
+
guard rejects one-sided files/cases, missing discovery markers and convenience
|
|
74
|
+
APIs in the canonical pairs without adding dependencies or replacing either
|
|
75
|
+
test runner. Python 3.15 CI now runs all references.
|
|
76
|
+
- **Pointer definitions**: expose Python's `_type_` metadata and defer incomplete
|
|
77
|
+
aggregate pointee layout until an actual memory access, so forward-bound
|
|
78
|
+
`_fields_` and self-referential types do not need manual cache invalidation.
|
|
79
|
+
- **Scalar and field conversion**: accept legitimate empty/whitespace field
|
|
80
|
+
names without corrupting constructor/prototype metadata, and convert full-width
|
|
81
|
+
BigInts to floating-point values with CPython rounding and overflow behavior
|
|
82
|
+
rather than an artificial 64-bit integer limit.
|
|
83
|
+
- **Function protocols**: `CFUNCTYPE` callbacks are callable, native functions
|
|
84
|
+
can be cast through the public API, and cached prototype conversion/retval
|
|
85
|
+
hooks are captured at type creation. Pointer-to-pointer values use the pointer
|
|
86
|
+
slot rather than the pointee bytes. Declared integer arguments reject nullish
|
|
87
|
+
values, and string-pointer arguments require strings, compatible C-data or an
|
|
88
|
+
explicit cast instead of an untyped integer address.
|
|
89
|
+
- **Raw memory and finalization**: explicitly sized `string_at` preserves all
|
|
90
|
+
bytes, including invalid UTF-8 and embedded NUL, as a Latin1 string; unsized
|
|
91
|
+
textual reads retain their UTF-8 representation. Address conversion errors
|
|
92
|
+
retain their causes through `ArgumentError`. Materialized aggregate layouts
|
|
93
|
+
reject `_fields_` reassignment, including previously incomplete types.
|
|
94
|
+
- **Typed pointer adapters**: match CPython's distinction between direct and
|
|
95
|
+
adapted arguments. Automatic by-reference conversion, array decay and NULL
|
|
96
|
+
acceptance no longer apply to scalar/array/null `_as_parameter_` results for
|
|
97
|
+
`POINTER(T)`; explicit compatible pointers and `byref` results remain accepted.
|
|
98
|
+
- **Parameter resolution**: terminal primitive `_as_parameter_` results avoid
|
|
99
|
+
allocating a cycle-detection Set. Recursive conversion follows CPython:
|
|
100
|
+
stateful getters may revisit an object before terminating, and the fixed
|
|
101
|
+
128-step rejection is removed. Non-terminating recursion uses the host runtime
|
|
102
|
+
stack guard; intermediate owners stay alive and getter errors propagate unchanged.
|
|
103
|
+
- **Prototype callers**: eligible synchronous prototype bindings reuse the
|
|
104
|
+
fixed-arity JavaScript wrappers used by library functions. Calls needing
|
|
105
|
+
owners, custom adapters, result conversion or argument-count fallback keep
|
|
106
|
+
the general pipeline. Hook snapshots, original argument arrays, callable
|
|
107
|
+
metadata and prototype asynchronous behavior are preserved. External
|
|
108
|
+
comparisons include explicit already-bound `CFUNCTYPE` caller rows.
|
|
109
|
+
- **Callback conversion**: builtin-only signatures skip the generic argument
|
|
110
|
+
conversion dispatcher while preserving invocation and result conversion. Native
|
|
111
|
+
handlers construct fallback error messages only on failure, with unchanged
|
|
112
|
+
diagnostics and thread-safety checks.
|
|
113
|
+
- **Long UTF-8 arguments**: synchronous calls encode directly into reusable
|
|
114
|
+
scratch storage when it fits, keeping the ordinary encoder for growth.
|
|
115
|
+
String contents are still encoded on every call; the existing retention
|
|
116
|
+
bound, wide-string alignment and independent reentrant buffers are preserved.
|
|
117
|
+
- **Structure argument conversion**: plain-object arguments for functional
|
|
118
|
+
`struct()` definitions containing only builtin non-pointer scalar fields
|
|
119
|
+
skip the transient Proxy and use the same byte initializer as `create()`.
|
|
120
|
+
Field validation, zero defaults, dynamic `create()` / `set()` hooks and
|
|
121
|
+
argument lifetimes are preserved. Classes and complex definitions keep
|
|
122
|
+
their existing conversion paths.
|
|
123
|
+
|
|
10
124
|
## [2.4.0] - 2026-10-24
|
|
11
125
|
|
|
12
126
|
### Added
|
|
@@ -904,7 +1018,9 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
|
|
|
904
1018
|
|
|
905
1019
|
Initial releases.
|
|
906
1020
|
|
|
907
|
-
[Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.
|
|
1021
|
+
[Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.6.0...HEAD
|
|
1022
|
+
[2.6.0]: https://github.com/dmazzella/node-ctypes/compare/v2.5.0...v2.6.0
|
|
1023
|
+
[2.5.0]: https://github.com/dmazzella/node-ctypes/compare/v2.4.0...v2.5.0
|
|
908
1024
|
[2.4.0]: https://github.com/dmazzella/node-ctypes/compare/v2.3.0...v2.4.0
|
|
909
1025
|
[2.3.0]: https://github.com/dmazzella/node-ctypes/compare/v2.2.0...v2.3.0
|
|
910
1026
|
[2.2.0]: https://github.com/dmazzella/node-ctypes/compare/v2.1.1...v2.2.0
|
package/README.md
CHANGED
|
@@ -236,6 +236,9 @@ that cannot be converted (a plain JS function, an object) raise
|
|
|
236
236
|
Declared `POINTER(T)` parameters reject incompatible ctypes instances,
|
|
237
237
|
arrays and pointer types before entering C. Compatible subclasses and arrays
|
|
238
238
|
are accepted, and a matching scalar/structure is passed by reference.
|
|
239
|
+
These implicit scalar/array/NULL conversions apply to direct arguments only.
|
|
240
|
+
To adapt one of these values through `_as_parameter_`, return an explicit
|
|
241
|
+
compatible pointer or `byref` value instead, as in CPython.
|
|
239
242
|
An explicit `cast()` changes the pointer type. Raw addresses and raw
|
|
240
243
|
Buffer/TypedArray/ArrayBuffer memory remain node-ctypes extensions; use
|
|
241
244
|
`c_void_p` for portable raw-address code.
|
|
@@ -326,6 +329,57 @@ const onEvent = threadSafeCallback((code) => console.log("event", code), null, [
|
|
|
326
329
|
startWorker(onEvent); // a native library calling onEvent from its own thread
|
|
327
330
|
```
|
|
328
331
|
|
|
332
|
+
For an embedding runtime that must detach its native thread state before waiting,
|
|
333
|
+
the optional fourth argument can be `{ abi, nativeContext: { suspend, resume, onError, notify? } }`
|
|
334
|
+
instead of the existing ABI string. Each hook accepts a ctypes native function,
|
|
335
|
+
a low-level function handle, or a nonzero BigInt function address:
|
|
336
|
+
|
|
337
|
+
```javascript
|
|
338
|
+
const onRequest = threadSafeCallback(handleRequest, c_int, [c_int], {
|
|
339
|
+
nativeContext: {
|
|
340
|
+
suspend: runtime.func("save_context", c_void_p, []),
|
|
341
|
+
resume: runtime.func("restore_context", null, [c_void_p]),
|
|
342
|
+
onError: runtime.func("install_error", null, [c_void_p]),
|
|
343
|
+
notify: runtime.func("wake_host", null, []),
|
|
344
|
+
},
|
|
345
|
+
});
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
Function objects resolve through `_as_parameter_` or `address` once, when the
|
|
349
|
+
callback is constructed. The hooks are called directly using the default C ABI;
|
|
350
|
+
the function wrapper's JS converters and `errcheck` are not invoked:
|
|
351
|
+
|
|
352
|
+
- `void *suspend(void)` runs on a foreign caller before queueing.
|
|
353
|
+
- `void resume(void *)` restores that caller's saved state after dispatch, including
|
|
354
|
+
queue failure or environment shutdown. Neither hook runs on the Node host fast path.
|
|
355
|
+
- `void onError(void *)` consumes an opaque error pointer on the original caller
|
|
356
|
+
thread, after restoration. During the JS callback, use
|
|
357
|
+
`callback.setNativeError(pointer)` once and return the native API's required error
|
|
358
|
+
sentinel (`NULL`, `-1`, etc.). Error payloads belong to each invocation, including
|
|
359
|
+
concurrent and nested calls; JS exceptions are still reported as documented above.
|
|
360
|
+
- Optional `void notify(void)` runs on the foreign caller after successful queueing,
|
|
361
|
+
while its native state is detached. It may wake the host through the consumer's
|
|
362
|
+
runtime, but must not execute JavaScript itself.
|
|
363
|
+
|
|
364
|
+
`callback.drain()` executes a snapshot of pending calls **on the owning Node
|
|
365
|
+
thread**, returning the number it claimed. Each call executes at most once,
|
|
366
|
+
whether the TSFN or a drain gets there first. Delayed TSFN deliveries retain
|
|
367
|
+
only the shared request state and do not touch completed calls' native arguments.
|
|
368
|
+
The consumer must provide a safe way to reenter the host and call `drain()`;
|
|
369
|
+
calling it before entering a blocking native wait is not sufficient.
|
|
370
|
+
|
|
371
|
+
Hooks must not throw or execute JavaScript. Plain JS functions and known
|
|
372
|
+
JS-backed callback wrappers are rejected; an address cannot prove a function's
|
|
373
|
+
signature, validity or implementation. Supplied function objects are retained by
|
|
374
|
+
the native dispatcher through release and queued delivery cleanup. This does not
|
|
375
|
+
prevent explicitly closing their libraries or releasing their underlying resources;
|
|
376
|
+
raw addresses carry no owner. Keep the callback and the hook libraries
|
|
377
|
+
alive until all native calls have returned; explicit release is rejected while a
|
|
378
|
+
native-context call is active. These hooks do not acquire the host runtime context,
|
|
379
|
+
pump a blocked host event loop automatically, or implement interpreter ownership/subinterpreters.
|
|
380
|
+
The host JS handler must acquire/release its own runtime context around native API
|
|
381
|
+
operations. The ordinary callback path is unchanged when no hooks are supplied.
|
|
382
|
+
|
|
329
383
|
Both callback implementations store narrow integer results in a complete
|
|
330
384
|
libffi `ffi_arg`, with the declared signedness; failures zero that complete
|
|
331
385
|
slot. Floating-point results retain their own storage width. The native
|
|
@@ -585,9 +639,12 @@ memory passed by value or as an integer address, including values materialized
|
|
|
585
639
|
by getters.
|
|
586
640
|
|
|
587
641
|
`_as_parameter_` chains are resolved recursively, including results of
|
|
588
|
-
`from_param`, with intermediate owners retained.
|
|
589
|
-
|
|
590
|
-
|
|
642
|
+
`from_param`, with intermediate owners retained. As in CPython, an adapter may
|
|
643
|
+
be visited again when a stateful getter eventually returns a usable value;
|
|
644
|
+
object identity alone is not rejected as a cycle, and there is no fixed
|
|
645
|
+
128-step limit. Non-terminating recursion raises an argument conversion error.
|
|
646
|
+
The available recursion depth and stack-error wording follow the JavaScript
|
|
647
|
+
runtime, rather than CPython's runtime-specific recursion guard.
|
|
591
648
|
|
|
592
649
|
This only covers the call: if C stores a pointer for later use, or returns a
|
|
593
650
|
pointer into an argument's memory, keep the source object referenced for as
|
|
@@ -715,6 +772,11 @@ Plus the Win32 types, structures and pointer types of `ctypes.wintypes` under `w
|
|
|
715
772
|
- `create_string_buffer(init, size?)` / `c_buffer` / `create_unicode_buffer(init, size?)` — with `.value` (and `.raw`)
|
|
716
773
|
- `string_at(addr, size?)` / `wstring_at(addr, size?)` — exactly `size` units, or up to the NUL
|
|
717
774
|
|
|
775
|
+
With an explicit byte count, `string_at` returns a lossless Latin1 string:
|
|
776
|
+
`Buffer.from(string_at(addr, n), "latin1")` recovers all `n` original bytes,
|
|
777
|
+
including embedded NUL and invalid UTF-8. Without a count it retains the
|
|
778
|
+
UTF-8 text representation. `wstring_at` counts native wide-character units.
|
|
779
|
+
|
|
718
780
|
### Error slots
|
|
719
781
|
|
|
720
782
|
- `get_errno()` / `set_errno(v)`
|
|
@@ -734,7 +796,7 @@ Plus the Win32 types, structures and pointer types of `ctypes.wintypes` under `w
|
|
|
734
796
|
|
|
735
797
|
## Python ctypes parity & differences
|
|
736
798
|
|
|
737
|
-
###
|
|
799
|
+
### Supported Python ctypes behavior
|
|
738
800
|
|
|
739
801
|
Structs, unions, bit fields (`_layout_` `"gcc-sysv"` / `"ms"`), anonymous
|
|
740
802
|
fields, `_pack_`, `_align_`, subclasses of structures and unions, nested layouts,
|
|
@@ -831,8 +893,10 @@ needs these changes:
|
|
|
831
893
|
|
|
832
894
|
Each example in `examples/` has its own README; see the [index](examples/README.md).
|
|
833
895
|
|
|
896
|
+
- [Electron + React](examples/cross-platform/electron-app/README.md) — a native system clock through a sandboxed preload bridge, synchronized C-memory views and a packaged ASAR application
|
|
834
897
|
- [Embedded Python](examples/cross-platform/python/README.md) — CPython through its C API: code, modules, callbacks, JavaScript objects by reference, shared memory, threads, asyncio and cancellation (Windows, macOS, Linux)
|
|
835
898
|
- [Smart card (PC/SC)](examples/cross-platform/smartcard/README.md) — `winscard` on Windows, `PCSC.framework` on macOS, `libpcsclite` on Linux
|
|
899
|
+
- [Cryptoki (PKCS #11)](examples/cross-platform/cryptoki/README.md) — complete 3.2 declarations with 2.20–3.2 dispatch and a standalone SoftHSM demo: temporary token, login, RSA, ECDSA, AES and SHA-256
|
|
836
900
|
- [Accessibility](examples/macos/accessibility/README.md) — macOS UI automation with the Accessibility API
|
|
837
901
|
- [COM automation](examples/windows/com/README.md) — shell shortcuts (`IShellLinkW`) and Active Directory (`IDirectorySearch`)
|
|
838
902
|
- [Controls](examples/windows/controls/README.md) — Win32 common controls
|
|
@@ -846,8 +910,18 @@ Each example in `examples/` has its own README; see the [index](examples/README.
|
|
|
846
910
|
|
|
847
911
|
From the repository root, `npm --prefix tests test` first builds a small C library (`tests/fixtures/`, into
|
|
848
912
|
`build/fixture/`) used by the tests of structures by value, array parameters
|
|
849
|
-
and reentrant calls; `npm run build:test-fixture` builds it alone.
|
|
850
|
-
|
|
913
|
+
and reentrant calls; `npm run build:test-fixture` builds it alone. Matched
|
|
914
|
+
Python/JavaScript contracts live under `tests/cpython_parity/`, divided by domain,
|
|
915
|
+
and load the same library. Node-specific async, representation and GC checks
|
|
916
|
+
live under `tests/node_specific/`; genuine Python-only scheduling checks live
|
|
917
|
+
under `tests/python_specific/`. The former `common/` and `windows/` suites have
|
|
918
|
+
been migrated into these domains.
|
|
919
|
+
|
|
920
|
+
Paired JavaScript uses the Python-shaped API: `Structure`/`Union` classes,
|
|
921
|
+
`ARRAY`, library attributes with `argtypes`/`restype`, and `CFUNCTYPE` bindings.
|
|
922
|
+
The structural guard checks neighboring files and matching class/method IDs
|
|
923
|
+
using the existing TypeScript parser and Python AST; runtime assertions remain
|
|
924
|
+
independent checks against CPython, not a claim based on file names alone.
|
|
851
925
|
|
|
852
926
|
```bash
|
|
853
927
|
npm install
|
|
@@ -855,13 +929,16 @@ npm run build
|
|
|
855
929
|
npm --prefix tests install
|
|
856
930
|
npm --prefix tests test # functional/parity tests
|
|
857
931
|
NODE_CTYPES_NO_EXTERNAL_BUFFERS=1 npm --prefix tests test # mirrored native memory
|
|
932
|
+
npm --prefix tests run test:parity # matched CPython and JS contracts
|
|
933
|
+
npm --prefix tests run test:parity:check # paired file/case/discovery/style guard
|
|
934
|
+
npm --prefix tests run test:python # all Python references
|
|
858
935
|
npm run test:types # TypeScript declarations
|
|
859
936
|
npm run docs # TypeDoc API site in docs/
|
|
860
937
|
npm run docs:serve # preview
|
|
861
938
|
```
|
|
862
939
|
|
|
863
|
-
See [
|
|
864
|
-
|
|
940
|
+
See the [test suite guide](tests/README.md) for paired-case conventions,
|
|
941
|
+
runtime differences and focused commands.
|
|
865
942
|
|
|
866
943
|
### Performance comparisons
|
|
867
944
|
|
|
@@ -916,7 +993,16 @@ variadic calls and async calls with 1/8 calls in flight. Cases without an
|
|
|
916
993
|
equivalent documented node:ffi API are listed as **not compared**, not
|
|
917
994
|
emulated with a different native signature.
|
|
918
995
|
|
|
996
|
+
The `CFUNCTYPE` rows measure calls through an already-bound node-ctypes
|
|
997
|
+
prototype, against an independently bound competitor function with the same
|
|
998
|
+
C signature. Bindings are separate to avoid sharing optimization feedback
|
|
999
|
+
with the direct-call rows. These cases do not include prototype construction
|
|
1000
|
+
or callback registration.
|
|
1001
|
+
|
|
919
1002
|
Both sides call the same C fixture and verify results before/after timing.
|
|
1003
|
+
String contents are encoded on every call; node-ctypes reuses scratch storage,
|
|
1004
|
+
not previously encoded strings. Measurements describe warmed repeated calls,
|
|
1005
|
+
not cold-start allocation costs.
|
|
920
1006
|
String lengths are compared as Numbers, including conversion where the API
|
|
921
1007
|
returns BigInt; wide integers are BigInt in both APIs. Structures are plain
|
|
922
1008
|
objects. Async times include scheduling and are reported per completed call,
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/lib/core/Library.js
CHANGED
|
@@ -40,7 +40,7 @@
|
|
|
40
40
|
*/
|
|
41
41
|
|
|
42
42
|
import { _toNativeReturnType } from "./types.js";
|
|
43
|
-
import { adaptCallbackFunction, argumentConverters, argumentsNeedOwners, callWithArgumentOwners, callWithResultHandler, convertArguments,
|
|
43
|
+
import { adaptCallbackFunction, argumentConverters, argumentsNeedOwners, callWithArgumentOwners, callWithResultHandler, convertArguments, resultCheck, resultConverter, scalarResult, specializeCall, structResult } from "./conversions.js";
|
|
44
44
|
import { createTypeKey } from "../utils/cache.js";
|
|
45
45
|
|
|
46
46
|
/**
|
|
@@ -72,7 +72,10 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
|
|
|
72
72
|
class FunctionWrapper {
|
|
73
73
|
constructor(cdll, name) {
|
|
74
74
|
const argtypes = [];
|
|
75
|
+
let declaredArgtypes = [];
|
|
76
|
+
let converters = [];
|
|
75
77
|
let restype = undefined;
|
|
78
|
+
let resultSignature;
|
|
76
79
|
let errcheck = null;
|
|
77
80
|
let cachedFunc = null;
|
|
78
81
|
|
|
@@ -82,7 +85,9 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
|
|
|
82
85
|
// argtypes / restype, come in Python.
|
|
83
86
|
const resolve = () => {
|
|
84
87
|
if (!cachedFunc) {
|
|
85
|
-
|
|
88
|
+
const returnType = restype === undefined ? cdll._defaultRestype() : restype;
|
|
89
|
+
const signature = resultSignature ?? { represent: resultConverter(returnType), check: cdll._resultCheck(returnType, name) };
|
|
90
|
+
cachedFunc = cdll._createFunction(name, returnType, declaredArgtypes, {}, { ...signature, converters });
|
|
86
91
|
Object.defineProperty(cachedFunc, kErrcheckFunc, { value: func });
|
|
87
92
|
if (errcheck !== null) {
|
|
88
93
|
cachedFunc.errcheck = errcheck;
|
|
@@ -102,7 +107,11 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
|
|
|
102
107
|
get: () => argtypes,
|
|
103
108
|
set: (value) => {
|
|
104
109
|
// Python: argtypes = None toglie i tipi degli argomenti.
|
|
105
|
-
|
|
110
|
+
const types = [...(value ?? [])];
|
|
111
|
+
const next = argumentConverters(types, native);
|
|
112
|
+
argtypes.splice(0, argtypes.length, ...types);
|
|
113
|
+
declaredArgtypes = types;
|
|
114
|
+
converters = next;
|
|
106
115
|
cachedFunc = null; // Invalidate cache
|
|
107
116
|
},
|
|
108
117
|
configurable: true,
|
|
@@ -110,6 +119,8 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
|
|
|
110
119
|
restype: {
|
|
111
120
|
get: () => (restype === undefined ? cdll._defaultRestype() : restype),
|
|
112
121
|
set: (value) => {
|
|
122
|
+
const returnType = value === undefined ? cdll._defaultRestype() : value;
|
|
123
|
+
resultSignature = { represent: resultConverter(returnType), check: cdll._resultCheck(returnType, name) };
|
|
113
124
|
restype = value;
|
|
114
125
|
cachedFunc = null; // Invalidate cache
|
|
115
126
|
},
|
|
@@ -214,7 +225,7 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
|
|
|
214
225
|
* Crea una nuova funzione, senza cache (vedi func()).
|
|
215
226
|
* @protected
|
|
216
227
|
*/
|
|
217
|
-
_createFunction(name, returnType, argTypes = [], options = {}) {
|
|
228
|
+
_createFunction(name, returnType, argTypes = [], options = {}, signature) {
|
|
218
229
|
// Propagate library-level use_last_error / use_errno to the FFIFunction
|
|
219
230
|
const mergedOptions = {
|
|
220
231
|
...options,
|
|
@@ -223,26 +234,23 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
|
|
|
223
234
|
...(structResult(returnType) ? { struct_buffer: true } : {}),
|
|
224
235
|
...(scalarResult(returnType) ? { scalar_buffer: true } : {}),
|
|
225
236
|
};
|
|
226
|
-
const ffiFunc = this._lib.func(name, _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native), mergedOptions);
|
|
237
|
+
const ffiFunc = this._lib.func(name, signature?.nativeRestype ?? _toNativeReturnType(returnType, native), signature?.nativeArgtypes ?? _toNativeTypes(argTypes, native), mergedOptions);
|
|
227
238
|
|
|
228
239
|
// =========================================================================
|
|
229
240
|
// OPTIMIZATION: Create specialized wrapper based on argument types
|
|
230
241
|
// For primitive-only args, bypass the processing loop entirely
|
|
231
242
|
// =========================================================================
|
|
232
243
|
|
|
233
|
-
const argCount = argTypes.length;
|
|
234
|
-
|
|
235
244
|
// Conversione degli argomenti come il from_param di base di Python
|
|
236
245
|
// (vedi conversions.js): un convertitore per posizione dichiarata.
|
|
237
|
-
const C = argumentConverters(argTypes, native);
|
|
238
|
-
const [C0, C1, C2, C3, C4, C5] = C;
|
|
246
|
+
const C = signature?.converters ?? argumentConverters(argTypes, native);
|
|
239
247
|
const convertAll = (args) => convertArguments(args, C);
|
|
240
248
|
const hasAdapters = C.some((convert) => convert.requiresOwners);
|
|
241
|
-
const baseConvert = resultConverter(returnType);
|
|
242
|
-
const check = this._resultCheck(returnType, name);
|
|
249
|
+
const baseConvert = signature === undefined ? resultConverter(returnType) : signature.represent;
|
|
250
|
+
const check = signature === undefined ? this._resultCheck(returnType, name) : signature.check;
|
|
243
251
|
const convertResult = check === undefined ? baseConvert : baseConvert === undefined ? check : (result) => check(baseConvert(result));
|
|
244
252
|
const captureHere = convertResult === undefined;
|
|
245
|
-
|
|
253
|
+
const callState = { errcheck: null };
|
|
246
254
|
let checkedSync;
|
|
247
255
|
const checkedCall = (method, args, checked) => {
|
|
248
256
|
const originalArgs = Array.isArray(args) ? args : Array.prototype.slice.call(args);
|
|
@@ -252,71 +260,13 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
|
|
|
252
260
|
return callWithResultHandler(ffiFunc, method, originalArgs, C, finish, hasAdapters || argumentsNeedOwners(originalArgs), call);
|
|
253
261
|
};
|
|
254
262
|
const ownedCall = (method, args) => callWithArgumentOwners(ffiFunc, method, args, C);
|
|
255
|
-
const invoke = (method, args) => {
|
|
256
|
-
if (captureHere &&
|
|
263
|
+
const invoke = (method, args, checked) => {
|
|
264
|
+
if (captureHere && checked !== null) return checkedCall(method, args, checked);
|
|
257
265
|
return captureHere && (hasAdapters || argumentsNeedOwners(args)) ? ownedCall(method, args) : ffiFunc[method](...convertAll(args));
|
|
258
266
|
};
|
|
259
267
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
const specialize = (method) => {
|
|
263
|
-
switch (argCount) {
|
|
264
|
-
case 0:
|
|
265
|
-
return function () {
|
|
266
|
-
if (captureHere && jsErrcheck !== null) return checkedCall(method, arguments, jsErrcheck);
|
|
267
|
-
return arguments.length === 0 ? ffiFunc[method]() : invoke(method, arguments);
|
|
268
|
-
};
|
|
269
|
-
case 1:
|
|
270
|
-
return function (a0) {
|
|
271
|
-
if (captureHere && jsErrcheck !== null) return checkedCall(method, arguments, jsErrcheck);
|
|
272
|
-
if (arguments.length !== 1) return invoke(method, arguments);
|
|
273
|
-
if (captureHere && (hasAdapters || needsArgumentOwners(a0))) return ownedCall(method, arguments);
|
|
274
|
-
return ffiFunc[method](C0(a0));
|
|
275
|
-
};
|
|
276
|
-
case 2:
|
|
277
|
-
return function (a0, a1) {
|
|
278
|
-
if (captureHere && jsErrcheck !== null) return checkedCall(method, arguments, jsErrcheck);
|
|
279
|
-
if (arguments.length !== 2) return invoke(method, arguments);
|
|
280
|
-
if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1))) return ownedCall(method, arguments);
|
|
281
|
-
return ffiFunc[method](C0(a0), C1(a1));
|
|
282
|
-
};
|
|
283
|
-
case 3:
|
|
284
|
-
return function (a0, a1, a2) {
|
|
285
|
-
if (captureHere && jsErrcheck !== null) return checkedCall(method, arguments, jsErrcheck);
|
|
286
|
-
if (arguments.length !== 3) return invoke(method, arguments);
|
|
287
|
-
if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2))) return ownedCall(method, arguments);
|
|
288
|
-
return ffiFunc[method](C0(a0), C1(a1), C2(a2));
|
|
289
|
-
};
|
|
290
|
-
case 4:
|
|
291
|
-
return function (a0, a1, a2, a3) {
|
|
292
|
-
if (captureHere && jsErrcheck !== null) return checkedCall(method, arguments, jsErrcheck);
|
|
293
|
-
if (arguments.length !== 4) return invoke(method, arguments);
|
|
294
|
-
if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2) || needsArgumentOwners(a3))) return ownedCall(method, arguments);
|
|
295
|
-
return ffiFunc[method](C0(a0), C1(a1), C2(a2), C3(a3));
|
|
296
|
-
};
|
|
297
|
-
case 5:
|
|
298
|
-
return function (a0, a1, a2, a3, a4) {
|
|
299
|
-
if (captureHere && jsErrcheck !== null) return checkedCall(method, arguments, jsErrcheck);
|
|
300
|
-
if (arguments.length !== 5) return invoke(method, arguments);
|
|
301
|
-
if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2) || needsArgumentOwners(a3) || needsArgumentOwners(a4))) return ownedCall(method, arguments);
|
|
302
|
-
return ffiFunc[method](C0(a0), C1(a1), C2(a2), C3(a3), C4(a4));
|
|
303
|
-
};
|
|
304
|
-
case 6:
|
|
305
|
-
return function (a0, a1, a2, a3, a4, a5) {
|
|
306
|
-
if (captureHere && jsErrcheck !== null) return checkedCall(method, arguments, jsErrcheck);
|
|
307
|
-
if (arguments.length !== 6) return invoke(method, arguments);
|
|
308
|
-
if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2) || needsArgumentOwners(a3) || needsArgumentOwners(a4) || needsArgumentOwners(a5))) return ownedCall(method, arguments);
|
|
309
|
-
return ffiFunc[method](C0(a0), C1(a1), C2(a2), C3(a3), C4(a4), C5(a5));
|
|
310
|
-
};
|
|
311
|
-
default:
|
|
312
|
-
return function (...args) {
|
|
313
|
-
return invoke(method, args);
|
|
314
|
-
};
|
|
315
|
-
}
|
|
316
|
-
};
|
|
317
|
-
|
|
318
|
-
let callMethod = specialize("call");
|
|
319
|
-
let asyncCallMethod = specialize("callAsync");
|
|
268
|
+
let callMethod = specializeCall(ffiFunc, "call", C, callState, (args, checked) => invoke("call", args, checked), captureHere);
|
|
269
|
+
let asyncCallMethod = specializeCall(ffiFunc, "callAsync", C, callState, (args, checked) => invoke("callAsync", args, checked), captureHere);
|
|
320
270
|
|
|
321
271
|
// Result handlers run inside the native call scope, after conversion and
|
|
322
272
|
// with the hook/arguments captured before any argument adapter executes.
|
|
@@ -325,12 +275,12 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
|
|
|
325
275
|
const rawAsync = asyncCallMethod;
|
|
326
276
|
const finish = (result) => convertResult(result);
|
|
327
277
|
callMethod = function (...args) {
|
|
328
|
-
if (
|
|
278
|
+
if (callState.errcheck !== null) return checkedCall("call", args, callState.errcheck);
|
|
329
279
|
if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "call", args, C, finish);
|
|
330
280
|
return finish(rawCall.apply(this, args), args);
|
|
331
281
|
};
|
|
332
282
|
asyncCallMethod = function (...args) {
|
|
333
|
-
if (
|
|
283
|
+
if (callState.errcheck !== null) return checkedCall("callAsync", args, callState.errcheck);
|
|
334
284
|
if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, C, finish);
|
|
335
285
|
return rawAsync.apply(this, args).then((result) => finish(result, args));
|
|
336
286
|
};
|
|
@@ -366,12 +316,12 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
|
|
|
366
316
|
// Esponi errcheck come setter/getter
|
|
367
317
|
errcheck: {
|
|
368
318
|
get() {
|
|
369
|
-
return
|
|
319
|
+
return callState.errcheck;
|
|
370
320
|
},
|
|
371
321
|
set(callback) {
|
|
372
322
|
callback = callback ?? null;
|
|
373
323
|
if (callback !== null && typeof callback !== "function") throw new TypeError("errcheck must be a function or null");
|
|
374
|
-
|
|
324
|
+
callState.errcheck = callback;
|
|
375
325
|
},
|
|
376
326
|
enumerable: false,
|
|
377
327
|
configurable: true,
|
|
@@ -448,11 +398,17 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
|
|
|
448
398
|
* WinDLL - come CDLL ma con stdcall di default (per Windows)
|
|
449
399
|
*/
|
|
450
400
|
class WinDLL extends CDLL {
|
|
451
|
-
_createFunction(name, returnType, argTypes = [], options = {}) {
|
|
452
|
-
return super._createFunction(
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
401
|
+
_createFunction(name, returnType, argTypes = [], options = {}, signature) {
|
|
402
|
+
return super._createFunction(
|
|
403
|
+
name,
|
|
404
|
+
returnType,
|
|
405
|
+
argTypes,
|
|
406
|
+
{
|
|
407
|
+
abi: "stdcall",
|
|
408
|
+
...options,
|
|
409
|
+
},
|
|
410
|
+
signature,
|
|
411
|
+
);
|
|
456
412
|
}
|
|
457
413
|
}
|
|
458
414
|
|
package/lib/core/callback.js
CHANGED
|
@@ -57,6 +57,31 @@ import { _toNativeReturnType, _toNativeTypes } from "./types.js";
|
|
|
57
57
|
import { adaptCallbackFunction, scalarResult } from "./conversions.js";
|
|
58
58
|
import { trackCallback } from "./callback-tracker.js";
|
|
59
59
|
|
|
60
|
+
function nativeContextHook(value, name, owners) {
|
|
61
|
+
if (value !== null && (typeof value === "object" || typeof value === "function")) {
|
|
62
|
+
if ("_callback" in value) throw new TypeError(`nativeContext.${name} must not execute JavaScript`);
|
|
63
|
+
const parameter = value._as_parameter_;
|
|
64
|
+
const address = parameter === undefined ? value.address : parameter;
|
|
65
|
+
if (typeof address !== "bigint") throw new TypeError(`nativeContext.${name} must be a native function or BigInt address`);
|
|
66
|
+
owners.push(value);
|
|
67
|
+
return address;
|
|
68
|
+
}
|
|
69
|
+
if (typeof value !== "bigint") throw new TypeError(`nativeContext.${name} must be a native function or BigInt address`);
|
|
70
|
+
return value;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function nativeContextAddresses(context, owners) {
|
|
74
|
+
if (context === null || typeof context !== "object") throw new TypeError("nativeContext must contain suspend, resume and onError hooks");
|
|
75
|
+
const addresses = {
|
|
76
|
+
suspend: nativeContextHook(context.suspend, "suspend", owners),
|
|
77
|
+
resume: nativeContextHook(context.resume, "resume", owners),
|
|
78
|
+
onError: nativeContextHook(context.onError, "onError", owners),
|
|
79
|
+
};
|
|
80
|
+
const notify = context.notify;
|
|
81
|
+
if (notify !== undefined) addresses.notify = nativeContextHook(notify, "notify", owners);
|
|
82
|
+
return addresses;
|
|
83
|
+
}
|
|
84
|
+
|
|
60
85
|
/**
|
|
61
86
|
* Creates a C-callable callback from a JavaScript function (main-thread only).
|
|
62
87
|
*
|
|
@@ -164,8 +189,8 @@ export function callback(fn, returnType, argTypes = [], native, abi = undefined)
|
|
|
164
189
|
},
|
|
165
190
|
_callback: cb,
|
|
166
191
|
};
|
|
167
|
-
// Python ctypes parity:
|
|
168
|
-
//
|
|
192
|
+
// Python ctypes parity: pass the callback directly as an argument,
|
|
193
|
+
// e.g. qsort(arr, n, size, cmp). Non-enumerable to preserve Object.keys.
|
|
169
194
|
Object.defineProperty(wrapper, "_as_parameter_", {
|
|
170
195
|
get() {
|
|
171
196
|
return cb.pointer;
|
|
@@ -276,10 +301,26 @@ export function callback(fn, returnType, argTypes = [], native, abi = undefined)
|
|
|
276
301
|
* @throws {Error} If callback creation fails or type conversion fails
|
|
277
302
|
* @see {@link callback} for main-thread-only callbacks
|
|
278
303
|
*/
|
|
279
|
-
export function threadSafeCallback(fn, returnType, argTypes = [], native,
|
|
280
|
-
const
|
|
304
|
+
export function threadSafeCallback(fn, returnType, argTypes = [], native, options = undefined) {
|
|
305
|
+
const { abi, nativeContext } = typeof options === "object" && options !== null ? options : { abi: options };
|
|
306
|
+
const owners = [];
|
|
307
|
+
const context = nativeContext === undefined ? undefined : nativeContextAddresses(nativeContext, owners);
|
|
308
|
+
const adapted = adaptCallbackFunction(fn, argTypes, returnType, native);
|
|
309
|
+
// Both the native callback and TSFN pin this function through queued delivery.
|
|
310
|
+
const dispatch =
|
|
311
|
+
owners.length === 0
|
|
312
|
+
? adapted
|
|
313
|
+
: Object.defineProperty(
|
|
314
|
+
function (...args) {
|
|
315
|
+
return Reflect.apply(adapted, this, args);
|
|
316
|
+
},
|
|
317
|
+
"_objects",
|
|
318
|
+
{ value: owners },
|
|
319
|
+
);
|
|
320
|
+
const args = [dispatch, _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native)];
|
|
281
321
|
const scalarArgs = argTypes.map(scalarResult);
|
|
282
|
-
if (
|
|
322
|
+
if (context !== undefined) args.push(abi ?? "default", scalarArgs, context);
|
|
323
|
+
else if (scalarArgs.some(Boolean)) args.push(abi ?? "default", scalarArgs);
|
|
283
324
|
else if (abi) args.push(abi);
|
|
284
325
|
const cb = new native.ThreadSafeCallback(...args);
|
|
285
326
|
|
|
@@ -298,13 +339,19 @@ export function threadSafeCallback(fn, returnType, argTypes = [], native, abi =
|
|
|
298
339
|
cb.unref();
|
|
299
340
|
return wrapper;
|
|
300
341
|
},
|
|
342
|
+
setNativeError(error) {
|
|
343
|
+
cb.setNativeError(error);
|
|
344
|
+
},
|
|
345
|
+
drain() {
|
|
346
|
+
return cb.drain();
|
|
347
|
+
},
|
|
301
348
|
[Symbol.dispose]() {
|
|
302
349
|
cb.release();
|
|
303
350
|
},
|
|
304
351
|
_callback: cb,
|
|
305
352
|
};
|
|
306
|
-
// Python ctypes parity:
|
|
307
|
-
//
|
|
353
|
+
// Python ctypes parity: pass the callback directly as an argument,
|
|
354
|
+
// e.g. qsort(arr, n, size, cmp). Non-enumerable to preserve Object.keys.
|
|
308
355
|
Object.defineProperty(wrapper, "_as_parameter_", {
|
|
309
356
|
get() {
|
|
310
357
|
return cb.pointer;
|