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 +21 -7
- 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/core/callback.js +14 -0
- package/lib/index.d.ts +24 -2
- package/package.json +1 -1
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
|
-
|
|
503
|
-
|
|
504
|
-
- [
|
|
505
|
-
- [
|
|
506
|
-
- [
|
|
507
|
-
- [
|
|
508
|
-
- [
|
|
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
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/lib/core/callback.js
CHANGED
|
@@ -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[]):
|
|
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.
|