node-ctypes 2.2.0 → 2.3.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/lib/core/types.js CHANGED
@@ -14,19 +14,90 @@
14
14
  *
15
15
  * - SimpleCData primitives (c_int32, ecc.)
16
16
  * - POINTER
17
- * - Bitfield: consecutivi nella stessa storage-cell vengono raggruppati
18
- * in un singolo field del base type (layout C-ABI compatibile; i
19
- * reader/writer bitfield individuali leggono/scrivono a offset).
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.
20
21
  * - Array: sia `array(SimpleCData, N)` sia `array(Structure/Union, N)`;
21
22
  * per il secondo caso il native ArrayType è costruito lazy qui.
22
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_`).
23
27
  */
24
28
 
29
+ // ArrayType nativi costruiti per gli array di Structure/Union (gli array JS
30
+ // espongono `_native` in sola lettura).
31
+ const nativeArrayTypes = new WeakMap();
32
+
33
+ // ArrayType nativi uint8[n] per i byte emessi come tali (vedi sotto).
34
+ const byteArrayTypes = new Map();
35
+
36
+ function byteRun(st, native, offset, length) {
37
+ if (length <= 0) return;
38
+ if (length === 1) {
39
+ st.addField(`__byte@${offset}`, native.CType.UINT8);
40
+ return;
41
+ }
42
+ let arrayType = byteArrayTypes.get(length);
43
+ if (arrayType === undefined) {
44
+ arrayType = new native.ArrayType(native.CType.UINT8, length);
45
+ byteArrayTypes.set(length, arrayType);
46
+ }
47
+ st.addField(`__bytes@${offset}`, arrayType);
48
+ }
49
+
50
+ const roundUp = (n, a) => Math.ceil(n / a) * a;
51
+
52
+ // Byte toccati da un bitfield (dentro la sua unità di `baseSize` byte).
53
+ function bitFieldBytes(f) {
54
+ const first = Math.floor(f.bitOffset / 8);
55
+ const last = Math.floor((f.bitOffset + f.bitSize - 1) / 8);
56
+ const bytes = [];
57
+ for (let b = first; b <= last; b++) {
58
+ bytes.push(f.offset + (f.swapped ? f.baseSize - 1 - b : b));
59
+ }
60
+ return bytes;
61
+ }
62
+
63
+ const nestedDefOf = (f) => {
64
+ if (f.isNested) return typeof f.type === "function" ? f.type._structDef || f.type._buildStruct?.() : f.type;
65
+ const element = f.isArray ? f.type?.elementType : undefined;
66
+ if (typeof element === "function" && typeof element._buildStruct === "function") return element._structDef || element._buildStruct();
67
+ return undefined;
68
+ };
69
+
70
+ // Campi (anche di struct annidate) a un offset non multiplo del loro
71
+ // allineamento C, come con `_pack_`: l'ABI x86-64 System V passa queste struct
72
+ // in memoria (vedi StructInfo::SetMemoryClass).
73
+ const unalignedDefs = new WeakMap();
74
+ function hasUnalignedFields(def) {
75
+ let result = unalignedDefs.get(def);
76
+ if (result === undefined) {
77
+ result = def.fields.some((f) => {
78
+ if (f.isBitField) return false;
79
+ if (!def.isUnion && f.offset % (f.naturalAlignment ?? f.alignment) !== 0) return true;
80
+ const nested = nestedDefOf(f);
81
+ return nested !== undefined && hasUnalignedFields(nested);
82
+ });
83
+ unalignedDefs.set(def, result);
84
+ }
85
+ return result;
86
+ }
87
+
25
88
  /**
26
89
  * Costruisce (o recupera cached) un native `StructType` corrispondente a un
27
90
  * structDef/unionDef. Cacheato su `def._nativeStructType` per evitare
28
91
  * ricostruzioni multiple sulla stessa def.
29
92
  *
93
+ * La struct nativa ha gli offset, la dimensione e l'allineamento del layout
94
+ * JS (layout.js, `_pack_`, `_align_`, bitfield). Un campo resta del suo tipo
95
+ * (che conta per la classificazione dell'ABI: float/double vanno nei registri
96
+ * SSE) quando nella struct nativa cade allo stesso offset: offset allineato al
97
+ * suo allineamento C, non superiore a quello della struct. Altrimenti (campi
98
+ * disallineati da `_pack_`, byte dei bitfield) i suoi byte diventano uint8. Il
99
+ * padding non è emesso, se non prima di byte da collocare all'offset giusto.
100
+ *
30
101
  * @param {Object} def - structDef o unionDef (output di `struct()`/`union()`
31
102
  * o `_structDef` di una Structure class).
32
103
  * @param {Object} native - modulo native (`require('ctypes.node')`).
@@ -35,109 +106,134 @@
35
106
  */
36
107
  function _buildNativeStructType(def, native) {
37
108
  if (def._nativeStructType) return def._nativeStructType;
38
- const st = new native.StructType({ union: !!def.isUnion });
39
-
40
- // Gestione bitfield per layout-compatible con libffi:
41
- // libffi non ha `ffi_type` per bitfield. Replichiamo il layout C
42
- // raggruppando i bitfield consecutivi che condividono lo stesso
43
- // storage-cell (identificato dal `baseType` + `offset` di partenza)
44
- // in un singolo field del base type (c_uint32, c_uint64, ecc.).
45
- //
46
- // Esempio C:
47
- // struct { int a:3; int b:5; int c:8; }; // tutti nello stesso int32
48
- // Layout:
49
- // native StructType aggiunge 1 field di tipo c_int32 con nome sintetico
50
- // (es. "__bitfield@0"). I reader/writer bitfield individuali restano
51
- // sulla def JS e continuano a funzionare perché leggono/scrivono a
52
- // offset corretti dentro il buffer della struct.
53
- //
54
- // Quando la struct è passata/ricevuta by-value, il layout di memoria è
55
- // identico a quello C; i bitfield values viaggiano dentro gli integer
56
- // di base e l'utente li legge/scrive normalmente via i field accessor.
57
- const emittedBitfieldCells = new Set();
58
- for (const f of def.fields) {
59
- if (f.isBitField) {
60
- const cellKey = `${f.offset}:${f.baseSize}`;
61
- if (emittedBitfieldCells.has(cellKey)) continue; // già emesso da un bitfield precedente nella stessa cell
62
- emittedBitfieldCells.add(cellKey);
63
- // Determina il CType del base type (es. c_uint32 → CType.UINT32).
64
- // f.type è la SimpleCData class del base.
65
- if (!f.type || typeof f.type._type !== "number") {
66
- throw new Error(`Bitfield '${f.name}': base type senza _type numerico`);
67
- }
68
- // Usa un nome sintetico per la cell (non accessibile via field map —
69
- // i bitfield individuali conservano i loro nomi e accedono al buffer
70
- // direttamente via fieldReaders/fieldWriters precompilati).
71
- const cellName = `__bitfield@${f.offset}`;
72
- st.addField(cellName, f.type._type);
73
- continue;
109
+ const st = new native.StructType({ union: !!def.isUnion, alignment: def.alignment, memoryClass: hasUnalignedFields(def) });
110
+ const fits = (alignment, offset) => alignment <= def.alignment && offset % alignment === 0;
111
+
112
+ // La classe base è il primo membro della struct (i suoi campi sono i primi
113
+ // di def.fields, agli stessi offset).
114
+ let fields = def.fields;
115
+ let position = 0;
116
+ if (def.base) {
117
+ if (fits(def.base.alignment, 0)) st.addField("__base__", _buildNativeStructType(def.base, native));
118
+ else byteRun(st, native, 0, def.base.size);
119
+ fields = def.fields.slice(def.base.fields.length);
120
+ position = def.isUnion ? 0 : def.base.size;
121
+ }
122
+
123
+ if (def.isUnion) {
124
+ for (const f of fields) {
125
+ const size = f.isBitField ? f.baseSize : f.size;
126
+ const alignment = f.naturalAlignment ?? f.alignment;
127
+ if (!fits(alignment, 0)) byteRun(st, native, 0, size);
128
+ // Un bitfield occupa il proprio tipo base all'offset 0.
129
+ else if (f.isBitField) st.addField(`__bitfield_${f.name}`, bitFieldBaseType(f));
130
+ else addNativeField(st, f, native);
74
131
  }
75
- if (f.isArray) {
76
- // Caso 1: `_native` è già un native ArrayType instance (array di
77
- // primitives o di Structure native). Lo passiamo direttamente al
78
- // StructType.addField.
79
- const native_is_array_type =
80
- f.type && f.type._native &&
81
- typeof f.type._native.getSize === "function" &&
82
- f.type._native.constructor?.name === "ArrayType";
83
- if (native_is_array_type) {
84
- st.addField(f.name, f.type._native, f.isAnonymous ? { anonymous: true } : undefined);
85
- continue;
86
- }
87
- // Caso 2: lo shim JS ha Structure/Union come elementType. Costruiamo
88
- // qui (lazy) un native ArrayType col native StructType dell'element.
89
- // Questo abilita struct-by-value con array-of-struct fields.
90
- const elementType = f.type?.elementType;
91
- const count = f.type?.length;
92
- if (elementType && typeof count === "number" &&
93
- typeof elementType === "function" &&
94
- (typeof elementType._buildStruct === "function" ||
95
- typeof elementType._buildUnion === "function")) {
96
- const elemDef = elementType._structDef || elementType._unionDef ||
97
- elementType._buildStruct?.() || elementType._buildUnion?.();
98
- const elemNative = _buildNativeStructType(elemDef, native);
99
- const arrNative = new native.ArrayType(elemNative, count);
100
- st.addField(f.name, arrNative, f.isAnonymous ? { anonymous: true } : undefined);
101
- // Promuovi il native sullo shim per evitare ricostruzioni future.
102
- f.type._native = arrNative;
103
- continue;
104
- }
105
- throw new Error(
106
- `Field '${f.name}': array-in-struct-by-value non riconosciuto. ` +
107
- `Tipi supportati: array(SimpleCData, N), array(Structure/Union subclass, N). ` +
108
- `Alternativa: passa la struct per puntatore.`,
109
- );
132
+ } else {
133
+ // Campi e byte dei bitfield in ordine di offset.
134
+ const items = [];
135
+ const bitBytes = new Set();
136
+ for (const f of fields) {
137
+ if (f.isBitField) bitFieldBytes(f).forEach((b) => bitBytes.add(b));
138
+ else if (f.size > 0) items.push({ offset: f.offset, size: f.size, field: f });
110
139
  }
111
- if (f.isNested) {
112
- // f.type è un structDef/unionDef (quando dichiarato via struct/union)
113
- // o una Structure/Union class (quando dichiarato con class extends).
114
- let nestedDef = f.type;
115
- if (typeof f.type === "function") {
116
- nestedDef = f.type._structDef || f.type._unionDef || f.type._buildStruct?.() || f.type._buildUnion?.();
117
- }
118
- if (!nestedDef || !Array.isArray(nestedDef.fields)) {
119
- throw new Error(`Field '${f.name}': nested type non riconosciuto`);
140
+ for (const b of bitBytes) items.push({ offset: b, size: 1, field: null });
141
+ items.sort((a, b) => a.offset - b.offset);
142
+
143
+ let bytesFrom = -1; // inizio della sequenza di byte in corso
144
+ const flushBytes = () => {
145
+ if (bytesFrom >= 0) byteRun(st, native, bytesFrom, position - bytesFrom);
146
+ bytesFrom = -1;
147
+ };
148
+ const addBytes = (offset, size) => {
149
+ if (bytesFrom < 0) bytesFrom = position;
150
+ position = offset + size;
151
+ };
152
+
153
+ for (const { offset, size, field } of items) {
154
+ if (offset < position) continue; // byte già coperto
155
+ const alignment = field ? (field.naturalAlignment ?? field.alignment) : 1;
156
+ if (field && fits(alignment, offset)) {
157
+ // Il padding naturale prima del campo resta padding; un vuoto più
158
+ // grande (es. `_align_` di una struct annidata) diventa byte.
159
+ if (roundUp(position, alignment) !== offset) addBytes(offset, 0);
160
+ flushBytes();
161
+ addNativeField(st, field, native);
162
+ position = offset + size;
163
+ } else {
164
+ addBytes(offset, size);
120
165
  }
121
- const nestedNative = _buildNativeStructType(nestedDef, native);
122
- st.addField(f.name, nestedNative, f.isAnonymous ? { anonymous: true } : undefined);
123
- continue;
124
- }
125
- if (f.isPointer) {
126
- st.addField(f.name, native.CType.POINTER);
127
- continue;
128
- }
129
- // SimpleCData class: usa il suo _type numerico.
130
- if (f.type && typeof f.type === "function" && f.type._isSimpleCData) {
131
- st.addField(f.name, f.type._type);
132
- continue;
133
166
  }
134
- throw new Error(`Field '${f.name}': tipo non riconosciuto durante _buildNativeStructType`);
167
+ flushBytes();
168
+ // Coda oltre l'arrotondamento all'allineamento (non accade con i layout
169
+ // di layout.js, ma la dimensione deve comunque coincidere).
170
+ if (roundUp(position, def.alignment) < def.size) byteRun(st, native, position, def.size - position);
135
171
  }
136
172
 
173
+ const size = st.getSize();
174
+ if (size !== def.size || st.getAlignment() !== def.alignment) {
175
+ throw new Error(`Native layout of the structure (size ${size}, alignment ${st.getAlignment()}) differs from its definition (size ${def.size}, alignment ${def.alignment})`);
176
+ }
137
177
  def._nativeStructType = st;
138
178
  return st;
139
179
  }
140
180
 
181
+ function bitFieldBaseType(f) {
182
+ if (!f.type || typeof f.type._type !== "number") {
183
+ throw new Error(`Bitfield '${f.name}': base type senza _type numerico`);
184
+ }
185
+ return f.type._type;
186
+ }
187
+
188
+ function addNativeField(st, f, native) {
189
+ const options = f.isAnonymous ? { anonymous: true } : undefined;
190
+ if (f.isArray) {
191
+ // Array di primitive (o di struct native): `_native` è già un ArrayType.
192
+ const own = f.type?._native;
193
+ if (own && typeof own.getSize === "function" && own.constructor?.name === "ArrayType") {
194
+ st.addField(f.name, own, options);
195
+ return;
196
+ }
197
+ // Array di Structure/Union: ArrayType nativo costruito qui (una volta per tipo).
198
+ const elementType = f.type?.elementType;
199
+ const count = f.type?.length;
200
+ const elemDef = typeof elementType === "function" && typeof elementType._buildStruct === "function" ? elementType._structDef || elementType._buildStruct() : elementType?._isStructType === true ? elementType : undefined;
201
+ if (elemDef !== undefined && typeof count === "number") {
202
+ let arrNative = nativeArrayTypes.get(f.type);
203
+ if (arrNative === undefined) {
204
+ arrNative = new native.ArrayType(_buildNativeStructType(elemDef, native), count);
205
+ nativeArrayTypes.set(f.type, arrNative);
206
+ }
207
+ st.addField(f.name, arrNative, options);
208
+ return;
209
+ }
210
+ 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.`);
211
+ }
212
+ if (f.isNested) {
213
+ // f.type è un structDef/unionDef (quando dichiarato via struct/union)
214
+ // o una Structure/Union class (quando dichiarato con class extends).
215
+ let nestedDef = f.type;
216
+ if (typeof f.type === "function") {
217
+ nestedDef = f.type._structDef || f.type._buildStruct?.();
218
+ }
219
+ if (!nestedDef || !Array.isArray(nestedDef.fields)) {
220
+ throw new Error(`Field '${f.name}': nested type non riconosciuto`);
221
+ }
222
+ st.addField(f.name, _buildNativeStructType(nestedDef, native), options);
223
+ return;
224
+ }
225
+ if (f.isPointer) {
226
+ st.addField(f.name, native.CType.POINTER);
227
+ return;
228
+ }
229
+ // SimpleCData class: usa il suo _type numerico.
230
+ if (f.type && typeof f.type === "function" && f.type._isSimpleCData) {
231
+ st.addField(f.name, f.type._type);
232
+ return;
233
+ }
234
+ throw new Error(`Field '${f.name}': tipo non riconosciuto durante _buildNativeStructType`);
235
+ }
236
+
141
237
  /**
142
238
  * Normalizza un tipo singolo nel formato atteso dal native FFIFunction.
143
239
  *
@@ -204,9 +300,11 @@ export function _toNativeReturnType(type, native) {
204
300
  }
205
301
 
206
302
  /**
207
- * Normalizza un array di tipi (batch). Non-array → pass-through.
303
+ * Normalizza un array di tipi di argomento (batch). Non-array → pass-through.
304
+ * Un tipo array come argomento è un puntatore, come in C e Python
305
+ * (`argtypes = [c_int * 4]` passa l'indirizzo dell'array).
208
306
  */
209
307
  export function _toNativeTypes(types, native) {
210
308
  if (!Array.isArray(types)) return types;
211
- return types.map((type) => _toNativeType(type, native));
309
+ return types.map((type) => (type && (typeof type === "object" || typeof type === "function") && type._isArrayType === true ? native.CType.POINTER : _toNativeType(type, native)));
212
310
  }