node-ctypes 2.14.0 → 2.15.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 +27 -1
- 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 +69 -51
- package/lib/core/callback-conversions.js +123 -0
- package/lib/core/callback.js +68 -4
- package/lib/core/conversions.js +74 -412
- package/lib/core/funcptr.js +31 -287
- package/lib/core/invocation.js +170 -0
- package/lib/core/native-aggregate.js +193 -0
- package/lib/core/parameters.js +45 -0
- package/lib/core/paramflags.js +183 -0
- package/lib/core/results.js +86 -0
- package/lib/core/types.js +14 -277
- package/lib/index.js +2 -1
- package/lib/memory/buffer.js +1 -1
- package/lib/memory/mirror.js +2 -2
- package/lib/memory/operations.js +2 -1
- package/lib/memory/ownership.js +218 -0
- package/lib/memory/pointer.js +6 -1
- package/lib/platform/win_types.js +1 -1
- package/lib/structures/Structure.js +50 -37
- package/lib/structures/helpers/array.js +27 -13
- package/lib/structures/helpers/bitfield.js +1 -1
- package/lib/structures/helpers/common.js +3 -368
- package/lib/structures/helpers/fields.js +111 -0
- package/lib/structures/helpers/layout.js +44 -57
- package/lib/structures/helpers/struct.js +19 -108
- package/lib/structures/helpers/union.js +13 -114
- package/lib/structures/helpers/wrap.js +1 -1
- package/lib/structures/protocol.js +8 -0
- package/lib/types/SimpleCData.js +2 -1
- package/lib/types/primitives.js +2 -1
- package/lib/types/scalar-protocol.js +120 -0
- package/package.json +1 -1
package/lib/core/types.js
CHANGED
|
@@ -1,319 +1,56 @@
|
|
|
1
|
-
/**
|
|
2
|
-
|
|
3
|
-
* @module core/types
|
|
4
|
-
* @description Type normalization helpers tra il formato JS-facing della lib
|
|
5
|
-
* e quello richiesto dal binding nativo (`FFIFunction` / `Callback` / ecc.).
|
|
6
|
-
*
|
|
7
|
-
* Le classi `Structure`/`Union` JS (e `struct()`/`union()` plain helpers)
|
|
8
|
-
* producono `structDef` — oggetti JS con `fields`/`fieldMap`/ecc. — **non**
|
|
9
|
-
* sono il native `StructType` che il C++ si aspetta come argtype/restype.
|
|
10
|
-
*
|
|
11
|
-
* `_buildNativeStructType` costruisce (o recupera cached) il wrapper
|
|
12
|
-
* `new native.StructType()` popolato con `addField(name, type)` per ogni
|
|
13
|
-
* campo del def. Supporta tutti i tipi di field:
|
|
14
|
-
*
|
|
15
|
-
* - SimpleCData primitives (c_int32, ecc.)
|
|
16
|
-
* - POINTER
|
|
17
|
-
* - Bitfield: i byte che contengono bitfield diventano campi uint8 agli
|
|
18
|
-
* offset del layout JS (con gcc-sysv un bitfield può condividere byte con
|
|
19
|
-
* altri campi, e un unico tipo per "cella" non riprodurrebbe gli offset).
|
|
20
|
-
* - Campi disallineati (`_pack_`): byte uint8 agli offset del layout JS.
|
|
21
|
-
* - Array: sia `array(SimpleCData, N)` sia `array(Structure/Union, N)`;
|
|
22
|
-
* per il secondo caso il native ArrayType è costruito lazy qui.
|
|
23
|
-
* - Nested Structure/Union (anche `_anonymous_`): ricorsione.
|
|
24
|
-
* - Classe base (Python: sottoclasse con _fields_): primo campo, come in C.
|
|
25
|
-
*
|
|
26
|
-
* Dimensione e allineamento sono quelli del layout JS (layout.js, `_align_`).
|
|
27
|
-
*/
|
|
1
|
+
/** Normalize public ctypes declarations for native arguments and return values. */
|
|
2
|
+
import { buildNativeAggregate } from "./native-aggregate.js";
|
|
28
3
|
|
|
29
|
-
import { cacheWeakValue } from "../utils/cache.js";
|
|
30
|
-
|
|
31
|
-
// ArrayType nativi costruiti per gli array di Structure/Union (gli array JS
|
|
32
|
-
// espongono `_native` in sola lettura).
|
|
33
|
-
const nativeArrayTypes = new WeakMap();
|
|
34
|
-
|
|
35
|
-
// ArrayType nativi uint8[n] per i byte emessi come tali (vedi sotto).
|
|
36
|
-
const byteArrayTypes = new Map();
|
|
37
|
-
|
|
38
|
-
function byteRun(st, native, offset, length) {
|
|
39
|
-
if (length <= 0) return;
|
|
40
|
-
if (length === 1) {
|
|
41
|
-
st.addField(`__byte@${offset}`, native.CType.UINT8);
|
|
42
|
-
return;
|
|
43
|
-
}
|
|
44
|
-
let arrayType = byteArrayTypes.get(length)?.deref();
|
|
45
|
-
if (arrayType === undefined) {
|
|
46
|
-
arrayType = new native.ArrayType(native.CType.UINT8, length);
|
|
47
|
-
cacheWeakValue(byteArrayTypes, length, arrayType);
|
|
48
|
-
}
|
|
49
|
-
st.addField(`__bytes@${offset}`, arrayType);
|
|
50
|
-
}
|
|
51
|
-
|
|
52
|
-
const roundUp = (n, a) => Math.ceil(n / a) * a;
|
|
53
|
-
|
|
54
|
-
// Byte toccati da un bitfield (dentro la sua unità di `baseSize` byte).
|
|
55
|
-
function bitFieldBytes(f) {
|
|
56
|
-
const first = Math.floor(f.bitOffset / 8);
|
|
57
|
-
const last = Math.floor((f.bitOffset + f.bitSize - 1) / 8);
|
|
58
|
-
const bytes = [];
|
|
59
|
-
for (let b = first; b <= last; b++) {
|
|
60
|
-
bytes.push(f.offset + (f.swapped ? f.baseSize - 1 - b : b));
|
|
61
|
-
}
|
|
62
|
-
return bytes;
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
const nestedDefOf = (f) => {
|
|
66
|
-
if (f.isNested) return typeof f.type === "function" ? f.type._structDef || f.type._buildStruct?.() : f.type;
|
|
67
|
-
const element = f.isArray ? f.type?.elementType : undefined;
|
|
68
|
-
if (typeof element === "function" && typeof element._buildStruct === "function") return element._structDef || element._buildStruct();
|
|
69
|
-
return undefined;
|
|
70
|
-
};
|
|
71
|
-
|
|
72
|
-
// Campi (anche di struct annidate) a un offset non multiplo del loro
|
|
73
|
-
// allineamento C, come con `_pack_`: l'ABI x86-64 System V passa queste struct
|
|
74
|
-
// in memoria (vedi StructInfo::SetMemoryClass).
|
|
75
|
-
const unalignedDefs = new WeakMap();
|
|
76
|
-
function hasUnalignedFields(def) {
|
|
77
|
-
let result = unalignedDefs.get(def);
|
|
78
|
-
if (result === undefined) {
|
|
79
|
-
result = def.fields.some((f) => {
|
|
80
|
-
if (f.isBitField) return false;
|
|
81
|
-
if (!def.isUnion && f.offset % (f.naturalAlignment ?? f.alignment) !== 0) return true;
|
|
82
|
-
const nested = nestedDefOf(f);
|
|
83
|
-
return nested !== undefined && hasUnalignedFields(nested);
|
|
84
|
-
});
|
|
85
|
-
unalignedDefs.set(def, result);
|
|
86
|
-
}
|
|
87
|
-
return result;
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
/**
|
|
91
|
-
* Costruisce (o recupera cached) un native `StructType` corrispondente a un
|
|
92
|
-
* structDef/unionDef. Cacheato su `def._nativeStructType` per evitare
|
|
93
|
-
* ricostruzioni multiple sulla stessa def.
|
|
94
|
-
*
|
|
95
|
-
* La struct nativa ha gli offset, la dimensione e l'allineamento del layout
|
|
96
|
-
* JS (layout.js, `_pack_`, `_align_`, bitfield). Un campo resta del suo tipo
|
|
97
|
-
* (che conta per la classificazione dell'ABI: float/double vanno nei registri
|
|
98
|
-
* SSE) quando nella struct nativa cade allo stesso offset: offset allineato al
|
|
99
|
-
* suo allineamento C, non superiore a quello della struct. Altrimenti (campi
|
|
100
|
-
* disallineati da `_pack_`, byte dei bitfield) i suoi byte diventano uint8. Il
|
|
101
|
-
* padding non è emesso, se non prima di byte da collocare all'offset giusto.
|
|
102
|
-
*
|
|
103
|
-
* @param {Object} def - structDef o unionDef (output di `struct()`/`union()`
|
|
104
|
-
* o `_structDef` di una Structure class).
|
|
105
|
-
* @param {Object} native - modulo native (`require('ctypes.node')`).
|
|
106
|
-
* @returns {Object} istanza di `native.StructType` utilizzabile come
|
|
107
|
-
* argtype/restype dal FFIFunction.
|
|
108
|
-
*/
|
|
109
|
-
function _buildNativeStructType(def, native) {
|
|
110
|
-
if (def._nativeStructType) return def._nativeStructType;
|
|
111
|
-
if (!Number.isInteger(Math.log2(def.alignment))) {
|
|
112
|
-
throw new TypeError("Native by-value ABI requires power-of-two alignment; use this layout only for memory serialization");
|
|
113
|
-
}
|
|
114
|
-
const st = new native.StructType({
|
|
115
|
-
union: !!def.isUnion,
|
|
116
|
-
alignment: def.alignment,
|
|
117
|
-
memoryClass: hasUnalignedFields(def),
|
|
118
|
-
});
|
|
119
|
-
const fits = (alignment, offset) => alignment <= def.alignment && offset % alignment === 0;
|
|
120
|
-
|
|
121
|
-
// La classe base è il primo membro della struct (i suoi campi sono i primi
|
|
122
|
-
// di def.fields, agli stessi offset).
|
|
123
|
-
let fields = def.fields;
|
|
124
|
-
let position = 0;
|
|
125
|
-
if (def.base) {
|
|
126
|
-
if (fits(def.base.alignment, 0)) st.addField("__base__", _buildNativeStructType(def.base, native));
|
|
127
|
-
else byteRun(st, native, 0, def.base.size);
|
|
128
|
-
fields = def.fields.slice(def.base.fields.length);
|
|
129
|
-
position = def.isUnion ? 0 : def.base.size;
|
|
130
|
-
}
|
|
131
|
-
|
|
132
|
-
if (def.isUnion) {
|
|
133
|
-
for (const f of fields) {
|
|
134
|
-
const size = f.isBitField ? f.baseSize : f.size;
|
|
135
|
-
const alignment = f.naturalAlignment ?? f.alignment;
|
|
136
|
-
if (!fits(alignment, 0)) byteRun(st, native, 0, size);
|
|
137
|
-
// Un bitfield occupa il proprio tipo base all'offset 0.
|
|
138
|
-
else if (f.isBitField) st.addField(`__bitfield_${f.name}`, bitFieldBaseType(f));
|
|
139
|
-
else addNativeField(st, f, native);
|
|
140
|
-
}
|
|
141
|
-
} else {
|
|
142
|
-
// Campi e byte dei bitfield in ordine di offset.
|
|
143
|
-
const items = [];
|
|
144
|
-
const bitBytes = new Set();
|
|
145
|
-
for (const f of fields) {
|
|
146
|
-
if (f.isBitField) bitFieldBytes(f).forEach((b) => bitBytes.add(b));
|
|
147
|
-
else if (f.size > 0) items.push({ offset: f.offset, size: f.size, field: f });
|
|
148
|
-
}
|
|
149
|
-
for (const b of bitBytes) items.push({ offset: b, size: 1, field: null });
|
|
150
|
-
items.sort((a, b) => a.offset - b.offset);
|
|
151
|
-
|
|
152
|
-
let bytesFrom = -1; // inizio della sequenza di byte in corso
|
|
153
|
-
const flushBytes = () => {
|
|
154
|
-
if (bytesFrom >= 0) byteRun(st, native, bytesFrom, position - bytesFrom);
|
|
155
|
-
bytesFrom = -1;
|
|
156
|
-
};
|
|
157
|
-
const addBytes = (offset, size) => {
|
|
158
|
-
if (bytesFrom < 0) bytesFrom = position;
|
|
159
|
-
position = offset + size;
|
|
160
|
-
};
|
|
161
|
-
|
|
162
|
-
for (const { offset, size, field } of items) {
|
|
163
|
-
if (offset < position) continue; // byte già coperto
|
|
164
|
-
const alignment = field ? (field.naturalAlignment ?? field.alignment) : 1;
|
|
165
|
-
if (field && fits(alignment, offset)) {
|
|
166
|
-
// Il padding naturale prima del campo resta padding; un vuoto più
|
|
167
|
-
// grande (es. `_align_` di una struct annidata) diventa byte.
|
|
168
|
-
if (roundUp(position, alignment) !== offset) addBytes(offset, 0);
|
|
169
|
-
flushBytes();
|
|
170
|
-
addNativeField(st, field, native);
|
|
171
|
-
position = offset + size;
|
|
172
|
-
} else {
|
|
173
|
-
addBytes(offset, size);
|
|
174
|
-
}
|
|
175
|
-
}
|
|
176
|
-
flushBytes();
|
|
177
|
-
// Coda oltre l'arrotondamento all'allineamento (non accade con i layout
|
|
178
|
-
// di layout.js, ma la dimensione deve comunque coincidere).
|
|
179
|
-
if (roundUp(position, def.alignment) < def.size) byteRun(st, native, position, def.size - position);
|
|
180
|
-
}
|
|
181
|
-
|
|
182
|
-
const size = st.getSize();
|
|
183
|
-
if (size !== def.size || st.getAlignment() !== def.alignment) {
|
|
184
|
-
throw new Error(`Native layout of the structure (size ${size}, alignment ${st.getAlignment()}) differs from its definition (size ${def.size}, alignment ${def.alignment})`);
|
|
185
|
-
}
|
|
186
|
-
def._nativeStructType = st;
|
|
187
|
-
return st;
|
|
188
|
-
}
|
|
189
|
-
|
|
190
|
-
function bitFieldBaseType(f) {
|
|
191
|
-
if (!f.type || typeof f.type._type !== "number") {
|
|
192
|
-
throw new Error(`Bitfield '${f.name}': base type senza _type numerico`);
|
|
193
|
-
}
|
|
194
|
-
return f.type._type;
|
|
195
|
-
}
|
|
196
|
-
|
|
197
|
-
function addNativeField(st, f, native) {
|
|
198
|
-
const options = f.isAnonymous ? { anonymous: true } : undefined;
|
|
199
|
-
if (f.isArray) {
|
|
200
|
-
// Array di primitive (o di struct native): `_native` è già un ArrayType.
|
|
201
|
-
const own = f.type?._native;
|
|
202
|
-
if (own && typeof own.getSize === "function" && own.constructor?.name === "ArrayType") {
|
|
203
|
-
st.addField(f.name, own, options);
|
|
204
|
-
return;
|
|
205
|
-
}
|
|
206
|
-
// Array di Structure/Union: ArrayType nativo costruito qui (una volta per tipo).
|
|
207
|
-
const elementType = f.type?.elementType;
|
|
208
|
-
const count = f.type?.length;
|
|
209
|
-
const elemDef = typeof elementType === "function" && typeof elementType._buildStruct === "function" ? elementType._structDef || elementType._buildStruct() : elementType?._isStructType === true ? elementType : undefined;
|
|
210
|
-
if (elemDef !== undefined && typeof count === "number") {
|
|
211
|
-
let arrNative = nativeArrayTypes.get(f.type);
|
|
212
|
-
if (arrNative === undefined) {
|
|
213
|
-
arrNative = new native.ArrayType(_buildNativeStructType(elemDef, native), count);
|
|
214
|
-
nativeArrayTypes.set(f.type, arrNative);
|
|
215
|
-
}
|
|
216
|
-
st.addField(f.name, arrNative, options);
|
|
217
|
-
return;
|
|
218
|
-
}
|
|
219
|
-
throw new Error(`Field '${f.name}': array-in-struct-by-value non riconosciuto. ` + `Tipi supportati: array(SimpleCData, N), array(Structure/Union subclass o struct()/union(), N). ` + `Alternativa: passa la struct per puntatore.`);
|
|
220
|
-
}
|
|
221
|
-
if (f.isNested) {
|
|
222
|
-
// f.type è un structDef/unionDef (quando dichiarato via struct/union)
|
|
223
|
-
// o una Structure/Union class (quando dichiarato con class extends).
|
|
224
|
-
let nestedDef = f.type;
|
|
225
|
-
if (typeof f.type === "function") {
|
|
226
|
-
nestedDef = f.type._structDef || f.type._buildStruct?.();
|
|
227
|
-
}
|
|
228
|
-
if (!nestedDef || !Array.isArray(nestedDef.fields)) {
|
|
229
|
-
throw new Error(`Field '${f.name}': nested type non riconosciuto`);
|
|
230
|
-
}
|
|
231
|
-
st.addField(f.name, _buildNativeStructType(nestedDef, native), options);
|
|
232
|
-
return;
|
|
233
|
-
}
|
|
234
|
-
if (f.isPointer) {
|
|
235
|
-
st.addField(f.name, native.CType.POINTER);
|
|
236
|
-
return;
|
|
237
|
-
}
|
|
238
|
-
// SimpleCData class: usa il suo _type numerico.
|
|
239
|
-
if (f.type && typeof f.type === "function" && f.type._isSimpleCData) {
|
|
240
|
-
st.addField(f.name, f.type._type);
|
|
241
|
-
return;
|
|
242
|
-
}
|
|
243
|
-
throw new Error(`Field '${f.name}': tipo non riconosciuto durante _buildNativeStructType`);
|
|
244
|
-
}
|
|
245
|
-
|
|
246
|
-
/**
|
|
247
|
-
* Normalizza un tipo singolo nel formato atteso dal native FFIFunction.
|
|
248
|
-
*
|
|
249
|
-
* Regole di conversione:
|
|
250
|
-
* 1. SimpleCData class (c_int32, c_char_p, ecc.): ritorna `_type` numerico.
|
|
251
|
-
* 2. POINTER(T) wrapper (ha `_pointerTo`): ritorna `CType.POINTER`.
|
|
252
|
-
* 3. Structure / Union class: costruisce (o cachea) un native StructType.
|
|
253
|
-
* 4. Plain structDef / unionDef (ha `_isStructType`): idem.
|
|
254
|
-
* 5. ArrayType wrapper (ha `_isArrayType`): ritorna il `_native` se
|
|
255
|
-
* disponibile, altrimenti l'object.
|
|
256
|
-
* 6. Numero: pass-through (già un CType).
|
|
257
|
-
* 7. Altro: pass-through (es. native CType object, HRESULT, ecc.).
|
|
258
|
-
*/
|
|
259
4
|
export function _toNativeType(type, native) {
|
|
260
|
-
// 1. SimpleCData
|
|
261
5
|
if (typeof type === "function" && type._isSimpleCData) {
|
|
262
6
|
return type._type;
|
|
263
7
|
}
|
|
264
8
|
|
|
265
|
-
// 2. POINTER wrapper
|
|
266
9
|
if (type && typeof type === "object" && type._pointerTo !== undefined) {
|
|
267
10
|
return native.CType.POINTER;
|
|
268
11
|
}
|
|
269
12
|
|
|
270
|
-
// 2b. Tipo funzione CFUNCTYPE / WINFUNCTYPE (Python: argtypes = [..., CMPFUNC])
|
|
271
13
|
if (typeof type === "function" && type._isFuncPtr === true) {
|
|
272
14
|
return native.CType.POINTER;
|
|
273
15
|
}
|
|
274
16
|
|
|
275
|
-
// 3. Structure / Union subclass → native StructType.
|
|
276
17
|
if (typeof type === "function" && typeof type._buildStruct === "function") {
|
|
277
18
|
const def = type._structDef || type._buildStruct();
|
|
278
|
-
return
|
|
19
|
+
return buildNativeAggregate(def, native);
|
|
279
20
|
}
|
|
280
21
|
if (typeof type === "function" && typeof type._buildUnion === "function") {
|
|
281
22
|
const def = type._unionDef || type._buildUnion();
|
|
282
|
-
return
|
|
23
|
+
return buildNativeAggregate(def, native);
|
|
283
24
|
}
|
|
284
25
|
|
|
285
|
-
// 4. Plain structDef / unionDef.
|
|
286
26
|
if (type && typeof type === "object" && type._isStructType && Array.isArray(type.fields)) {
|
|
287
|
-
return
|
|
27
|
+
return buildNativeAggregate(type, native);
|
|
288
28
|
}
|
|
289
29
|
|
|
290
|
-
// 5. Array wrapper
|
|
291
30
|
if (type && (typeof type === "object" || typeof type === "function") && type._isArrayType) {
|
|
292
31
|
return type._native || type;
|
|
293
32
|
}
|
|
294
33
|
|
|
295
|
-
// 6. Numero
|
|
296
34
|
if (typeof type === "number") return type;
|
|
297
35
|
|
|
298
|
-
// 7. Pass-through
|
|
299
36
|
return type;
|
|
300
37
|
}
|
|
301
38
|
|
|
302
|
-
|
|
303
|
-
* Come _toNativeType, per i tipi di ritorno: `null` vale `void`
|
|
304
|
-
* (Python ctypes: `restype = None`, `CFUNCTYPE(None, ...)`).
|
|
305
|
-
*/
|
|
39
|
+
// A null restype denotes void, not a null pointer.
|
|
306
40
|
export function _toNativeReturnType(type, native) {
|
|
307
41
|
if (type === null) return native.CType.VOID;
|
|
308
42
|
return _toNativeType(type, native);
|
|
309
43
|
}
|
|
310
44
|
|
|
311
|
-
|
|
312
|
-
* Normalizza un array di tipi di argomento (batch). Non-array → pass-through.
|
|
313
|
-
* Un tipo array come argomento è un puntatore, come in C e Python
|
|
314
|
-
* (`argtypes = [c_int * 4]` passa l'indirizzo dell'array).
|
|
315
|
-
*/
|
|
45
|
+
// Array parameters decay to pointers; array fields in aggregates do not.
|
|
316
46
|
export function _toNativeTypes(types, native) {
|
|
317
47
|
if (!Array.isArray(types)) return types;
|
|
318
48
|
return types.map((type) => (type && (typeof type === "object" || typeof type === "function") && type._isArrayType === true ? native.CType.POINTER : _toNativeType(type, native)));
|
|
319
49
|
}
|
|
50
|
+
|
|
51
|
+
export function requireDescriptor(type, native, index) {
|
|
52
|
+
// A low-level array wrapper can resolve its _native getter later, at binding.
|
|
53
|
+
if (type instanceof native.StructType || type instanceof native.ArrayType || "_native" in type) return;
|
|
54
|
+
const position = index === undefined ? "return type" : `argument type at index ${index}`;
|
|
55
|
+
throw new TypeError(`Invalid ${position}: expected a ctypes type descriptor`);
|
|
56
|
+
}
|
package/lib/index.js
CHANGED
|
@@ -43,7 +43,8 @@ import { createMemoryOps } from "./memory/operations.js";
|
|
|
43
43
|
import { enableMirrors, wrapNative } from "./memory/mirror.js";
|
|
44
44
|
import { addressOf as _addressOf, byref as _byref, cast as _cast, ptrToBuffer as _ptrToBuffer, POINTER as _POINTER, pointer as _pointer } from "./memory/pointer.js";
|
|
45
45
|
import { FormatError as _FormatError, WinError as _WinError, ArgumentError } from "./platform/errors.js";
|
|
46
|
-
import { bitfield as _bitfield, _isStruct, _isArrayType, _isBitField
|
|
46
|
+
import { bitfield as _bitfield, _isStruct, _isArrayType, _isBitField } from "./structures/helpers/common.js";
|
|
47
|
+
import { registerSimpleType } from "./types/scalar-protocol.js";
|
|
47
48
|
import { array as _array } from "./structures/helpers/array.js";
|
|
48
49
|
import { union as _union } from "./structures/helpers/union.js";
|
|
49
50
|
import { struct as _struct } from "./structures/helpers/struct.js";
|
package/lib/memory/buffer.js
CHANGED
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
*/
|
|
29
29
|
|
|
30
30
|
import { mirrorAddress } from "./mirror.js";
|
|
31
|
-
import { resolveParameter } from "../
|
|
31
|
+
import { resolveParameter } from "../core/parameters.js";
|
|
32
32
|
import { ArgumentError } from "../platform/errors.js";
|
|
33
33
|
|
|
34
34
|
// Fixed backing stores do not move; resizable/growable stores are never cached.
|
package/lib/memory/mirror.js
CHANGED
|
@@ -214,13 +214,13 @@ export function syncDefinition(def) {
|
|
|
214
214
|
const size = def.size;
|
|
215
215
|
const fieldMap = def.fieldMap;
|
|
216
216
|
const { get, set, toObject } = def;
|
|
217
|
-
def.get = function (bufOrObj, fieldName) {
|
|
217
|
+
def.get = function (bufOrObj, fieldName, owner) {
|
|
218
218
|
if (isMirror(bufOrObj)) {
|
|
219
219
|
const field = fieldMap?.get(fieldName);
|
|
220
220
|
if (field === undefined) refresh(bufOrObj, 0, size);
|
|
221
221
|
else if (!field.isNested && !field.isArray) refresh(bufOrObj, field.offset, fieldSize(field));
|
|
222
222
|
}
|
|
223
|
-
return get.call(this, bufOrObj, fieldName);
|
|
223
|
+
return get.call(this, bufOrObj, fieldName, owner);
|
|
224
224
|
};
|
|
225
225
|
def.set = function (bufOrObj, fieldName, value) {
|
|
226
226
|
if (!isMirror(bufOrObj)) return set.call(this, bufOrObj, fieldName, value);
|
package/lib/memory/operations.js
CHANGED
|
@@ -28,7 +28,8 @@
|
|
|
28
28
|
*/
|
|
29
29
|
|
|
30
30
|
import { flush, mirrorsActive, refresh } from "./mirror.js";
|
|
31
|
-
import { copyInstance
|
|
31
|
+
import { copyInstance } from "./ownership.js";
|
|
32
|
+
import { isScalarSubclass, scalarView } from "../types/scalar-protocol.js";
|
|
32
33
|
|
|
33
34
|
/**
|
|
34
35
|
* Factory che cattura le dipendenze in closure e restituisce un bundle di
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
/** Pointer registrations and leases belong to the backing memory, not to an individual view. */
|
|
2
|
+
import { flush, mirrorsActive, refresh } from "./mirror.js";
|
|
3
|
+
import { POINTER_SIZE } from "../platform/constants.js";
|
|
4
|
+
|
|
5
|
+
export function sourceBytes(source, offset, size, name) {
|
|
6
|
+
const bytes = source !== null && typeof source === "object" && !ArrayBuffer.isView(source) && Buffer.isBuffer(source._buffer) ? source._buffer : source;
|
|
7
|
+
if (!ArrayBuffer.isView(bytes)) throw new TypeError(`${name}: source must be a Buffer, a typed array or a ctypes instance`);
|
|
8
|
+
if (!Number.isSafeInteger(offset)) throw new TypeError(`${name}: offset must be a safe integer`);
|
|
9
|
+
if (offset < 0) throw new RangeError(`${name}: offset cannot be negative`);
|
|
10
|
+
if (bytes.byteLength - offset < size) throw new RangeError(`${name}: Buffer size too small (${bytes.byteLength} instead of at least ${size + offset} bytes)`);
|
|
11
|
+
return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export function keepFunctionOwner(fn, owner) {
|
|
15
|
+
if (owner !== undefined) {
|
|
16
|
+
Object.defineProperty(fn, "_objects", { value: owner });
|
|
17
|
+
// AsyncWorker pins the native handle, not its public JS function.
|
|
18
|
+
Object.defineProperty(fn._ffi, "_objects", { value: owner });
|
|
19
|
+
}
|
|
20
|
+
return fn;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
const keptObjects = new WeakMap();
|
|
24
|
+
|
|
25
|
+
const memoryOwners = new WeakMap();
|
|
26
|
+
|
|
27
|
+
// Address-backed aliases share the reference table of their known owner.
|
|
28
|
+
const memoryDomains = new WeakMap();
|
|
29
|
+
|
|
30
|
+
export function memoryDomain(buf) {
|
|
31
|
+
return memoryDomains.get(buf.buffer) ?? { root: buf.buffer, offset: 0n };
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function memoryPosition(buf, offset) {
|
|
35
|
+
return BigInt(buf.byteOffset + offset) + (memoryDomains.get(buf.buffer)?.offset ?? 0n);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export function shareMemory(buf, memory, position) {
|
|
39
|
+
memoryDomains.set(buf.buffer, { root: memory.root, offset: position - BigInt(buf.byteOffset) });
|
|
40
|
+
return keepMemoryOwner(buf, memory);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
// Attach to the backing store, so subarrays and typed arrays keep the lease too.
|
|
44
|
+
export function keepMemoryOwner(buf, owner) {
|
|
45
|
+
if (owner === undefined || owner === null) return buf;
|
|
46
|
+
let owners = memoryOwners.get(buf.buffer);
|
|
47
|
+
if (owners === undefined) memoryOwners.set(buf.buffer, (owners = new Set()));
|
|
48
|
+
owners.add(owner);
|
|
49
|
+
return buf;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function storedAddress(buf, offset) {
|
|
53
|
+
return POINTER_SIZE === 8 ? buf.readBigUInt64LE(offset) : BigInt(buf.readUInt32LE(offset));
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
export function pointerOwner(buf, offset, address) {
|
|
57
|
+
const root = memoryDomains.get(buf.buffer)?.root ?? buf.buffer;
|
|
58
|
+
const kept = keptObjects.get(root);
|
|
59
|
+
if (kept === undefined) return buf;
|
|
60
|
+
const position = memoryPosition(buf, offset);
|
|
61
|
+
const reference = kept.get(position);
|
|
62
|
+
if (reference !== undefined && reference.address !== (address ?? storedAddress(buf, offset))) {
|
|
63
|
+
kept.delete(position);
|
|
64
|
+
return buf;
|
|
65
|
+
}
|
|
66
|
+
return reference?.owner ?? buf;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export function inDllBuffer(library, name, size, ptrToBuffer) {
|
|
70
|
+
const lib = library?._lib ?? library;
|
|
71
|
+
if (typeof lib?._symbolView !== "function") throw new TypeError("in_dll: first arg must be a Library (CDLL/WinDLL)");
|
|
72
|
+
const { address, owner } = lib._symbolView(name);
|
|
73
|
+
return keepMemoryOwner(ptrToBuffer(address, size), owner);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
function pointerSlots(type, offset = 0, size) {
|
|
77
|
+
if (type?._isPointerValued || type?._isFuncPtr || type?._pointerTo !== undefined) return [[offset, type._size ?? type.size ?? size]];
|
|
78
|
+
if (type?._isArrayType) {
|
|
79
|
+
const slots = [];
|
|
80
|
+
const elementSize = type.length === 0 ? 0 : type.getSize() / type.length;
|
|
81
|
+
const elements = pointerSlots(type.elementType, 0, elementSize);
|
|
82
|
+
if (elements.length === 0) return slots;
|
|
83
|
+
for (let i = 0; i < type.length; i++) {
|
|
84
|
+
for (const [position, width] of elements) slots.push([offset + i * elementSize + position, width]);
|
|
85
|
+
}
|
|
86
|
+
return slots;
|
|
87
|
+
}
|
|
88
|
+
const def = typeof type?._buildStruct === "function" ? (type._structDef ?? type._buildStruct()) : type;
|
|
89
|
+
const slots = [];
|
|
90
|
+
for (const field of def?.fields ?? []) {
|
|
91
|
+
if (field.isPointer) slots.push([offset + field.offset, field.size]);
|
|
92
|
+
else slots.push(...pointerSlots(field.type, offset + field.offset, field.size));
|
|
93
|
+
}
|
|
94
|
+
return slots;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Keep `value` alive as long as the memory of `targetBuf`, like Python ctypes
|
|
99
|
+
* `_objects`: an object whose address is stored in the buffer (string,
|
|
100
|
+
* pointer, callback) must not be garbage collected while native code can
|
|
101
|
+
* still read that address. The table belongs to the memory, not to the view,
|
|
102
|
+
* so assigning through a nested structure keeps the object alive with the
|
|
103
|
+
* outer one.
|
|
104
|
+
*
|
|
105
|
+
* @param {Uint8Array} targetBuf - Buffer holding the address
|
|
106
|
+
* @param {number} offset - Offset of the slot in `targetBuf`
|
|
107
|
+
* @param {*} value - Referenced object (or null to clear the slot)
|
|
108
|
+
*/
|
|
109
|
+
export function keepAlive(targetBuf, offset, value) {
|
|
110
|
+
const position = memoryPosition(targetBuf, offset);
|
|
111
|
+
const root = memoryDomains.get(targetBuf.buffer)?.root ?? targetBuf.buffer;
|
|
112
|
+
let kept = keptObjects.get(root);
|
|
113
|
+
if (value === null || (typeof value !== "object" && typeof value !== "function")) {
|
|
114
|
+
kept?.delete(position);
|
|
115
|
+
return;
|
|
116
|
+
}
|
|
117
|
+
if (kept === undefined) {
|
|
118
|
+
kept = new Map();
|
|
119
|
+
keptObjects.set(root, kept);
|
|
120
|
+
}
|
|
121
|
+
// A pointer wrapper can later be repointed; retain its current memory.
|
|
122
|
+
if (value._pointerType !== undefined) value = value._buffer ?? value._objects ?? value;
|
|
123
|
+
else if (value._isSimpleCDataInstance && value.constructor._isPointerValued) value = pointerOwner(value._buffer, 0);
|
|
124
|
+
kept.set(position, { owner: value, address: storedAddress(targetBuf, offset) });
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Object kept alive at `offset` of `buf` (see {@link keepAlive}).
|
|
129
|
+
*
|
|
130
|
+
* @param {Uint8Array} buf - Buffer
|
|
131
|
+
* @param {number} offset - Offset in `buf`
|
|
132
|
+
* @returns {*} The object, or undefined
|
|
133
|
+
*/
|
|
134
|
+
export function keptObject(buf, offset) {
|
|
135
|
+
const root = memoryDomains.get(buf.buffer)?.root ?? buf.buffer;
|
|
136
|
+
return keptObjects.get(root)?.get(memoryPosition(buf, offset))?.owner;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
export function clearKeepAlives(buf, offset, size) {
|
|
140
|
+
const root = memoryDomains.get(buf.buffer)?.root ?? buf.buffer;
|
|
141
|
+
const kept = keptObjects.get(root);
|
|
142
|
+
if (kept === undefined) return;
|
|
143
|
+
const start = BigInt(memoryPosition(buf, offset));
|
|
144
|
+
const end = start + BigInt(size);
|
|
145
|
+
for (const position of kept.keys()) {
|
|
146
|
+
if (position >= start && position < end) kept.delete(position);
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* Copy a struct/union instance into a nested field: the bytes (as Python
|
|
152
|
+
* does) plus the objects it keeps alive (strings, pointers, callbacks), so
|
|
153
|
+
* the addresses copied with them stay valid.
|
|
154
|
+
*
|
|
155
|
+
* @param {Buffer} buf - Target buffer
|
|
156
|
+
* @param {number} offset - Field offset
|
|
157
|
+
* @param {number} size - Field size
|
|
158
|
+
* @param {Object|Buffer} value - Instance with a `_buffer`, or source bytes
|
|
159
|
+
* @param {number} [sourceOffset=0] - Byte offset in the source
|
|
160
|
+
* @param {Function|Object} [type] - Layout used to retain references into leased memory
|
|
161
|
+
*/
|
|
162
|
+
export function copyInstance(buf, offset, size, value, sourceOffset = 0, type) {
|
|
163
|
+
const bytes = value._buffer ?? value;
|
|
164
|
+
const source = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
|
|
165
|
+
if (mirrorsActive) refresh(source, sourceOffset, size);
|
|
166
|
+
// Source and destination can overlap, including their reference tables.
|
|
167
|
+
const owners = snapshotOwners(source, sourceOffset, size, type);
|
|
168
|
+
source.copy(buf, offset, sourceOffset, sourceOffset + size);
|
|
169
|
+
clearKeepAlives(buf, offset, size);
|
|
170
|
+
for (const [relative, owner] of owners) keepAlive(buf, offset + relative, owner);
|
|
171
|
+
if (mirrorsActive) flush(buf, offset, size);
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
function snapshotOwners(source, sourceOffset, size, type) {
|
|
175
|
+
const start = memoryPosition(source, sourceOffset);
|
|
176
|
+
const sourceRoot = memoryDomains.get(source.buffer)?.root ?? source.buffer;
|
|
177
|
+
const sourceKept = keptObjects.get(sourceRoot);
|
|
178
|
+
const snapshot = new Map();
|
|
179
|
+
if (sourceKept !== undefined) {
|
|
180
|
+
for (const [position, reference] of sourceKept) {
|
|
181
|
+
if (position < start || position + BigInt(POINTER_SIZE) > start + BigInt(size)) continue;
|
|
182
|
+
const relative = Number(position - start);
|
|
183
|
+
if (reference.address === storedAddress(source, sourceOffset + relative)) {
|
|
184
|
+
snapshot.set(relative, reference.owner);
|
|
185
|
+
} else {
|
|
186
|
+
// A leased copy can retain the source buffer, so don't leave a stale owner on it.
|
|
187
|
+
sourceKept.delete(position);
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
if (type !== undefined && memoryOwners.has(source.buffer)) {
|
|
192
|
+
for (const [position, width] of pointerSlots(type)) {
|
|
193
|
+
if (snapshot.has(position) || position + width > size) continue;
|
|
194
|
+
for (let i = 0; i < width; i++) {
|
|
195
|
+
if (source[sourceOffset + position + i] !== 0) {
|
|
196
|
+
snapshot.set(position, source);
|
|
197
|
+
break;
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
return snapshot;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
// Keep the owners of the copied addresses even if a later adapter overwrites
|
|
206
|
+
// the original pointer fields. Plain bytes need no reference bookkeeping.
|
|
207
|
+
export function snapshotArgumentBytes(view, def) {
|
|
208
|
+
const size = def.size;
|
|
209
|
+
const copy = Buffer.alloc(size);
|
|
210
|
+
if (memoryOwners.has(view.buffer) || keptObjects.has(memoryDomains.get(view.buffer)?.root ?? view.buffer)) {
|
|
211
|
+
copyInstance(copy, 0, size, Buffer.from(view.buffer, view.byteOffset, size), 0, def);
|
|
212
|
+
} else {
|
|
213
|
+
const source = view instanceof Uint8Array && view.length === size ? view : Buffer.from(view.buffer, view.byteOffset, size);
|
|
214
|
+
if (mirrorsActive) refresh(source, 0, size);
|
|
215
|
+
copy.set(source);
|
|
216
|
+
}
|
|
217
|
+
return copy;
|
|
218
|
+
}
|
package/lib/memory/pointer.js
CHANGED
|
@@ -26,9 +26,14 @@
|
|
|
26
26
|
* ```
|
|
27
27
|
*/
|
|
28
28
|
|
|
29
|
-
import { byrefOwners
|
|
29
|
+
import { byrefOwners } from "../core/parameters.js";
|
|
30
|
+
import { keepAlive, keepFunctionOwner, keptObject, memoryDomain, pointerOwner, shareMemory } from "./ownership.js";
|
|
31
|
+
import { writePointerField } from "../structures/helpers/common.js";
|
|
32
|
+
import { isScalarSubclass, scalarView } from "../types/scalar-protocol.js";
|
|
30
33
|
import { flush, mirrorAddress, mirrorsActive, refresh } from "./mirror.js";
|
|
31
34
|
|
|
35
|
+
const kPointerMemory = Symbol("pointerMemory");
|
|
36
|
+
|
|
32
37
|
/**
|
|
33
38
|
* Gets the memory address of a buffer or pointer.
|
|
34
39
|
*
|