node-ctypes 2.0.0 → 2.1.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/README.md CHANGED
@@ -192,6 +192,17 @@ with the `using` declaration for scope-bound cleanup (also on `throw`):
192
192
  Set `NODE_CTYPES_DEBUG_CALLBACKS=1` to log a stack trace for every
193
193
  callback garbage-collected without `.release()`.
194
194
 
195
+ Callbacks invoked by native threads need `threadSafeCallback()`: the
196
+ JavaScript function runs on the main thread, and the calling thread waits
197
+ for its result. Like a timer, a thread-safe callback keeps the event loop
198
+ alive until released; `.unref()` lets the process exit when nothing else
199
+ is pending (calls are still delivered while it runs), `.ref()` restores it:
200
+
201
+ ```javascript
202
+ const onEvent = threadSafeCallback((code) => console.log("event", code), null, [c_int]).unref();
203
+ startWorker(onEvent); // a native library calling onEvent from its own thread
204
+ ```
205
+
195
206
  ### Errors: `errno` and `GetLastError`
196
207
 
197
208
  `GetLastError()` / `get_errno()` read a **private thread-local slot** —
@@ -499,13 +510,16 @@ needs these changes:
499
510
 
500
511
  ## Examples
501
512
 
502
- - [Windows Controls Demo](examples/windows/demo_controls.js) — Win32 common controls
503
- - [Windows Registry Demo](examples/windows/demo_registry.js) — `setValue` / `getValue` / `openKey` / `deleteKey`
504
- - [Windows Tray Demo](examples/windows/demo_tray.js) — system tray icon + popup menu
505
- - [Windows COM (Shortcut)](examples/windows/demo_comtypes_file.js) — `IShellLinkW` + `IPersistFile`
506
- - [Windows COM (Active Directory)](examples/windows/demo_comtypes_ads.js) — `IDirectorySearch` / `ADsOpenObject`
507
- - [Windows LDAP Demo](examples/windows/demo_ldap.js) — LDAPv3 paged search (`wldap32`)
508
- - [Smart Card (PC/SC) Demo](examples/demo_scard.js) — `WinSCard` on Windows, `pcsclite` on macOS/Linux
513
+ Each example in `examples/` has its own README; see the [index](examples/README.md).
514
+
515
+ - [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)
516
+ - [Smart card (PC/SC)](examples/cross-platform/smartcard/README.md) — `winscard` on Windows, `PCSC.framework` on macOS, `libpcsclite` on Linux
517
+ - [Accessibility](examples/macos/accessibility/README.md) — macOS UI automation with the Accessibility API
518
+ - [COM automation](examples/windows/com/README.md) — shell shortcuts (`IShellLinkW`) and Active Directory (`IDirectorySearch`)
519
+ - [Controls](examples/windows/controls/README.md) — Win32 common controls
520
+ - [LDAP](examples/windows/ldap/README.md) — LDAPv3 paged search (`wldap32`)
521
+ - [Registry](examples/windows/registry/README.md) — `setValue` / `getValue` / `openKey` / `deleteKey`
522
+ - [System tray](examples/windows/tray/README.md) — tray icon + popup menu
509
523
 
510
524
  ---
511
525
 
Binary file
Binary file
@@ -209,6 +209,11 @@ export function callback(fn, returnType, argTypes = [], native, abi = undefined)
209
209
  * - Failing to release will leak native memory
210
210
  * - Keep a reference while in use to prevent GC
211
211
  *
212
+ * **Event loop**: like a timer, a thread-safe callback keeps the Node.js
213
+ * event loop alive until it is released. `.unref()` lets the process exit
214
+ * when nothing else is pending (calls from other threads are still delivered
215
+ * while it runs); `.ref()` restores the default. Both return the wrapper.
216
+ *
212
217
  * @param {Function} fn - JavaScript function to wrap
213
218
  * The function will be executed on Node.js's main thread regardless of
214
219
  * which thread invokes the callback
@@ -218,6 +223,7 @@ export function callback(fn, returnType, argTypes = [], native, abi = undefined)
218
223
  * @returns {Object} Callback wrapper with properties:
219
224
  * - `pointer` (BigInt): Function pointer to pass to C
220
225
  * - `release()`: Release native resources (MUST be called)
226
+ * - `ref()` / `unref()`: Keep / do not keep the event loop alive
221
227
  * - `_callback`: Internal callback object
222
228
  *
223
229
  * @example Windows thread callback
@@ -287,6 +293,14 @@ export function threadSafeCallback(fn, returnType, argTypes = [], native, abi =
287
293
  release() {
288
294
  cb.release();
289
295
  },
296
+ ref() {
297
+ cb.ref();
298
+ return wrapper;
299
+ },
300
+ unref() {
301
+ cb.unref();
302
+ return wrapper;
303
+ },
290
304
  [Symbol.dispose]() {
291
305
  cb.release();
292
306
  },
package/lib/index.d.ts CHANGED
@@ -588,6 +588,21 @@ export interface CallbackWrapper {
588
588
  [Symbol.dispose](): void;
589
589
  }
590
590
 
591
+ /**
592
+ * Wrapper returned by {@link threadSafeCallback}.
593
+ * @category Callbacks
594
+ */
595
+ export interface ThreadSafeCallbackWrapper extends CallbackWrapper {
596
+ /** Keep the Node.js event loop alive until released (the default). */
597
+ ref(): this;
598
+
599
+ /**
600
+ * Do not keep the Node.js event loop alive: the process can exit while the
601
+ * callback exists. Calls from other threads are delivered while it runs.
602
+ */
603
+ unref(): this;
604
+ }
605
+
591
606
  /**
592
607
  * Native callback class for main-thread callbacks.
593
608
  * @category Callbacks
@@ -618,7 +633,12 @@ export class Callback {
618
633
  *
619
634
  * @category Callbacks
620
635
  */
621
- export class ThreadSafeCallback extends Callback {}
636
+ export class ThreadSafeCallback extends Callback {
637
+ /** Keep the Node.js event loop alive until released (the default). */
638
+ ref(): this;
639
+ /** Do not keep the Node.js event loop alive. */
640
+ unref(): this;
641
+ }
622
642
 
623
643
  // =============================================================================
624
644
  // Structures
@@ -1395,6 +1415,8 @@ export function callback(fn: Function, returnType: AnyType | null, argTypes?: An
1395
1415
  * Create a thread-safe callback that can be invoked from any thread.
1396
1416
  *
1397
1417
  * **Important:** Call `.release()` when the callback is no longer needed.
1418
+ * Like a timer, it keeps the Node.js event loop alive until released, unless
1419
+ * `.unref()` is called.
1398
1420
  *
1399
1421
  * @param fn - JavaScript function to wrap
1400
1422
  * @param returnType - Return type of the callback
@@ -1402,7 +1424,7 @@ export function callback(fn: Function, returnType: AnyType | null, argTypes?: An
1402
1424
  *
1403
1425
  * @category Callbacks
1404
1426
  */
1405
- export function threadSafeCallback(fn: Function, returnType: AnyType | null, argTypes?: AnyType[]): CallbackWrapper;
1427
+ export function threadSafeCallback(fn: Function, returnType: AnyType | null, argTypes?: AnyType[]): ThreadSafeCallbackWrapper;
1406
1428
 
1407
1429
  /**
1408
1430
  * Create a function pointer type with cdecl calling convention.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-ctypes",
3
- "version": "2.0.0",
3
+ "version": "2.1.1",
4
4
  "description": "Python ctypes-like FFI for Node.js using libffi",
5
5
  "author": "Damiano Mazzella",
6
6
  "license": "MIT",