node-ctypes 2.2.0 → 2.4.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 +932 -0
- package/README.md +504 -99
- 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/Library.js +136 -109
- package/lib/core/callback.js +17 -20
- package/lib/core/conversions.js +376 -16
- package/lib/core/funcptr.js +148 -73
- package/lib/core/lazy-loader.js +10 -4
- package/lib/core/types.js +201 -98
- package/lib/index.d.ts +276 -83
- package/lib/index.js +44 -32
- package/lib/memory/buffer.js +82 -22
- package/lib/memory/operations.js +55 -45
- package/lib/memory/pointer.js +233 -57
- package/lib/platform/constants.js +0 -1
- package/lib/platform/errors.js +48 -4
- package/lib/platform/find_library.js +78 -19
- package/lib/platform/win_types.js +8 -3
- package/lib/structures/Structure.js +252 -203
- package/lib/structures/Union.js +10 -21
- package/lib/structures/helpers/array.js +102 -16
- package/lib/structures/helpers/bitfield.js +75 -150
- package/lib/structures/helpers/common.js +310 -21
- package/lib/structures/helpers/layout.js +145 -0
- package/lib/structures/helpers/struct.js +160 -419
- package/lib/structures/helpers/union.js +154 -155
- package/lib/structures/helpers/wrap.js +3 -15
- package/lib/types/SimpleCData.js +11 -32
- package/lib/types/primitives.js +160 -113
- package/lib/utils/cache.js +34 -2
- package/package.json +4 -1
package/lib/memory/pointer.js
CHANGED
|
@@ -26,8 +26,8 @@
|
|
|
26
26
|
* ```
|
|
27
27
|
*/
|
|
28
28
|
|
|
29
|
-
import { writePointerField } from "../structures/helpers/common.js";
|
|
30
|
-
import { flush, mirrorAddress, mirrorsActive } from "./mirror.js";
|
|
29
|
+
import { byrefOwners, isScalarSubclass, keepAlive, keepFunctionOwner, keptObject, kPointerMemory, memoryDomain, pointerOwner, scalarView, shareMemory, writePointerField } from "../structures/helpers/common.js";
|
|
30
|
+
import { flush, mirrorAddress, mirrorsActive, refresh } from "./mirror.js";
|
|
31
31
|
|
|
32
32
|
/**
|
|
33
33
|
* Gets the memory address of a buffer or pointer.
|
|
@@ -56,13 +56,18 @@ import { flush, mirrorAddress, mirrorsActive } from "./mirror.js";
|
|
|
56
56
|
* ```
|
|
57
57
|
*/
|
|
58
58
|
export function addressOf(ptr, alloc, native) {
|
|
59
|
+
// Puntatore: l'indirizzo del puntatore stesso (Python addressof(p)), non
|
|
60
|
+
// quello della memoria puntata.
|
|
61
|
+
if (ptr && typeof ptr === "object" && ptr._pointerType !== undefined) {
|
|
62
|
+
ptr = ptr._pointerSlot;
|
|
63
|
+
}
|
|
59
64
|
// Object wrapper (SimpleCData, Structure, Union, array proxy) → unwrap al Buffer.
|
|
60
65
|
// Le istanze di array sono Proxy su un Buffer: Buffer.isBuffer() è vero in JS
|
|
61
66
|
// ma il nativo non vede un Buffer, quindi si usa sempre `_buffer` se presente.
|
|
62
67
|
if (ptr && typeof ptr === "object" && Buffer.isBuffer(ptr._buffer)) {
|
|
63
68
|
ptr = ptr._buffer;
|
|
64
69
|
}
|
|
65
|
-
if (Buffer.isBuffer(ptr)) {
|
|
70
|
+
if (Buffer.isBuffer(ptr) || ArrayBuffer.isView(ptr) || ptr instanceof ArrayBuffer) {
|
|
66
71
|
// Native API returns the buffer's memory address in one V8 boundary
|
|
67
72
|
// crossing. The fallback path below (tempBuf + writeValue) is kept
|
|
68
73
|
// for backward compatibility with older .node binaries that do not
|
|
@@ -80,7 +85,8 @@ export function addressOf(ptr, alloc, native) {
|
|
|
80
85
|
/**
|
|
81
86
|
* Passes an object by reference (Python byref equivalent).
|
|
82
87
|
*
|
|
83
|
-
* Returns
|
|
88
|
+
* Returns an owner-retaining byte view, or an address carrier for offsets
|
|
89
|
+
* outside the known buffer range.
|
|
84
90
|
* This is useful for passing arguments to C functions that expect pointers.
|
|
85
91
|
*
|
|
86
92
|
* **Python ctypes Compatibility**:
|
|
@@ -91,7 +97,8 @@ export function addressOf(ptr, alloc, native) {
|
|
|
91
97
|
* - SimpleCData instance (has _buffer property)
|
|
92
98
|
* - Buffer object
|
|
93
99
|
* - Structure instance (has _buffer property)
|
|
94
|
-
* @
|
|
100
|
+
* @param {number} [offset=0] - Signed byte offset
|
|
101
|
+
* @returns {Buffer|Object} Buffer view or owner-retaining address carrier
|
|
95
102
|
* @throws {TypeError} If obj is not a ctypes instance or Buffer
|
|
96
103
|
*
|
|
97
104
|
* @example Pass SimpleCData by reference
|
|
@@ -121,16 +128,24 @@ export function addressOf(ptr, alloc, native) {
|
|
|
121
128
|
* move_point(byref(point), 5, 10);
|
|
122
129
|
* ```
|
|
123
130
|
*/
|
|
124
|
-
export function byref(obj) {
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
131
|
+
export function byref(obj, offset = 0, native) {
|
|
132
|
+
if (!Number.isSafeInteger(offset)) throw new TypeError("byref() offset must be a safe integer");
|
|
133
|
+
let buffer;
|
|
134
|
+
// Puntatore: la memoria del puntatore (T**), così una funzione C può
|
|
135
|
+
// scriverci un indirizzo e ri-puntarlo (Python byref(p)).
|
|
136
|
+
if (obj && typeof obj === "object" && obj._pointerType !== undefined) {
|
|
137
|
+
buffer = obj._pointerSlot;
|
|
128
138
|
}
|
|
139
|
+
// SimpleCData instance or Structure instance - return its buffer
|
|
140
|
+
else if (obj && obj._buffer && Buffer.isBuffer(obj._buffer)) buffer = obj._buffer;
|
|
129
141
|
// Buffer - return as-is
|
|
130
|
-
if (Buffer.isBuffer(obj))
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
142
|
+
else if (Buffer.isBuffer(obj)) buffer = obj;
|
|
143
|
+
if (buffer === undefined) throw new TypeError("byref() argument must be a ctypes instance or Buffer");
|
|
144
|
+
const type = obj._pointerType ?? obj._arrayType ?? (obj.constructor?._isSimpleCData || typeof obj.constructor?._buildStruct === "function" ? obj.constructor : obj._structDef);
|
|
145
|
+
const view = offset >= 0 && offset <= buffer.length ? buffer.subarray(offset) : { address: (mirrorAddress(buffer) ?? native.addressOf(buffer)) + BigInt(offset) };
|
|
146
|
+
if (!Buffer.isBuffer(view)) Object.defineProperty(view, "_as_parameter_", { value: view.address });
|
|
147
|
+
byrefOwners.set(view, { owner: obj, type, offset });
|
|
148
|
+
return view;
|
|
134
149
|
}
|
|
135
150
|
|
|
136
151
|
/**
|
|
@@ -177,32 +192,36 @@ export function byref(obj) {
|
|
|
177
192
|
*/
|
|
178
193
|
export function cast(ptr, targetType, readValue, sizeof, ptrToBuffer, native) {
|
|
179
194
|
// Validate inputs
|
|
180
|
-
if (!ptr) {
|
|
195
|
+
if (!ptr && !(targetType?._pointerTo !== undefined || targetType?._isPointerValued === true)) {
|
|
181
196
|
throw new TypeError("cast() requires a non-null pointer");
|
|
182
197
|
}
|
|
183
198
|
if (!targetType) {
|
|
184
199
|
throw new TypeError("cast() requires a target type");
|
|
185
200
|
}
|
|
201
|
+
if (ArrayBuffer.isView(ptr) && !Buffer.isBuffer(ptr)) ptr = Buffer.from(ptr.buffer, ptr.byteOffset, ptr.byteLength);
|
|
202
|
+
else if (ptr instanceof ArrayBuffer) ptr = Buffer.from(ptr);
|
|
186
203
|
|
|
187
204
|
// PointerTypeDef — return a PointerInstance via fromAddress() or fromBuffer()
|
|
188
205
|
// Python equivalent: cast(c_void_p(addr), POINTER(c_int32)) — read stored address
|
|
189
206
|
// Python equivalent: cast(arr, POINTER(c_int32)) — pointer to arr's memory
|
|
190
207
|
// Python equivalent: cast(p, POINTER(c_double)) — pointer to same memory as p
|
|
191
208
|
if (typeof targetType === "object" && targetType._pointerTo !== undefined) {
|
|
209
|
+
if (!ptr) return targetType.fromAddress(0n);
|
|
192
210
|
// PointerInstance — use its address/buffer (Python: cast(p, POINTER(OtherType)))
|
|
193
211
|
if (ptr && typeof ptr === "object" && typeof ptr.address === "bigint") {
|
|
194
212
|
if (ptr._buffer) {
|
|
195
213
|
return targetType.fromBuffer(ptr._buffer);
|
|
196
214
|
}
|
|
197
|
-
return targetType.fromAddress(ptr.address);
|
|
215
|
+
return targetType.fromAddress(ptr.address, ptr);
|
|
198
216
|
}
|
|
199
217
|
|
|
200
218
|
// ctypes object with _buffer — distinguish data objects from pointer-value objects
|
|
201
219
|
// Note: array proxies are Buffer.isBuffer()==true but also have ._buffer, so don't exclude Buffers
|
|
202
220
|
if (ptr && typeof ptr === "object" && ptr._buffer && Buffer.isBuffer(ptr._buffer)) {
|
|
203
|
-
// SimpleCData storing a pointer/address value (c_void_p, c_char_p,
|
|
204
|
-
// → read the stored address value from the buffer
|
|
205
|
-
|
|
221
|
+
// SimpleCData storing a pointer/address value (c_void_p, c_char_p,
|
|
222
|
+
// c_wchar_p) → read the stored address value from the buffer
|
|
223
|
+
const pointerValued = new Set([native.CType.POINTER, native.CType.STRING, native.CType.WSTRING]);
|
|
224
|
+
if (ptr.constructor && ptr.constructor._isSimpleCData && pointerValued.has(ptr.constructor._type)) {
|
|
206
225
|
// This is a pointer-valued SimpleCData — read address from buffer
|
|
207
226
|
const buf = ptr._buffer;
|
|
208
227
|
let addr;
|
|
@@ -213,7 +232,8 @@ export function cast(ptr, targetType, readValue, sizeof, ptrToBuffer, native) {
|
|
|
213
232
|
} else {
|
|
214
233
|
throw new TypeError("cast(): buffer too small to contain a pointer");
|
|
215
234
|
}
|
|
216
|
-
|
|
235
|
+
// Python: il risultato tiene viva la sorgente (la stringa di un c_char_p).
|
|
236
|
+
return targetType.fromAddress(addr, ptr);
|
|
217
237
|
}
|
|
218
238
|
// Array, Structure, Union — pointer to their data buffer
|
|
219
239
|
// Python: cast(arr, POINTER(c_int32)) points to arr's memory
|
|
@@ -242,6 +262,15 @@ export function cast(ptr, targetType, readValue, sizeof, ptrToBuffer, native) {
|
|
|
242
262
|
return targetType.fromAddress(addr);
|
|
243
263
|
}
|
|
244
264
|
|
|
265
|
+
// c_void_p / c_char_p / c_wchar_p: an instance pointing to the source,
|
|
266
|
+
// which it keeps alive (Python: cast(buf, c_void_p).value == addressof(buf)).
|
|
267
|
+
if (typeof targetType === "function" && targetType._isSimpleCData === true && isPointerValued(targetType, native)) {
|
|
268
|
+
const result = new targetType();
|
|
269
|
+
writePointerField(result._buffer, 0, ptr == null || ptr === 0 || ptr === 0n ? 0n : castSourceAddress(ptr, native), native.POINTER_SIZE);
|
|
270
|
+
if (typeof ptr === "object") keepAlive(result._buffer, 0, ptr);
|
|
271
|
+
return result;
|
|
272
|
+
}
|
|
273
|
+
|
|
245
274
|
// Struct type - return wrapper object
|
|
246
275
|
if (typeof targetType === "object" && targetType.size !== undefined) {
|
|
247
276
|
const buf = Buffer.isBuffer(ptr) ? ptr : ptrToBuffer(ptr, targetType.size);
|
|
@@ -270,6 +299,28 @@ export function cast(ptr, targetType, readValue, sizeof, ptrToBuffer, native) {
|
|
|
270
299
|
return readValue(tempBuf, targetType, 0);
|
|
271
300
|
}
|
|
272
301
|
|
|
302
|
+
function isPointerValued(type, native) {
|
|
303
|
+
return type._type === native.CType.POINTER || type._type === native.CType.STRING || type._type === native.CType.WSTRING;
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
// Address given by a cast() source, as Python's c_void_p.from_param: the value
|
|
307
|
+
// of pointers, c_void_p, c_char_p and c_wchar_p, the memory of the others.
|
|
308
|
+
function castSourceAddress(ptr, native) {
|
|
309
|
+
if (typeof ptr === "bigint") return ptr;
|
|
310
|
+
if (typeof ptr === "number") return BigInt(ptr);
|
|
311
|
+
if (ptr !== null && typeof ptr === "object") {
|
|
312
|
+
if (ptr._pointerType !== undefined) return ptr.address;
|
|
313
|
+
const T = ptr.constructor;
|
|
314
|
+
if (T?._isSimpleCData === true && isPointerValued(T, native)) {
|
|
315
|
+
return native.POINTER_SIZE === 8 ? ptr._buffer.readBigUInt64LE(0) : BigInt(ptr._buffer.readUInt32LE(0));
|
|
316
|
+
}
|
|
317
|
+
if (Buffer.isBuffer(ptr._buffer)) return addressOf(ptr._buffer, null, native);
|
|
318
|
+
if (Buffer.isBuffer(ptr)) return addressOf(ptr, null, native);
|
|
319
|
+
if (ptr._as_parameter_ !== undefined) return castSourceAddress(ptr._as_parameter_, native);
|
|
320
|
+
}
|
|
321
|
+
throw new TypeError("cast(): ptr must be a BigInt, number, Buffer, ctypes instance, or PointerInstance");
|
|
322
|
+
}
|
|
323
|
+
|
|
273
324
|
/**
|
|
274
325
|
* Buffer over the memory at an address, used by `from_address`, `cast` and
|
|
275
326
|
* pointers (not exported: the public, Python-compatible way is
|
|
@@ -372,6 +423,7 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
372
423
|
// calcolabile subito. Se è thunk, entrambi vengono rimpiazzati al primo
|
|
373
424
|
// uso, senza mutare le chiusure dei trap.
|
|
374
425
|
let baseSize;
|
|
426
|
+
let scalarSubclass = isScalarSubclass(baseType);
|
|
375
427
|
let _lazyResolved = false;
|
|
376
428
|
function resolveIfLazy() {
|
|
377
429
|
if (!isLazyThunk || _lazyResolved) return;
|
|
@@ -384,6 +436,7 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
384
436
|
// `baseSize` serve solo per pointer arithmetic che avviene dopo la
|
|
385
437
|
// costruzione della struct, quando `resolved` è completamente definito.
|
|
386
438
|
baseType = resolved;
|
|
439
|
+
scalarSubclass = isScalarSubclass(baseType);
|
|
387
440
|
_lazyResolved = true;
|
|
388
441
|
baseSize = typeof resolved === "object" ? resolved.size : sizeof(resolved);
|
|
389
442
|
}
|
|
@@ -407,37 +460,53 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
407
460
|
|
|
408
461
|
// Python: per tipi semplici e Structure/Union `contents` (e p[i] per le struct)
|
|
409
462
|
// è un'istanza viva sulla memoria puntata, non una copia del valore.
|
|
410
|
-
|
|
411
|
-
const
|
|
463
|
+
// Array (Python POINTER(c_int * 3)): contents e p[i] sono istanze dell'array.
|
|
464
|
+
const isArrayBase = () => baseType !== null && (typeof baseType === "function" || typeof baseType === "object") && baseType._isArrayType === true;
|
|
465
|
+
const hasInstances = () => isArrayBase() || (typeof baseType === "function" && (baseType._isSimpleCData === true || typeof baseType._buildStruct === "function" || typeof baseType._buildUnion === "function"));
|
|
466
|
+
const isStructBase = () => scalarSubclass || isArrayBase() || (typeof baseType === "function" && (typeof baseType._buildStruct === "function" || typeof baseType._buildUnion === "function"));
|
|
412
467
|
|
|
413
468
|
// POINTER(POINTER(T)) / POINTER(CFUNCTYPE): elementi puntatore, letti come
|
|
414
469
|
// oggetto puntatore / funzione (NULL → null) e scritti come indirizzo.
|
|
415
470
|
const isPointerBase = () => (typeof baseType === "object" && baseType !== null && baseType._pointerTo !== undefined) || (typeof baseType === "function" && baseType._isFuncPtr === true);
|
|
416
471
|
|
|
417
|
-
function readPointerAt(buffer, address, offset) {
|
|
472
|
+
function readPointerAt(buffer, address, offset, owner) {
|
|
418
473
|
const inBuffer = buffer && offset + baseSize <= buffer.length;
|
|
419
474
|
const src = inBuffer ? buffer : native.ptrToBuffer(address + BigInt(offset), baseSize);
|
|
420
475
|
const off = inBuffer ? offset : 0;
|
|
476
|
+
if (!inBuffer) shareMemory(src, owner, address + BigInt(offset) - owner.origin);
|
|
477
|
+
if (mirrorsActive) refresh(src, off, baseSize);
|
|
421
478
|
const target = baseSize === 8 ? src.readBigUInt64LE(off) : BigInt(src.readUInt32LE(off));
|
|
479
|
+
const keep = pointerOwner(src, off, target);
|
|
422
480
|
if (target === 0n) return null;
|
|
423
|
-
|
|
481
|
+
if (typeof baseType !== "function") return baseType.fromAddress(target, keep);
|
|
482
|
+
return keepFunctionOwner(baseType(target), keep);
|
|
424
483
|
}
|
|
425
484
|
|
|
426
|
-
function writePointerAt(buffer, address, offset, value) {
|
|
485
|
+
function writePointerAt(buffer, address, offset, value, owner) {
|
|
427
486
|
if (buffer && offset + baseSize <= buffer.length) {
|
|
428
487
|
writePointerField(buffer, offset, value, baseSize);
|
|
488
|
+
if (mirrorsActive) flush(buffer, offset, baseSize);
|
|
429
489
|
return;
|
|
430
490
|
}
|
|
431
491
|
const target = native.ptrToBuffer(address + BigInt(offset), baseSize);
|
|
492
|
+
shareMemory(target, owner, address + BigInt(offset) - owner.origin);
|
|
432
493
|
writePointerField(target, 0, value, baseSize);
|
|
433
494
|
if (mirrorsActive) flush(target);
|
|
434
495
|
}
|
|
435
496
|
|
|
436
|
-
function instanceAt(buffer, address, offset) {
|
|
497
|
+
function instanceAt(buffer, address, offset, owner) {
|
|
498
|
+
if (scalarSubclass) {
|
|
499
|
+
if (buffer && offset + baseSize <= buffer.length) return scalarView(baseType, buffer.subarray(offset, offset + baseSize));
|
|
500
|
+
const view = native.ptrToBuffer(address + BigInt(offset), baseSize);
|
|
501
|
+
shareMemory(view, owner, address + BigInt(offset) - owner.origin);
|
|
502
|
+
return scalarView(baseType, view);
|
|
503
|
+
}
|
|
437
504
|
if (buffer && offset + baseSize <= buffer.length) {
|
|
438
505
|
return baseType.from_buffer(buffer, offset);
|
|
439
506
|
}
|
|
440
|
-
|
|
507
|
+
const result = baseType.from_address(address + BigInt(offset));
|
|
508
|
+
shareMemory(result._buffer, owner, address + BigInt(offset) - owner.origin);
|
|
509
|
+
return result;
|
|
441
510
|
}
|
|
442
511
|
|
|
443
512
|
// Scrittura a un indirizzo senza Buffer associato: per le primitive il
|
|
@@ -445,24 +514,26 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
445
514
|
// lo copia all'indirizzo, invece di creare un Buffer esterno (~400 ns,
|
|
446
515
|
// vietato in Electron).
|
|
447
516
|
let scratch = null;
|
|
448
|
-
function writeAtAddress(addr, value) {
|
|
449
|
-
if (typeof baseType === "function" && baseType._isSimpleCData) {
|
|
517
|
+
function writeAtAddress(addr, value, owner) {
|
|
518
|
+
if (typeof baseType === "function" && baseType._isSimpleCData && !baseType._isPointerValued) {
|
|
450
519
|
scratch ??= alloc(baseSize);
|
|
451
520
|
baseType._writer(scratch, 0, value);
|
|
452
521
|
native.writeMemory(scratch, 0, baseSize, addr);
|
|
453
522
|
return;
|
|
454
523
|
}
|
|
455
524
|
const buf = native.ptrToBuffer(addr, baseSize);
|
|
525
|
+
shareMemory(buf, owner, addr - owner.origin);
|
|
456
526
|
writeValue(buf, baseType, value, 0);
|
|
457
527
|
}
|
|
458
528
|
|
|
459
529
|
// Lettura a un indirizzo senza Buffer associato: per le primitive
|
|
460
530
|
// readValue(indirizzo) evita il Buffer esterno di ptrToBuffer.
|
|
461
|
-
function readAtAddress(addr) {
|
|
531
|
+
function readAtAddress(addr, owner) {
|
|
462
532
|
if (typeof baseType === "function" && baseType._isSimpleCData) {
|
|
463
533
|
return readValue(addr, baseType, 0);
|
|
464
534
|
}
|
|
465
535
|
const buf = native.ptrToBuffer(addr, baseSize);
|
|
536
|
+
shareMemory(buf, owner, addr - owner.origin);
|
|
466
537
|
return readValue(buf, baseType, 0);
|
|
467
538
|
}
|
|
468
539
|
|
|
@@ -470,13 +541,43 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
470
541
|
* Creates a pointer instance with Python ctypes-compatible API.
|
|
471
542
|
* Supports .contents property and [index] access for pointer arithmetic.
|
|
472
543
|
*/
|
|
473
|
-
function createPointerInstance(addressOrBuffer) {
|
|
544
|
+
function createPointerInstance(addressOrBuffer, keep, memory) {
|
|
474
545
|
// Risolvi il thunk lazy alla prima creazione di istanza: a questo
|
|
475
546
|
// punto la classe target è sicuramente inizializzata.
|
|
476
547
|
resolveIfLazy();
|
|
477
548
|
|
|
478
549
|
let _address = 0n;
|
|
479
550
|
let _buffer = null;
|
|
551
|
+
// Python `_objects`: ciò che deve restare vivo finché il puntatore punta
|
|
552
|
+
// lì (la sorgente di cast(), il puntatore da cui deriva add()).
|
|
553
|
+
let _objects = keep;
|
|
554
|
+
let _memory = memory;
|
|
555
|
+
if (keep?._pointerType !== undefined) _objects = keep._buffer ?? keep._objects;
|
|
556
|
+
if (_memory === undefined && _objects?.[kPointerMemory]) _memory = _objects;
|
|
557
|
+
// Memoria del puntatore (Python: un puntatore è un oggetto ctypes di
|
|
558
|
+
// POINTER_SIZE byte), creata alla prima richiesta di byref(p) /
|
|
559
|
+
// addressof(p). Da allora è lei a dare l'indirizzo: una funzione C che ci
|
|
560
|
+
// scrive (f(byref(p))) ri-punta p.
|
|
561
|
+
let _slot = null;
|
|
562
|
+
|
|
563
|
+
function sync() {
|
|
564
|
+
if (_slot === null) return;
|
|
565
|
+
const addr = native.POINTER_SIZE === 8 ? _slot.readBigUInt64LE(0) : BigInt(_slot.readUInt32LE(0));
|
|
566
|
+
if (addr !== _address) {
|
|
567
|
+
_address = addr;
|
|
568
|
+
_buffer = null;
|
|
569
|
+
_objects = undefined;
|
|
570
|
+
_memory = undefined;
|
|
571
|
+
keepAlive(_slot, 0, null);
|
|
572
|
+
}
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
function store() {
|
|
576
|
+
if (_slot === null) return;
|
|
577
|
+
if (native.POINTER_SIZE === 8) _slot.writeBigUInt64LE(BigInt.asUintN(64, _address), 0);
|
|
578
|
+
else _slot.writeUInt32LE(Number(BigInt.asUintN(32, _address)), 0);
|
|
579
|
+
keepAlive(_slot, 0, _memory ?? _buffer ?? _objects);
|
|
580
|
+
}
|
|
480
581
|
|
|
481
582
|
if (addressOrBuffer === undefined || addressOrBuffer === null) {
|
|
482
583
|
_address = 0n;
|
|
@@ -484,6 +585,9 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
484
585
|
_address = addressOrBuffer;
|
|
485
586
|
} else if (typeof addressOrBuffer === "number") {
|
|
486
587
|
_address = BigInt(addressOrBuffer);
|
|
588
|
+
} else if (typeof addressOrBuffer === "object" && Buffer.isBuffer(addressOrBuffer._buffer)) {
|
|
589
|
+
// Istanza ctypes (array, struct): la sua memoria.
|
|
590
|
+
pointTo(addressOrBuffer._buffer);
|
|
487
591
|
} else if (Buffer.isBuffer(addressOrBuffer)) {
|
|
488
592
|
pointTo(addressOrBuffer);
|
|
489
593
|
}
|
|
@@ -491,14 +595,48 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
491
595
|
// Puntare a un Buffer; una copia di memoria nativa (memory/mirror.js)
|
|
492
596
|
// vale il suo indirizzo originale, come un puntatore creato da indirizzo.
|
|
493
597
|
function pointTo(buf) {
|
|
598
|
+
_objects = undefined;
|
|
599
|
+
_memory = undefined;
|
|
494
600
|
const mirrored = mirrorAddress(buf);
|
|
495
601
|
if (mirrored !== undefined) {
|
|
496
602
|
_buffer = null;
|
|
497
603
|
_address = mirrored;
|
|
498
|
-
|
|
604
|
+
_objects = buf;
|
|
605
|
+
const domain = memoryDomain(buf);
|
|
606
|
+
_memory = { owner: buf, root: domain.root, origin: mirrored - domain.offset - BigInt(buf.byteOffset) };
|
|
607
|
+
_memory[kPointerMemory] = true;
|
|
608
|
+
} else {
|
|
609
|
+
_buffer = buf;
|
|
610
|
+
_address = getBufferAddress(buf);
|
|
611
|
+
}
|
|
612
|
+
store();
|
|
613
|
+
}
|
|
614
|
+
|
|
615
|
+
function getMemory() {
|
|
616
|
+
if (_memory === undefined) {
|
|
617
|
+
let buffer = _buffer;
|
|
618
|
+
let address = _address;
|
|
619
|
+
if (buffer === null && _objects !== null && typeof _objects === "object") {
|
|
620
|
+
const known = _objects.constructor?._isPointerValued ? keptObject(_objects._buffer, 0) : _objects;
|
|
621
|
+
const candidate = Buffer.isBuffer(known) ? known : known?._buffer;
|
|
622
|
+
if (Buffer.isBuffer(candidate)) {
|
|
623
|
+
const base = getBufferAddress(candidate);
|
|
624
|
+
if (_address >= base && _address < base + BigInt(candidate.length)) {
|
|
625
|
+
buffer = candidate;
|
|
626
|
+
address = base;
|
|
627
|
+
}
|
|
628
|
+
}
|
|
629
|
+
}
|
|
630
|
+
const domain = buffer === null ? { root: {}, offset: 0n } : memoryDomain(buffer);
|
|
631
|
+
_memory = {
|
|
632
|
+
owner: buffer ?? _objects,
|
|
633
|
+
root: domain.root,
|
|
634
|
+
origin: buffer === null ? 0n : address - domain.offset - BigInt(buffer.byteOffset),
|
|
635
|
+
};
|
|
636
|
+
_memory[kPointerMemory] = true;
|
|
637
|
+
if (_slot !== null) keepAlive(_slot, 0, _memory);
|
|
499
638
|
}
|
|
500
|
-
|
|
501
|
-
_address = getBufferAddress(buf);
|
|
639
|
+
return _memory;
|
|
502
640
|
}
|
|
503
641
|
|
|
504
642
|
const instance = {
|
|
@@ -510,9 +648,28 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
510
648
|
* Get the raw address as BigInt
|
|
511
649
|
*/
|
|
512
650
|
get address() {
|
|
651
|
+
sync();
|
|
513
652
|
return _address;
|
|
514
653
|
},
|
|
515
654
|
|
|
655
|
+
/**
|
|
656
|
+
* Memoria del puntatore (POINTER_SIZE byte con l'indirizzo): ciò che
|
|
657
|
+
* byref(p) / addressof(p) passano al C.
|
|
658
|
+
*/
|
|
659
|
+
get _pointerSlot() {
|
|
660
|
+
if (_slot === null) {
|
|
661
|
+
_slot = alloc(native.POINTER_SIZE);
|
|
662
|
+
store();
|
|
663
|
+
}
|
|
664
|
+
return _slot;
|
|
665
|
+
},
|
|
666
|
+
|
|
667
|
+
/** Oggetti tenuti vivi dal puntatore (Python `_objects`). */
|
|
668
|
+
get _objects() {
|
|
669
|
+
sync();
|
|
670
|
+
return getMemory();
|
|
671
|
+
},
|
|
672
|
+
|
|
516
673
|
/**
|
|
517
674
|
* Python ctypes compatible: the pointed object. For simple types and
|
|
518
675
|
* Structure/Union classes it is a live instance on the pointed memory
|
|
@@ -520,25 +677,32 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
520
677
|
* the pointer to it, assigning a plain value writes it.
|
|
521
678
|
*/
|
|
522
679
|
get contents() {
|
|
680
|
+
sync();
|
|
523
681
|
if (_address === 0n && !_buffer) {
|
|
524
682
|
throw new Error("NULL pointer access");
|
|
525
683
|
}
|
|
526
684
|
if (isPointerBase()) {
|
|
527
|
-
return readPointerAt(_buffer, _address, 0);
|
|
685
|
+
return readPointerAt(_buffer, _address, 0, getMemory());
|
|
528
686
|
}
|
|
529
687
|
if (hasInstances()) {
|
|
530
|
-
return instanceAt(_buffer, _address, 0);
|
|
688
|
+
return instanceAt(_buffer, _address, 0, getMemory());
|
|
531
689
|
}
|
|
532
690
|
if (_buffer) {
|
|
533
691
|
// We have the actual buffer, read from it
|
|
534
692
|
return readValue(_buffer, baseType, 0);
|
|
535
693
|
}
|
|
536
|
-
return readAtAddress(_address);
|
|
694
|
+
return readAtAddress(_address, getMemory());
|
|
537
695
|
},
|
|
538
696
|
|
|
539
697
|
set contents(value) {
|
|
698
|
+
sync();
|
|
540
699
|
// Python: assegnare un'istanza ri-punta il puntatore a quell'istanza.
|
|
541
|
-
if (value !== null && typeof value === "object" && (value._isSimpleCDataInstance === true || value._structDef !== undefined) && Buffer.isBuffer(value._buffer)) {
|
|
700
|
+
if (value !== null && typeof value === "object" && (value._isSimpleCDataInstance === true || value._structDef !== undefined || value._arrayType !== undefined) && Buffer.isBuffer(value._buffer)) {
|
|
701
|
+
// Python accetta anche un'istanza di un altro tipo; una più piccola
|
|
702
|
+
// del tipo puntato farebbe leggere e scrivere oltre la sua memoria.
|
|
703
|
+
if (value._buffer.length < baseSize) {
|
|
704
|
+
throw new TypeError(`contents: ${value.constructor?.name ?? "instance"} (${value._buffer.length} bytes) is smaller than the pointed type (${baseSize} bytes)`);
|
|
705
|
+
}
|
|
542
706
|
pointTo(value._buffer);
|
|
543
707
|
return;
|
|
544
708
|
}
|
|
@@ -546,11 +710,11 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
546
710
|
throw new Error("NULL pointer access");
|
|
547
711
|
}
|
|
548
712
|
if (isPointerBase()) {
|
|
549
|
-
writePointerAt(_buffer, _address, 0, value);
|
|
713
|
+
writePointerAt(_buffer, _address, 0, value, getMemory());
|
|
550
714
|
} else if (_buffer) {
|
|
551
715
|
writeValue(_buffer, baseType, value, 0);
|
|
552
716
|
} else {
|
|
553
|
-
writeAtAddress(_address, value);
|
|
717
|
+
writeAtAddress(_address, value, getMemory());
|
|
554
718
|
}
|
|
555
719
|
},
|
|
556
720
|
|
|
@@ -558,6 +722,7 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
558
722
|
* Returns the buffer this pointer points to (if available)
|
|
559
723
|
*/
|
|
560
724
|
get _buffer() {
|
|
725
|
+
sync();
|
|
561
726
|
return _buffer;
|
|
562
727
|
},
|
|
563
728
|
|
|
@@ -574,12 +739,12 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
574
739
|
set(value) {
|
|
575
740
|
if (Buffer.isBuffer(value)) {
|
|
576
741
|
pointTo(value);
|
|
577
|
-
} else if (typeof value === "bigint") {
|
|
578
|
-
_address = value;
|
|
579
|
-
_buffer = null;
|
|
580
|
-
} else if (typeof value === "number") {
|
|
742
|
+
} else if (typeof value === "bigint" || typeof value === "number") {
|
|
581
743
|
_address = BigInt(value);
|
|
582
744
|
_buffer = null;
|
|
745
|
+
_objects = undefined;
|
|
746
|
+
_memory = undefined;
|
|
747
|
+
store();
|
|
583
748
|
}
|
|
584
749
|
},
|
|
585
750
|
|
|
@@ -587,6 +752,7 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
587
752
|
* Check if pointer is NULL
|
|
588
753
|
*/
|
|
589
754
|
get isNull() {
|
|
755
|
+
sync();
|
|
590
756
|
return _address === 0n && !_buffer;
|
|
591
757
|
},
|
|
592
758
|
|
|
@@ -594,12 +760,15 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
594
760
|
* For compatibility - get pointer as buffer (8 bytes containing address)
|
|
595
761
|
*/
|
|
596
762
|
toBuffer() {
|
|
763
|
+
sync();
|
|
597
764
|
const buf = alloc(native.POINTER_SIZE);
|
|
598
765
|
writeValue(buf, c_void_p, _address);
|
|
766
|
+
keepAlive(buf, 0, _memory ?? _buffer ?? _objects);
|
|
599
767
|
return buf;
|
|
600
768
|
},
|
|
601
769
|
|
|
602
770
|
toString() {
|
|
771
|
+
sync();
|
|
603
772
|
return `<${typeName} pointer at 0x${_address.toString(16)}>`;
|
|
604
773
|
},
|
|
605
774
|
|
|
@@ -608,8 +777,10 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
608
777
|
* `ptr + n`. The pointer keeps the same element type.
|
|
609
778
|
*/
|
|
610
779
|
add(n) {
|
|
780
|
+
sync();
|
|
611
781
|
const offsetBytes = BigInt(n) * BigInt(baseSize);
|
|
612
|
-
|
|
782
|
+
// Il nuovo puntatore tiene viva la memoria di questo (Python _objects).
|
|
783
|
+
return createPointerInstance(_address + offsetBytes, _buffer ?? _objects, getMemory());
|
|
613
784
|
},
|
|
614
785
|
|
|
615
786
|
/**
|
|
@@ -637,10 +808,10 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
637
808
|
}
|
|
638
809
|
const offset = index * baseSize;
|
|
639
810
|
if (isPointerBase()) {
|
|
640
|
-
return readPointerAt(_buffer, _address, offset);
|
|
811
|
+
return readPointerAt(_buffer, _address, offset, getMemory());
|
|
641
812
|
}
|
|
642
813
|
if (isStructBase()) {
|
|
643
|
-
return instanceAt(_buffer, _address, offset);
|
|
814
|
+
return instanceAt(_buffer, _address, offset, getMemory());
|
|
644
815
|
}
|
|
645
816
|
if (_buffer && offset + baseSize <= _buffer.length) {
|
|
646
817
|
if (typeof baseType === "function" && baseType._isSimpleCData) {
|
|
@@ -648,7 +819,7 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
648
819
|
}
|
|
649
820
|
return readValue(_buffer, baseType, offset);
|
|
650
821
|
}
|
|
651
|
-
return readAtAddress(_address + BigInt(offset));
|
|
822
|
+
return readAtAddress(_address + BigInt(offset), getMemory());
|
|
652
823
|
}
|
|
653
824
|
return Reflect.get(target, prop, receiver);
|
|
654
825
|
},
|
|
@@ -662,14 +833,14 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
662
833
|
}
|
|
663
834
|
const offset = index * baseSize;
|
|
664
835
|
if (isPointerBase()) {
|
|
665
|
-
writePointerAt(_buffer, _address, offset, value);
|
|
836
|
+
writePointerAt(_buffer, _address, offset, value, getMemory());
|
|
666
837
|
return true;
|
|
667
838
|
}
|
|
668
839
|
if (_buffer && offset + baseSize <= _buffer.length) {
|
|
669
840
|
writeValue(_buffer, baseType, value, offset);
|
|
670
841
|
return true;
|
|
671
842
|
}
|
|
672
|
-
writeAtAddress(_address + BigInt(offset), value);
|
|
843
|
+
writeAtAddress(_address + BigInt(offset), value, getMemory());
|
|
673
844
|
return true;
|
|
674
845
|
}
|
|
675
846
|
return Reflect.set(target, prop, value, receiver);
|
|
@@ -717,8 +888,8 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
|
|
|
717
888
|
* @param {bigint|number} address - Memory address
|
|
718
889
|
* @returns {Object} Pointer instance
|
|
719
890
|
*/
|
|
720
|
-
fromAddress(address) {
|
|
721
|
-
return createPointerInstance(typeof address === "bigint" ? address : BigInt(address));
|
|
891
|
+
fromAddress(address, keep) {
|
|
892
|
+
return createPointerInstance(typeof address === "bigint" ? address : BigInt(address), keep);
|
|
722
893
|
},
|
|
723
894
|
|
|
724
895
|
/**
|
|
@@ -783,14 +954,16 @@ export function pointer(obj, POINTER_fn, sizeof, alloc, readValue, writeValue, c
|
|
|
783
954
|
let targetBuffer;
|
|
784
955
|
let baseType;
|
|
785
956
|
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
// Structure/Union instance or SimpleCData with _buffer
|
|
957
|
+
// Le istanze di array sono Proxy su un Buffer (Buffer.isBuffer è vero): la
|
|
958
|
+
// loro memoria è `_buffer`, controllato per primo.
|
|
959
|
+
if (obj !== null && typeof obj === "object" && Buffer.isBuffer(obj._buffer)) {
|
|
960
|
+
// Structure/Union instance, array or SimpleCData with _buffer
|
|
791
961
|
targetBuffer = obj._buffer;
|
|
792
962
|
// Get the base type for POINTER creation
|
|
793
|
-
if (obj.
|
|
963
|
+
if (obj._arrayType !== undefined) {
|
|
964
|
+
// Python: pointer(c_int * 3 instance) è un POINTER(c_int * 3).
|
|
965
|
+
baseType = obj._arrayType;
|
|
966
|
+
} else if (obj.constructor && obj.constructor._type) {
|
|
794
967
|
// SimpleCData instance - use the class itself (c_int32, c_double, etc.)
|
|
795
968
|
baseType = obj.constructor;
|
|
796
969
|
} else if (obj._structDef) {
|
|
@@ -799,6 +972,9 @@ export function pointer(obj, POINTER_fn, sizeof, alloc, readValue, writeValue, c
|
|
|
799
972
|
} else {
|
|
800
973
|
baseType = c_void_p;
|
|
801
974
|
}
|
|
975
|
+
} else if (Buffer.isBuffer(obj)) {
|
|
976
|
+
targetBuffer = obj;
|
|
977
|
+
baseType = c_void_p; // Generic pointer
|
|
802
978
|
} else {
|
|
803
979
|
throw new TypeError("pointer() argument must be a ctypes instance or Buffer");
|
|
804
980
|
}
|