node-ctypes 2.9.0 → 2.11.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,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.11.0] - 2026-11-10
11
+
12
+ ### Added
13
+
14
+ - **`Executor` and `fn.callOn(executor, ...args)`**: a native thread owned by
15
+ node-ctypes with a FIFO queue. `callOn` is the same call as `callAsync`
16
+ (conversions, out parameters, structures, variadic arguments, `errcheck`,
17
+ argument lifetime), run on that thread instead of a libuv worker: calls run
18
+ one at a time in arrival order and never occupy the libuv pool. Queued calls
19
+ can be cancelled with an `AbortSignal` (`callOn({ executor, signal }, ...)`);
20
+ `close()` waits for the accepted calls and stops the thread. Pending calls
21
+ keep the process alive, an idle executor does not; on process exit or worker
22
+ termination queued calls are discarded and a running call is detached.
23
+
24
+ ### Changed
25
+
26
+ - **Asynchronous call internals**: the converted arguments of `callAsync` are
27
+ held by a call object shared with `callOn`; the libuv worker only runs it.
28
+ Behavior is unchanged.
29
+
30
+ ### Documentation
31
+
32
+ - **Asynchronous calls**: document `callAsync` on the libuv pool, when to use
33
+ an `Executor`, cancellation, `close()` and the process lifetime.
34
+
35
+ ## [2.10.0] - 2026-11-06
36
+
37
+ ### Fixed
38
+
39
+ - **Callback exception boundary**: a C++ exception other than a Node-API error
40
+ (for example `std::bad_alloc` while copying an aggregate) raised while
41
+ converting arguments or results, calling the JavaScript function, its error
42
+ handler or the warning fallback is recorded and yields a zero result instead
43
+ of crossing the native callback frame.
44
+ - **Callback snapshot pool isolation**: snapshots of callback arguments no
45
+ longer share their pool with native-call temporaries. Since 2.9.0, detaching
46
+ a snapshot's `ArrayBuffer` broke every later by-value structure argument and
47
+ structure callback, and could let JavaScript read, alter or release memory
48
+ still used by an in-flight native call. A detached pool is now replaced.
49
+ - **Detached buffer arguments**: a Buffer, typed array, DataView or ArrayBuffer
50
+ argument detached while native code could still use it (by a callback during
51
+ a synchronous call, or before a `callAsync()` completes) now makes the call
52
+ throw or reject instead of returning silently. Node-API cannot prevent the
53
+ detach; synchronous calls check only when a JavaScript callback ran.
54
+
55
+ ### Documentation
56
+
57
+ - **Callback snapshot pool**: document the dedicated snapshot pool, how
58
+ retention affects memory and why the underlying `ArrayBuffer` should not be
59
+ exposed without copying.
60
+
10
61
  ## [2.9.0] - 2026-11-05
11
62
 
12
63
  ### Added
@@ -1130,7 +1181,9 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
1130
1181
 
1131
1182
  Initial releases.
1132
1183
 
1133
- [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.9.0...HEAD
1184
+ [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.11.0...HEAD
1185
+ [2.11.0]: https://github.com/dmazzella/node-ctypes/compare/v2.10.0...v2.11.0
1186
+ [2.10.0]: https://github.com/dmazzella/node-ctypes/compare/v2.9.0...v2.10.0
1134
1187
  [2.9.0]: https://github.com/dmazzella/node-ctypes/compare/v2.8.0...v2.9.0
1135
1188
  [2.8.0]: https://github.com/dmazzella/node-ctypes/compare/v2.7.0...v2.8.0
1136
1189
  [2.7.0]: https://github.com/dmazzella/node-ctypes/compare/v2.6.0...v2.7.0
package/README.md CHANGED
@@ -101,6 +101,47 @@ additional arguments bypass fixed invokers and prepare their libffi metadata
101
101
  on the JavaScript thread. Inferred calls use the ordinary ABI; true variadic
102
102
  calls preserve the declared named-prefix boundary.
103
103
 
104
+ ### Asynchronous calls: `callAsync` and `Executor`
105
+
106
+ `fn.callAsync(...args)` runs the call on a libuv worker and returns a promise;
107
+ the event loop stays free meanwhile. Arguments are converted on the
108
+ JavaScript thread before the call, results (and `errcheck`) after it, and the
109
+ memory passed by address stays referenced until the promise settles.
110
+
111
+ libuv workers are shared with `fs`, `dns` and `crypto` (4 by default), and
112
+ concurrent calls run in parallel in any order. For long or blocking calls, or
113
+ calls that must run in sequence on one thread (thread-local state,
114
+ thread-affine handles, libraries that are not thread-safe), use an
115
+ `Executor`: a native thread owned by node-ctypes with a FIFO queue.
116
+ `fn.callOn(executor, ...args)` is the same call as `callAsync`, run there:
117
+
118
+ ```javascript
119
+ import { Executor } from "node-ctypes";
120
+
121
+ const executor = new Executor({ name: "device" }); // thread name for debuggers
122
+ const read = await lib.device_read.callOn(executor, handle, buffer, buffer.length);
123
+
124
+ // Cancel a call that has not started yet: the promise rejects with signal.reason.
125
+ const controller = new AbortController();
126
+ const next = lib.device_read.callOn({ executor, signal: controller.signal }, handle, buffer, buffer.length);
127
+ controller.abort();
128
+
129
+ await executor.close(); // waits for the accepted calls, then stops the thread
130
+ ```
131
+
132
+ - Calls run one at a time, in arrival order; each promise settles once.
133
+ - The thread starts with the first call. Pending calls keep the process
134
+ alive; an idle executor does not, and is collected with its thread when no
135
+ longer referenced. `close()` rejects new calls, waits for the accepted ones
136
+ and stops the thread (an executor cannot be reopened).
137
+ - `executor.pending`, `completed`, `running` and `closed` report its state.
138
+ - A call that has started cannot be interrupted: the signal only removes
139
+ queued calls.
140
+ - On process exit (or worker termination) queued calls are discarded and a
141
+ running call is left to finish on its own.
142
+ - Callbacks invoked during the call run on the executor thread: use
143
+ `threadSafeCallback`, as with `callAsync`.
144
+
104
145
  ### Structs, unions, bit fields, arrays
105
146
 
106
147
  ```javascript
@@ -297,6 +338,25 @@ Existing callers retain their result-check snapshot and their own `errcheck`.
297
338
  An installed `from_param` converter still resolves the method at call time,
298
339
  as before.
299
340
 
341
+ Structure, union and scalar-instance arguments received by `callback()`,
342
+ `CFUNCTYPE` and `threadSafeCallback()` are owned snapshots: each one is a
343
+ distinct slice of an 8 KB off-heap pool reserved for callback snapshots.
344
+ Native-call temporaries use a separate pool that is never exposed, so a
345
+ snapshot cannot reveal or alter memory that native code is still using.
346
+ Slices are never reused, so a retained argument keeps its own bytes and
347
+ identity. Detaching a snapshot's `ArrayBuffer` (`transfer()`, a transfer list)
348
+ only affects the snapshots in that pool; later callbacks use a fresh one.
349
+
350
+ - Retaining any slice keeps its whole 8 KB backing `ArrayBuffer` alive. When
351
+ storing many small arguments for a long time, copy them, for example
352
+ `Buffer.from(value._buffer)` or a new instance built from its fields.
353
+ - `value._buffer.buffer` is the whole pool and can contain other callback
354
+ snapshots. Use `_buffer` itself (or `byteOffset` and `length`), and copy
355
+ before handing the underlying `ArrayBuffer` to untrusted code.
356
+
357
+ Values larger than 2 KB, layouts aligned to more than 8 bytes and raw native
358
+ callbacks keep a dedicated allocation.
359
+
300
360
  Both callbacks and libraries implement `Symbol.dispose`, so they work
301
361
  with the `using` declaration for scope-bound cleanup (also on `throw`):
302
362
 
@@ -593,6 +653,17 @@ still stop at its end; raw native addresses remain the caller's responsibility.
593
653
  Scalar `from_buffer()` / `from_buffer_copy()` validate byte size and offset
594
654
  before producing an instance and accept Buffer, typed views and ctypes memory.
595
655
 
656
+ Do not detach (`ArrayBuffer.prototype.transfer()`, a `postMessage` /
657
+ `structuredClone` transfer list) memory passed to a call that is still running:
658
+ a pending `callAsync()`, or the outer call while a callback runs. Native code
659
+ keeps its address and may access memory that now belongs to another
660
+ `ArrayBuffer` or has been released. Node-API cannot prevent the detach, so
661
+ node-ctypes reports it instead. A synchronous call during which a JavaScript
662
+ callback ran throws `argument N: memory was detached ...` after native code
663
+ returns, and a `callAsync()` whose Buffer, typed array, DataView or ArrayBuffer
664
+ argument was detached rejects. The check covers those arguments as passed,
665
+ not addresses stored inside structures or obtained with `addressof()`.
666
+
596
667
  ### Electron
597
668
 
598
669
  Electron does not allow Buffers over memory that V8 did not allocate, so a
Binary file
Binary file
@@ -42,6 +42,7 @@
42
42
  import { _toNativeReturnType } from "./types.js";
43
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
+ import { callOn } from "./executor.js";
45
46
 
46
47
  /**
47
48
  * Creates the Library-related classes with required dependencies injected.
@@ -143,6 +144,11 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
143
144
  set: () => {},
144
145
  configurable: true,
145
146
  },
147
+ callOn: {
148
+ get: () => resolve().callOn,
149
+ set: () => {},
150
+ configurable: true,
151
+ },
146
152
  });
147
153
 
148
154
  return func;
@@ -314,6 +320,7 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
314
320
  _as_parameter_: { value: ffiFunc.address },
315
321
  _ffi: { value: ffiFunc },
316
322
  callAsync: { value: asyncCallMethod, writable: false, enumerable: false, configurable: false },
323
+ callOn: { value: (target, ...args) => callOn(callMethod, target, args), writable: false, enumerable: false, configurable: false },
317
324
  // Esponi errcheck come setter/getter
318
325
  errcheck: {
319
326
  get() {
@@ -57,7 +57,7 @@ import { _toNativeReturnType, _toNativeTypes } from "./types.js";
57
57
  import { adaptCallbackFunction, scalarResult } from "./conversions.js";
58
58
  import { trackCallback } from "./callback-tracker.js";
59
59
  import { callbackPointer } from "../structures/helpers/common.js";
60
- import { allocTransient } from "../memory/buffer.js";
60
+ import { allocSnapshot } from "../memory/buffer.js";
61
61
 
62
62
  function nativeContextHook(value, name, owners) {
63
63
  if (value !== null && (typeof value === "object" || typeof value === "function")) {
@@ -176,7 +176,7 @@ export function callback(fn, returnType, argTypes = [], native, abi = undefined)
176
176
  const args = [adaptCallbackFunction(fn, argTypes, returnType, native), _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native)];
177
177
  const scalarArgs = argTypes.map(scalarResult);
178
178
  const buffers = scalarArgs.some(Boolean) || args[2].some((type) => typeof type === "object" && type !== null);
179
- if (buffers) args.push(abi ?? "default", scalarArgs, undefined, allocTransient);
179
+ if (buffers) args.push(abi ?? "default", scalarArgs, undefined, allocSnapshot);
180
180
  else if (abi) args.push(abi);
181
181
  const cb = new native.Callback(...args);
182
182
 
@@ -324,7 +324,7 @@ export function threadSafeCallback(fn, returnType, argTypes = [], native, option
324
324
  const args = [dispatch, _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native)];
325
325
  const scalarArgs = argTypes.map(scalarResult);
326
326
  const buffers = scalarArgs.some(Boolean) || args[2].some((type) => typeof type === "object" && type !== null);
327
- if (buffers) args.push(abi ?? "default", scalarArgs, context, allocTransient);
327
+ if (buffers) args.push(abi ?? "default", scalarArgs, context, allocSnapshot);
328
328
  else if (context !== undefined) args.push(abi ?? "default", scalarArgs, context);
329
329
  else if (scalarArgs.some(Boolean)) args.push(abi ?? "default", scalarArgs);
330
330
  else if (abi) args.push(abi);
@@ -0,0 +1,63 @@
1
+ /**
2
+ * @file executor.js
3
+ * @module core/executor
4
+ * @description `fn.callOn(executor, ...args)`: the same call as
5
+ * `fn.callAsync(...args)` (conversions, out parameters, errcheck, argument
6
+ * lifetime), run on an {@link Executor} thread instead of a libuv worker.
7
+ */
8
+
9
+ let native = null;
10
+
11
+ /**
12
+ * Set the native module (once, from lib/index.js, before any call).
13
+ *
14
+ * @param {Object} nativeModule - Native module
15
+ */
16
+ export function initExecutor(nativeModule) {
17
+ native = nativeModule;
18
+ }
19
+
20
+ /**
21
+ * Run `fn.callAsync(...args)` on `target`: an `Executor`, or
22
+ * `{ executor, signal }` to cancel the call while it is still queued.
23
+ *
24
+ * The native binding takes the executor for exactly one call: the next
25
+ * asynchronous call of `fn`'s native function, made synchronously below.
26
+ *
27
+ * @param {Function} fn - A function with `callAsync` and `_ffi`
28
+ * @param {Object} target - Executor or `{ executor, signal }`
29
+ * @param {Array} args - Call arguments
30
+ * @returns {Promise<*>}
31
+ */
32
+ export function callOn(fn, target, args) {
33
+ let executor = target;
34
+ let signal;
35
+ if (!(target instanceof native.Executor)) {
36
+ executor = target?.executor;
37
+ signal = target?.signal ?? undefined;
38
+ if (!(executor instanceof native.Executor)) {
39
+ return Promise.reject(new TypeError("callOn requires an Executor or { executor, signal }"));
40
+ }
41
+ if (signal !== undefined && !(signal instanceof AbortSignal)) {
42
+ return Promise.reject(new TypeError("callOn: signal must be an AbortSignal"));
43
+ }
44
+ }
45
+ if (signal?.aborted) return Promise.reject(signal.reason);
46
+
47
+ const previous = executor._lastJob;
48
+ let promise;
49
+ native.setCallTarget(executor, fn._ffi);
50
+ try {
51
+ promise = fn.callAsync(...args);
52
+ } finally {
53
+ native.setCallTarget(null);
54
+ }
55
+ const job = executor._lastJob;
56
+ if (signal === undefined || job === previous) return promise;
57
+
58
+ // Cancel while queued: the promise rejects with the abort reason; a call
59
+ // that has started completes normally.
60
+ const abort = () => executor._cancel(job, signal.reason);
61
+ signal.addEventListener("abort", abort, { once: true });
62
+ return promise.finally(() => signal.removeEventListener("abort", abort));
63
+ }
@@ -41,6 +41,7 @@ import { argumentConverters, argumentsNeedOwners, callWithArgumentOwners, callWi
41
41
  import { callback as createCallback } from "./callback.js";
42
42
  import { isScalarSubclass, keepFunctionOwner, scalarOutparam } from "../structures/helpers/common.js";
43
43
  import { cacheWeakValue, createTypeKey } from "../utils/cache.js";
44
+ import { callOn } from "./executor.js";
44
45
 
45
46
  const prototypeOwners = new WeakMap();
46
47
 
@@ -171,6 +172,7 @@ function applyParamflags(rawFn, restype, argtypes, paramflags) {
171
172
  _as_parameter_: { value: rawFn.address },
172
173
  _ffi: { value: rawFn._ffi },
173
174
  callAsync: { value: (...args) => invokeWithFlags("callAsync", args) },
175
+ callOn: { value: (target, ...args) => callOn(paramflagsWrapper, target, args) },
174
176
  errcheck: {
175
177
  get: () => errcheck,
176
178
  set: (callback) => {
@@ -403,6 +405,12 @@ function createFuncPtrType(native, typeName, abi) {
403
405
  enumerable: false,
404
406
  configurable: false,
405
407
  },
408
+ callOn: {
409
+ value: (target, ...args) => callOn(callMethod, target, args),
410
+ writable: false,
411
+ enumerable: false,
412
+ configurable: false,
413
+ },
406
414
  errcheck: {
407
415
  get() {
408
416
  return callState.errcheck;
package/lib/index.d.ts CHANGED
@@ -223,6 +223,9 @@ export interface FFIFunction {
223
223
  /** Call the native function asynchronously on a worker thread. */
224
224
  callAsync(...args: any[]): Promise<any>;
225
225
 
226
+ /** Like {@link callAsync}, on the thread of an {@link Executor}. */
227
+ callOn(target: ExecutorTarget, ...args: any[]): Promise<any>;
228
+
226
229
  /** The function name in the native library. */
227
230
  readonly funcName: string;
228
231
 
@@ -287,6 +290,8 @@ export type NativeErrcheckCallback<TArgs extends readonly FFIType[] = FFIType[],
287
290
  export interface TypedFFIFunction<TArgs extends readonly FFIType[], TRet extends FFIType | null> {
288
291
  (...args: FFIArgs<TArgs>): FFIReturn<TRet>;
289
292
  callAsync(...args: FFIArgs<TArgs>): Promise<FFIReturn<TRet>>;
293
+ /** Like {@link callAsync}, on the thread of an {@link Executor}. */
294
+ callOn(target: ExecutorTarget, ...args: FFIArgs<TArgs>): Promise<FFIReturn<TRet>>;
290
295
  readonly funcName: string;
291
296
  readonly address: bigint;
292
297
  readonly _as_parameter_: bigint;
@@ -471,6 +476,9 @@ export interface FunctionWrapper {
471
476
  /** Call the function asynchronously on a worker thread. */
472
477
  callAsync(...args: any[]): Promise<any>;
473
478
 
479
+ /** Like {@link callAsync}, on the thread of an {@link Executor}. */
480
+ callOn(target: ExecutorTarget, ...args: any[]): Promise<any>;
481
+
474
482
  /** Argument types. Set before calling. */
475
483
  argtypes: FFIType[];
476
484
 
@@ -730,6 +738,73 @@ export class ThreadSafeCallback extends Callback {
730
738
  drain(): number;
731
739
  }
732
740
 
741
+ // =============================================================================
742
+ // Executor
743
+ // =============================================================================
744
+
745
+ /**
746
+ * Options of {@link Executor}.
747
+ * @category Async Calls
748
+ */
749
+ export interface ExecutorOptions {
750
+ /** Thread name shown by debuggers and profilers (default `"node-ctypes"`). */
751
+ name?: string;
752
+ }
753
+
754
+ /**
755
+ * Where {@link FFIFunction.callOn} runs a call: an {@link Executor}, or an
756
+ * executor with an `AbortSignal` that cancels the call while it is queued
757
+ * (the promise rejects with `signal.reason`; a started call completes).
758
+ * @category Async Calls
759
+ */
760
+ export type ExecutorTarget = Executor | { readonly executor: Executor; readonly signal?: AbortSignal };
761
+
762
+ /**
763
+ * A native thread owned by node-ctypes, with a FIFO queue of calls.
764
+ *
765
+ * `fn.callOn(executor, ...args)` is `fn.callAsync(...args)` (same conversions,
766
+ * out parameters, errcheck and argument lifetime) run on this thread instead
767
+ * of a libuv worker: calls run one at a time, in arrival order, so a slow call
768
+ * never occupies the libuv pool (fs, dns, crypto) and calls that must share a
769
+ * thread (thread-local state, thread-affine handles) can.
770
+ *
771
+ * The thread starts with the first call. While calls are pending the process
772
+ * stays alive; an idle executor does not keep it alive and is collected with
773
+ * its thread when unreferenced. When the process exits (or a worker thread
774
+ * terminates) queued calls are discarded and a running call is left to finish
775
+ * on its own.
776
+ *
777
+ * No Python equivalent.
778
+ *
779
+ * @example
780
+ * ```javascript
781
+ * const executor = new Executor({ name: "device" });
782
+ * const result = await lib.slow_read.callOn(executor, handle, buffer, size);
783
+ * const controller = new AbortController();
784
+ * const next = lib.slow_read.callOn({ executor, signal: controller.signal }, handle, buffer, size);
785
+ * controller.abort(); // rejects `next` if it has not started
786
+ * await executor.close();
787
+ * ```
788
+ *
789
+ * @category Async Calls
790
+ */
791
+ export class Executor {
792
+ constructor(options?: ExecutorOptions);
793
+ /**
794
+ * Reject new calls, wait for the accepted ones, then stop the thread.
795
+ * Always returns the same promise; a closed executor cannot be reopened.
796
+ */
797
+ close(): Promise<void>;
798
+ /** Calls queued or running. */
799
+ readonly pending: number;
800
+ /** Calls settled since the executor was created. */
801
+ readonly completed: number;
802
+ /** Whether the thread is running (started by the first call, stopped by `close()`). */
803
+ readonly running: boolean;
804
+ /** Whether `close()` has been called. */
805
+ readonly closed: boolean;
806
+ }
807
+
733
808
  // =============================================================================
734
809
  // Structures
735
810
  // =============================================================================
package/lib/index.js CHANGED
@@ -27,6 +27,7 @@ import { createLazyLoader } from "./core/lazy-loader.js";
27
27
  import { callback as createCallback, threadSafeCallback as createThreadSafeCallback } from "./core/callback.js";
28
28
  import { createCFUNCTYPE, createWINFUNCTYPE } from "./core/funcptr.js";
29
29
  import { createLibraryClasses } from "./core/Library.js";
30
+ import { initExecutor } from "./core/executor.js";
30
31
  import {
31
32
  alloc as _alloc,
32
33
  cstring as _cstring,
@@ -111,7 +112,10 @@ const native = externalBuffers ? rawNative : wrapNative(rawNative);
111
112
  _initConstants(native);
112
113
 
113
114
  // Re-esporta le classi native
114
- const { Version, Library, FFIFunction, Callback, ThreadSafeCallback, StructType, ArrayType, CType } = native;
115
+ const { Version, Library, FFIFunction, Callback, ThreadSafeCallback, StructType, ArrayType, CType, Executor } = native;
116
+
117
+ // fn.callOn(executor, ...args) imposta l'Executor della chiamata nel nativo.
118
+ initExecutor(native);
115
119
 
116
120
  // Gli errori di conversione degli argomenti nel nativo sono ctypes.ArgumentError.
117
121
  native.setArgumentError(ArgumentError);
@@ -593,6 +597,7 @@ export {
593
597
  FFIFunction,
594
598
  Callback,
595
599
  ThreadSafeCallback,
600
+ Executor,
596
601
  CType,
597
602
 
598
603
  // Funzioni base
@@ -74,14 +74,19 @@ const kTransientPoolSize = 8192;
74
74
  const FixedArrayBuffer = ArrayBuffer;
75
75
  const bufferFrom = Buffer.from;
76
76
  const zeroBuffer = Buffer.alloc;
77
+
77
78
  let transientPool = new FixedArrayBuffer(kTransientPoolSize);
78
79
  let transientOffset = 0;
80
+ let snapshotPool = new FixedArrayBuffer(kTransientPoolSize);
81
+ let snapshotOffset = 0;
79
82
 
80
83
  /**
81
- * Zero-filled buffer for a native-call temporary or an owned callback snapshot. A small
84
+ * Zero-filled buffer for a value that only lives for one native call. A small
82
85
  * Buffer.alloc lives on the V8 heap and must be externalized when native code
83
86
  * reads it; slices of an off-heap pool avoid that. Slices are never reused, so
84
- * a fresh pool is already zeroed. Retained slices keep their backing store alive.
87
+ * a fresh pool is already zeroed. The pool is never handed to user code:
88
+ * native code may still use these slices while JavaScript runs (callbacks,
89
+ * async calls).
85
90
  *
86
91
  * @param {number} size - Size in bytes to allocate
87
92
  * @returns {Buffer} Zero-initialized buffer
@@ -97,6 +102,36 @@ export function allocTransient(size) {
97
102
  return buf;
98
103
  }
99
104
 
105
+ /**
106
+ * Zero-filled buffer for an owned callback argument snapshot, sliced as
107
+ * {@link allocTransient} from a separate pool: a snapshot's `.buffer` exposes
108
+ * only other snapshots, and detaching it cannot affect native-call temporaries.
109
+ * Retained slices keep their pool alive; a pool detached by user code
110
+ * (`transfer()`, a transfer list) is replaced.
111
+ *
112
+ * @param {number} size - Size in bytes to allocate
113
+ * @returns {Buffer} Zero-initialized buffer
114
+ */
115
+ export function allocSnapshot(size) {
116
+ if (size > kTransientPoolSize >>> 2) return zeroBuffer(size);
117
+ if (snapshotOffset + size > kTransientPoolSize) {
118
+ snapshotPool = new FixedArrayBuffer(kTransientPoolSize);
119
+ snapshotOffset = 0;
120
+ }
121
+ let buf;
122
+ try {
123
+ buf = bufferFrom(snapshotPool, snapshotOffset, size);
124
+ } catch (error) {
125
+ // Un pool staccato ha byteLength 0: il controllo resta fuori dal percorso caldo.
126
+ if (!snapshotPool.detached) throw error;
127
+ snapshotPool = new FixedArrayBuffer(kTransientPoolSize);
128
+ snapshotOffset = 0;
129
+ buf = bufferFrom(snapshotPool, 0, size);
130
+ }
131
+ snapshotOffset += (size + 7) & ~7;
132
+ return buf;
133
+ }
134
+
100
135
  /**
101
136
  * Creates a buffer containing a null-terminated C string.
102
137
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-ctypes",
3
- "version": "2.9.0",
3
+ "version": "2.11.0",
4
4
  "description": "Python ctypes-like FFI for Node.js using libffi",
5
5
  "author": "Damiano Mazzella",
6
6
  "license": "MIT",
@@ -11,7 +11,7 @@
11
11
  "bugs": {
12
12
  "url": "https://github.com/dmazzella/node-ctypes/issues"
13
13
  },
14
- "homepage": "https://github.com/dmazzella/node-ctypes#readme",
14
+ "homepage": "https://dmazzella.github.io/node-ctypes/",
15
15
  "keywords": [
16
16
  "ffi",
17
17
  "ctypes",