node-ctypes 2.11.1 → 2.12.1
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 +74 -1
- package/README.md +11 -0
- 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/index.d.ts +23 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [2.12.1] - 2026-11-11
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
- **Executor inline wait per function**: the JavaScript thread now waits for
|
|
15
|
+
a call for about one and a half times the typical duration of its function
|
|
16
|
+
(measured on every call; shorter durations weigh more, so a slow first call
|
|
17
|
+
is forgotten in a few calls), at least `spin` and at most the new
|
|
18
|
+
`spinLimit` option (microseconds, default 500, `0` for never more than
|
|
19
|
+
`spin`); a function that usually takes longer is not waited for. Before, a
|
|
20
|
+
single backoff per executor skipped the wait for every function after a slow
|
|
21
|
+
call: a slow function alternated with fast ones (e.g. ADSI `GetColumn`
|
|
22
|
+
with `FreeColumn`) sent the fast ones through the event loop too. On that
|
|
23
|
+
pattern (one call of 65 µs and two fast calls) the overhead per round drops
|
|
24
|
+
from about 47 µs to about 18 µs. The backoff is now per function: when its
|
|
25
|
+
waits time out (e.g. where the executor thread wakes up slowly), a function
|
|
26
|
+
skips the next 1, 3, 7, ... up to 1023 waits, without affecting the others.
|
|
27
|
+
|
|
28
|
+
### Fixed
|
|
29
|
+
|
|
30
|
+
- **Executor busy waits on a loaded machine**: the busy waits called
|
|
31
|
+
`std::this_thread::yield()`, which, with other threads ready on the same
|
|
32
|
+
core, gives the core away for a whole time slice: on a loaded machine (CI
|
|
33
|
+
VMs running test files in parallel) each call cost tens of milliseconds, 401
|
|
34
|
+
awaited calls 13 s instead of 0.13 s. The waits no longer yield, the
|
|
35
|
+
executor thread polls for the next call for at most 50 µs whatever `spin`
|
|
36
|
+
is, and the JavaScript thread stops waiting as soon as a native thread waits
|
|
37
|
+
for it (a thread-safe callback invoked by the awaited call). Under load the
|
|
38
|
+
fast path is now 3 to 5 times faster than `spin: 0`, as on an idle machine.
|
|
39
|
+
|
|
40
|
+
### Added
|
|
41
|
+
|
|
42
|
+
- **`Executor` `spinLimit` option**, and tests for the per-function wait
|
|
43
|
+
(a function beyond `spin` within `spinLimit`, a slow function alternated
|
|
44
|
+
with a fast one, a function that becomes fast again), checking the budget
|
|
45
|
+
computed per function (independent of the speed of the machine); test fixture
|
|
46
|
+
function `fixture_busy_wait_us`.
|
|
47
|
+
|
|
48
|
+
## [2.12.0] - 2026-11-10
|
|
49
|
+
|
|
50
|
+
### Added
|
|
51
|
+
|
|
52
|
+
- **`Executor` `spin` option** (microseconds, default 50, `0` disables, at
|
|
53
|
+
most 10000): after a call the executor thread polls for the next one this
|
|
54
|
+
long before sleeping, and the JavaScript thread waits this long for a call
|
|
55
|
+
submitted to an executor with nothing queued, completing it without a round
|
|
56
|
+
trip through the event loop. Awaited calls in sequence go from about 37 µs to
|
|
57
|
+
about 4 µs each on Windows x64 (the same as a burst).
|
|
58
|
+
- **Tests**: spin option validation, awaited calls with and without spin,
|
|
59
|
+
errcheck calling the same executor during an inline completion, slow calls
|
|
60
|
+
falling back to the notification, thread-safe callbacks from the executor
|
|
61
|
+
thread while the JavaScript thread waits, and immediates/timers running
|
|
62
|
+
during awaited calls and bursts.
|
|
63
|
+
|
|
64
|
+
### Changed
|
|
65
|
+
|
|
66
|
+
- **Executor completions**: a call that completes within the `spin` budget is
|
|
67
|
+
completed before `callOn` returns: its errcheck runs then and the promise is
|
|
68
|
+
already settled (`await` still resumes asynchronously).
|
|
69
|
+
- **Event loop fairness**: inline completions are limited to 1 ms per turn of
|
|
70
|
+
the event loop (a turn is detected by delivering a marker through the
|
|
71
|
+
executor's thread-safe function); after that, calls are completed through
|
|
72
|
+
the thread-safe function so that timers, I/O and UI events run, and a burst
|
|
73
|
+
submitted in one go is queued instead of blocking the JavaScript thread.
|
|
74
|
+
Waits that time out (slow calls) are skipped for the following calls, with
|
|
75
|
+
exponential backoff up to 1024 calls, until one completes in time again.
|
|
76
|
+
- **Executor internals**: Node-API calls go through node-addon-api
|
|
77
|
+
(`TypedThreadSafeFunction::NonBlockingCall`,
|
|
78
|
+
`Error::ThrowAsJavaScriptException`, `Env::AddCleanupHook`); the executor
|
|
79
|
+
thread signals its condition variable only when the thread is asleep.
|
|
80
|
+
|
|
10
81
|
## [2.11.1] - 2026-11-10
|
|
11
82
|
|
|
12
83
|
### Fixed
|
|
@@ -1200,7 +1271,9 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
|
|
|
1200
1271
|
|
|
1201
1272
|
Initial releases.
|
|
1202
1273
|
|
|
1203
|
-
[Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.
|
|
1274
|
+
[Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.12.1...HEAD
|
|
1275
|
+
[2.12.1]: https://github.com/dmazzella/node-ctypes/compare/v2.12.0...v2.12.1
|
|
1276
|
+
[2.12.0]: https://github.com/dmazzella/node-ctypes/compare/v2.11.1...v2.12.0
|
|
1204
1277
|
[2.11.1]: https://github.com/dmazzella/node-ctypes/compare/v2.11.0...v2.11.1
|
|
1205
1278
|
[2.11.0]: https://github.com/dmazzella/node-ctypes/compare/v2.10.0...v2.11.0
|
|
1206
1279
|
[2.10.0]: https://github.com/dmazzella/node-ctypes/compare/v2.9.0...v2.10.0
|
package/README.md
CHANGED
|
@@ -135,6 +135,17 @@ await executor.close(); // waits for the accepted calls, then stops the thread
|
|
|
135
135
|
longer referenced. `close()` rejects new calls, waits for the accepted ones
|
|
136
136
|
and stops the thread (an executor cannot be reopened).
|
|
137
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.
|
|
138
149
|
- A call that has started cannot be interrupted: the signal only removes
|
|
139
150
|
queued calls.
|
|
140
151
|
- On process exit (or worker termination) queued calls are discarded and a
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/lib/index.d.ts
CHANGED
|
@@ -749,6 +749,25 @@ export class ThreadSafeCallback extends Callback {
|
|
|
749
749
|
export interface ExecutorOptions {
|
|
750
750
|
/** Thread name shown by debuggers and profilers (default `"node-ctypes"`). */
|
|
751
751
|
name?: string;
|
|
752
|
+
/**
|
|
753
|
+
* Busy-wait budget in microseconds (default 50, 0 to disable, at most
|
|
754
|
+
* 10000). After a call the executor thread polls for the next one this long
|
|
755
|
+
* (at most 50 µs) before sleeping, and the JavaScript thread waits for a call submitted to
|
|
756
|
+
* an idle executor, completing it without a round trip through the event
|
|
757
|
+
* loop: awaited calls in sequence cost a few microseconds instead of tens.
|
|
758
|
+
* The JavaScript thread waits `spin` for a function not called yet; then,
|
|
759
|
+
* per function, about one and a half times its typical duration (measured
|
|
760
|
+
* on every call), at least `spin` and at most {@link spinLimit}. A function
|
|
761
|
+
* that usually takes longer is not waited for: its calls complete through
|
|
762
|
+
* the event loop, without delaying the others.
|
|
763
|
+
*/
|
|
764
|
+
spin?: number;
|
|
765
|
+
/**
|
|
766
|
+
* Longest wait in microseconds for a function that usually takes longer
|
|
767
|
+
* than {@link spin} (default 500, at most 10000; 0: never more than
|
|
768
|
+
* `spin`).
|
|
769
|
+
*/
|
|
770
|
+
spinLimit?: number;
|
|
752
771
|
}
|
|
753
772
|
|
|
754
773
|
/**
|
|
@@ -774,6 +793,10 @@ export type ExecutorTarget = Executor | { readonly executor: Executor; readonly
|
|
|
774
793
|
* terminates) queued calls are discarded and a running call is left to finish
|
|
775
794
|
* on its own.
|
|
776
795
|
*
|
|
796
|
+
* A call that completes within the {@link ExecutorOptions.spin} budget is
|
|
797
|
+
* completed before `callOn` returns: its errcheck runs then, and the promise
|
|
798
|
+
* is already settled (`await` still resumes asynchronously).
|
|
799
|
+
*
|
|
777
800
|
* No Python equivalent.
|
|
778
801
|
*
|
|
779
802
|
* @example
|