node-ctypes 2.11.1 → 2.12.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 CHANGED
@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.12.0] - 2026-11-10
11
+
12
+ ### Added
13
+
14
+ - **`Executor` `spin` option** (microseconds, default 50, `0` disables, at
15
+ most 10000): after a call the executor thread polls for the next one this
16
+ long before sleeping, and the JavaScript thread waits this long for a call
17
+ submitted to an executor with nothing queued, completing it without a round
18
+ trip through the event loop. Awaited calls in sequence go from about 37 µs to
19
+ about 4 µs each on Windows x64 (the same as a burst).
20
+ - **Tests**: spin option validation, awaited calls with and without spin,
21
+ errcheck calling the same executor during an inline completion, slow calls
22
+ falling back to the notification, thread-safe callbacks from the executor
23
+ thread while the JavaScript thread waits, and immediates/timers running
24
+ during awaited calls and bursts.
25
+
26
+ ### Changed
27
+
28
+ - **Executor completions**: a call that completes within the `spin` budget is
29
+ completed before `callOn` returns: its errcheck runs then and the promise is
30
+ already settled (`await` still resumes asynchronously).
31
+ - **Event loop fairness**: inline completions are limited to 1 ms per turn of
32
+ the event loop (a turn is detected by delivering a marker through the
33
+ executor's thread-safe function); after that, calls are completed through
34
+ the thread-safe function so that timers, I/O and UI events run, and a burst
35
+ submitted in one go is queued instead of blocking the JavaScript thread.
36
+ Waits that time out (slow calls) are skipped for the following calls, with
37
+ exponential backoff up to 1024 calls, until one completes in time again.
38
+ - **Executor internals**: Node-API calls go through node-addon-api
39
+ (`TypedThreadSafeFunction::NonBlockingCall`,
40
+ `Error::ThrowAsJavaScriptException`, `Env::AddCleanupHook`); the executor
41
+ thread signals its condition variable only when the thread is asleep.
42
+
10
43
  ## [2.11.1] - 2026-11-10
11
44
 
12
45
  ### Fixed
@@ -1200,7 +1233,8 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
1200
1233
 
1201
1234
  Initial releases.
1202
1235
 
1203
- [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.11.1...HEAD
1236
+ [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.12.0...HEAD
1237
+ [2.12.0]: https://github.com/dmazzella/node-ctypes/compare/v2.11.1...v2.12.0
1204
1238
  [2.11.1]: https://github.com/dmazzella/node-ctypes/compare/v2.11.0...v2.11.1
1205
1239
  [2.11.0]: https://github.com/dmazzella/node-ctypes/compare/v2.10.0...v2.11.0
1206
1240
  [2.10.0]: https://github.com/dmazzella/node-ctypes/compare/v2.9.0...v2.10.0
package/README.md CHANGED
@@ -135,6 +135,14 @@ 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 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. Inline completions are limited to 1 ms per turn of the
144
+ event loop, so timers, I/O and UI events keep running; slow calls fall back
145
+ to the normal notification.
138
146
  - A call that has started cannot be interrupted: the signal only removes
139
147
  queued calls.
140
148
  - 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,16 @@ 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
+ * before sleeping, and the JavaScript thread waits this long for a call
756
+ * submitted to an idle executor, completing it without a round trip through
757
+ * the event loop: awaited calls in sequence cost a few microseconds instead
758
+ * of tens. When the wait times out (slow calls) the following calls skip it,
759
+ * with exponential backoff, until one completes in time again.
760
+ */
761
+ spin?: number;
752
762
  }
753
763
 
754
764
  /**
@@ -774,6 +784,10 @@ export type ExecutorTarget = Executor | { readonly executor: Executor; readonly
774
784
  * terminates) queued calls are discarded and a running call is left to finish
775
785
  * on its own.
776
786
  *
787
+ * A call that completes within the {@link ExecutorOptions.spin} budget is
788
+ * completed before `callOn` returns: its errcheck runs then, and the promise
789
+ * is already settled (`await` still resumes asynchronously).
790
+ *
777
791
  * No Python equivalent.
778
792
  *
779
793
  * @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.0",
4
4
  "description": "Python ctypes-like FFI for Node.js using libffi",
5
5
  "author": "Damiano Mazzella",
6
6
  "license": "MIT",