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 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.11.1...HEAD
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
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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-ctypes",
3
- "version": "2.11.1",
3
+ "version": "2.12.1",
4
4
  "description": "Python ctypes-like FFI for Node.js using libffi",
5
5
  "author": "Damiano Mazzella",
6
6
  "license": "MIT",