more

Author: cjihrig

doc/api/ffi.md

@@ -68,8 +68,8 @@ console.log(lib.symbols.abs(-42));
 
 Each symbol signature is an object with the following fields:
 
-* `parameters` {string\[]} Array of argument types.
-* `result` {string} Return type.
+* `parameters` {(string|Object)\[]} Array of argument types.
+* `result` {string|Object} Return type.
 
 Supported type names:
 
@@ -80,6 +80,11 @@ Supported type names:
 * `i64`, `u64`
 * `f32`, `f64`
 * `pointer`
+* `bool`
+* `buffer`
+* `function`
+* `usize`, `isize`
+* Struct descriptor objects: `{ struct: [/* field types */] }`
 
 ### `library.symbols`
 
@@ -112,6 +117,67 @@ PointerObjects are created by:
 * `library.getSymbol(name)` - Get function pointer from library
 * `UnsafePointer.offset(pointer, offset)` - Create offset pointer
 
+## Struct types
+
+Struct types are expressed inline as type descriptors instead of a class.
+
+* Struct descriptor: `{ struct: [fieldType1, fieldType2, ...] }`
+* Each field type can be any supported native type string or another struct
+  descriptor.
+
+### Using struct descriptors with `dlopen()`
+
+```mjs
+import { dlopen } from 'node:ffi';
+
+const Point = { struct: ['i32', 'i32'] };
+
+const lib = dlopen('./mylib.so', {
+  make_point: {
+    parameters: ['i32', 'i32'],
+    result: Point,
+  },
+  point_distance_squared: {
+    parameters: [Point, Point],
+    result: 'i32',
+  },
+});
+
+const p = lib.symbols.make_point(3, 4);
+// Struct return values are raw bytes.
+console.log(p instanceof Uint8Array); // true
+
+const q = new Uint8Array(8);
+new DataView(q.buffer).setInt32(0, 0, true);
+new DataView(q.buffer).setInt32(4, 0, true);
+
+console.log(lib.symbols.point_distance_squared(p, q)); // 25
+```
+
+```cjs
+const { dlopen } = require('node:ffi');
+
+const Point = { struct: ['i32', 'i32'] };
+
+const lib = dlopen('./mylib.so', {
+  make_point: {
+    parameters: ['i32', 'i32'],
+    result: Point,
+  },
+  point_distance_squared: {
+    parameters: [Point, Point],
+    result: 'i32',
+  },
+});
+
+const p = lib.symbols.make_point(3, 4);
+console.log(p instanceof Uint8Array); // true
+```
+
+For struct parameters, pass an `ArrayBuffer` or `ArrayBufferView`
+(`Uint8Array`, `DataView`, etc.) containing bytes that match the target native
+struct layout.
+
 ## Class: `UnsafeFnPointer`
 
 <!-- YAML
@@ -125,8 +191,8 @@ Create a callable wrapper around a function pointer.
 * `pointer` {PointerObject|bigint} A PointerObject or BigInt representing the
   function pointer address.
 * `definition` {Object} Function signature definition.
-  * `parameters` {string\[]} Parameter types.
-  * `result` {string} Return type.
+  * `parameters` {(string|Object)\[]} Parameter types.
+  * `result` {string|Object} Return type.
   * `nonblocking` {boolean} When `true`, function calls will run on a dedicated
     blocking thread and will return a Promise. **Default:** `false`.
 

node.gyp

@@ -460,8 +460,15 @@
       'src/node_webstorage.h',
     ],
     'node_ffi_sources': [
-      'src/node_ffi.cc',
-      'src/node_ffi.h',
+      'src/ffi/dynamic_library.cc',
+      'src/ffi/node_ffi.cc',
+      'src/ffi/node_ffi.h',
+      'src/ffi/pointer_object.cc',
+      'src/ffi/types.cc',
+      'src/ffi/unsafe_callback.cc',
+      'src/ffi/unsafe_fn_pointer.cc',
+      'src/ffi/unsafe_pointer.cc',
+      'src/ffi/unsafe_pointer_view.cc',
     ],
     'node_mksnapshot_exec': '<(PRODUCT_DIR)/<(EXECUTABLE_PREFIX)node_mksnapshot<(EXECUTABLE_SUFFIX)',
     'node_js2c_exec': '<(PRODUCT_DIR)/<(EXECUTABLE_PREFIX)node_js2c<(EXECUTABLE_SUFFIX)',

src/env_properties.h

@@ -21,6 +21,7 @@
   V(arrow_message_private_symbol, "node:arrowMessage")                         \
   V(contextify_context_private_symbol, "node:contextify:context")              \
   V(decorated_private_symbol, "node:decorated")                                \
+  V(ffi_pointer_address_private_symbol, "node:ffi:pointer_address")            \
   V(transfer_mode_private_symbol, "node:transfer_mode")                        \
   V(host_defined_option_symbol, "node:host_defined_option_symbol")             \
   V(js_transferable_wrapper_private_symbol, "node:js_transferable_wrapper")    \
@@ -404,6 +405,11 @@
   V(dns_ns_record_template, v8::DictionaryTemplate)                            \
   V(fd_constructor_template, v8::ObjectTemplate)                               \
   V(fdclose_constructor_template, v8::ObjectTemplate)                          \
+  V(ffi_dynamic_library_constructor_template, v8::FunctionTemplate)            \
+  V(ffi_unsafe_callback_constructor_template, v8::FunctionTemplate)            \
+  V(ffi_unsafe_fn_pointer_constructor_template, v8::FunctionTemplate)          \
+  V(ffi_unsafe_pointer_constructor_template, v8::FunctionTemplate)             \
+  V(ffi_unsafe_pointer_view_constructor_template, v8::FunctionTemplate)        \
   V(filehandlereadwrap_template, v8::ObjectTemplate)                           \
   V(free_list_statistics_template, v8::DictionaryTemplate)                     \
   V(fsreqpromise_constructor_template, v8::ObjectTemplate)                     \