koffi 2.0.0 → 2.1.0-beta.2

package/test/sync.js

@@ -15,7 +15,6 @@
 
 const koffi = require('./build/koffi.node');
 const assert = require('assert');
-const path = require('path');
 
 const Pack1 = koffi.struct('Pack1', {
     a: 'int'
@@ -62,7 +61,7 @@ const IntFloat = koffi.struct('IntFloat', {
 
 const BFG = koffi.struct('BFG', {
     a: 'int8_t',
-    b: 'int64_t',
+    b: [16, 'int64_t'],
     c: 'char',
     d: 'const char *',
     e: 'short',
@@ -128,7 +127,7 @@ async function main() {
 }
 
 async function test() {
-    let lib_filename = path.dirname(__filename) + '/build/misc' + koffi.extension;
+    let lib_filename = __dirname + '/build/misc' + koffi.extension;
     let lib = koffi.load(lib_filename);
 
     const GetMinusOne1 = lib.func('int8_t GetMinusOne1(void)');
@@ -160,6 +159,7 @@ async function test() {
     const ConcatenateToStr8 = lib.func('ConcatenateToStr8', 'str', [...Array(8).fill('int64_t'), koffi.struct('IJK8', {i: 'int64_t', j: 'int64_t', k: 'int64_t'}), 'int64_t']);
     const MakeBFG = lib.func('BFG __stdcall MakeBFG(_Out_ BFG *p, int x, double y, const char *str)');
     const MakePackedBFG = lib.func('AliasBFG __fastcall MakePackedBFG(int x, double y, _Out_ PackedBFG *p, const char *str)');
+    const MakePolymorphBFG = lib.func('void MakePolymorphBFG(int type, int x, double y, const char *str, _Out_ void *p)');
     const ReturnBigString = process.platform == 'win32' ?
                             lib.stdcall(1, koffi.disposable('str', koffi.free), ['str']) :
                             lib.func('const char * __stdcall ReturnBigString(const char *str)');
@@ -186,6 +186,7 @@ async function test() {
     const MultiplyIntegers = lib.func('void MultiplyIntegers(int multiplier, _Inout_ int *values, int len)');
     const ThroughStr = lib.func('str ThroughStr(StrStruct s)');
     const ThroughStr16 = lib.func('str16 ThroughStr16(StrStruct s)');
+    const ReverseBytes = lib.func('void ReverseBytes(_Inout_ void *array, int len)');
 
     // Simple signed value returns
     assert.equal(GetMinusOne1(), -1);
@@ -295,6 +296,17 @@ async function test() {
         assert.deepEqual(out, bfg);
     }
 
+    // Polymorph pointer
+    {
+        let bfg = {};
+
+        MakePolymorphBFG(0, 2, 7, 'boo', koffi.as(bfg, 'BFG *'));
+        assert.deepEqual(bfg, { a: 2, b: 4, c: -25, d: 'X/boo/X', e: 54, inner: { f: 14, g: 5 }});
+
+        MakePolymorphBFG(1, 2, 7, 'bies', koffi.as(bfg, 'PackedBFG *'));
+        assert.deepEqual(bfg, { a: 2, b: 4, c: -25, d: 'X/bies/X', e: 54, inner: { f: 14, g: 5 }});
+    }
+
     // Big string
     {
         let str = 'fooBAR!'.repeat(1024 * 1024);
@@ -372,10 +384,12 @@ async function test() {
         let out1 = Array(10);
         let out2 = new Int32Array(10);
         let mult = -3;
+        let ret = null;
 
         FillRange(2, 7, out1, out1.length);
-        FillRange(13, 3, out2, out2.length);
+        ret = FillRange(13, 3, out2, out2.length);
 
+        assert.strictEqual(ret, undefined);
         assert.deepEqual(out1, [2, 9, 16, 23, 30, 37, 44, 51, 58, 65]);
         assert.deepEqual(out2, new Int32Array([13, 16, 19, 22, 25, 28, 31, 34, 37, 40]));
 
@@ -392,4 +406,16 @@ async function test() {
         assert.equal(ThroughStr16({ str: null, str16: 'World!' }), 'World!');
         assert.equal(ThroughStr16({ str: 'World!', str16: null }), null);
     }
+
+    // Transparent typed arrays for void pointers
+    {
+        let arr8 = Uint8Array.from([1, 2, 3, 4, 5]);
+        let arr16 = Int16Array.from([1, 2, 3, 4, 5]);
+
+        ReverseBytes(arr8, arr8.byteLength);
+        assert.deepEqual(arr8, Uint8Array.from([5, 4, 3, 2, 1]));
+
+        ReverseBytes(arr16, arr16.byteLength);
+        assert.deepEqual(arr16, Int16Array.from([1280, 1024, 768, 512, 256]));
+    }
 }

package/doc/dist/html/.buildinfo

@@ -1,4 +0,0 @@
-# Sphinx build info version 1
-# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 3958eced2fda3c6c0751ec1a88d416ca
-tags: 645f666f9bcd5a90fca523b33c5a78b7

package/doc/dist/html/_sources/benchmarks.md.txt

@@ -1,137 +0,0 @@
-# Benchmarks
-
-## Overview
-
-Here is a quick overview of the execution time of Koffi calls on three benchmarks, where it is compared to a theoretical ideal FFI implementation (approximated with pre-compiled static N-API glue code):
-
-- The first benchmark is based on `rand()` calls
-- The second benchmark is based on `atoi()` calls
-- The third benchmark is based on [Raylib](https://www.raylib.com/)
-
-<table style="margin: 0 auto;">
-    <tr>
-        <td><a href="static/perf_linux_20220628.png" target="_blank"><img src="static/perf_linux_20220628.png" alt="Linux x86_64 performance" style="width: 350px;"/></a></td>
-        <td><a href="static/perf_windows_20220628.png" target="_blank"><img src="static/perf_windows_20220628.png" alt="Windows x86_64 performance" style="width: 350px;"/></a></td>
-    </tr>
-</table>
-
-These results are detailed and explained below, and compared to node-ffi/node-ffi-napi.
-
-## Linux x86_64
-
-The results presented below were measured on my x86_64 Linux machine (Intel® Core™ i5-4460).
-
-### rand results
-
-This test is based around repeated calls to a simple standard C function atoi, and has three implementations:
-
-- the first one is the reference, it calls atoi through an N-API module, and is close to the theoretical limit of a perfect (no overhead) Node.js > C FFI implementation (pre-compiled static glue code)
-- the second one calls atoi through Koffi
-- the third one uses the official Node.js FFI implementation, node-ffi-napi
-
-Benchmark     | Iteration time | Relative performance | Overhead
-------------- | -------------- | -------------------- | --------
-rand_napi     | 644 ns         | x1.00                | (ref)
-rand_koffi    | 950 ns         | x0.68                | +48%
-rand_node_ffi | 30350 ns       | x0.02                | +4613%
-
-Because rand is a pretty small function, the FFI overhead is clearly visible.
-
-### atoi results
-
-This test is similar to the rand one, but it is based on atoi, which takes a string parameter. Javascript (V8) to C string conversion is relatively slow and heavy.
-
-Benchmark     | Iteration time | Relative performance | Overhead
-------------- | -------------- | -------------------- | --------
-atoi_napi     | 1104 ns        | x1.00                | (ref)
-atoi_koffi    | 1778 ns        | x0.62                | +61%
-atoi_node_ffi | 125300 ns      | x0.009               | +11250%
-
-Because atoi is a pretty small function, the FFI overhead is clearly visible.
-
-### Raylib results
-
-This benchmark uses the CPU-based image drawing functions in Raylib. The calls are much heavier than in the atoi benchmark, thus the FFI overhead is reduced. In this implementation, Koffi is compared to:
-
-- Baseline: Full C++ version of the code (no JS)
-- [node-raylib](https://github.com/RobLoach/node-raylib): This is a native wrapper implemented with N-API
-
-Benchmark          | Iteration time | Relative performance | Overhead
------------------- | -------------- | -------------------- | --------
-raylib_cc          | 215.7 µs       | x1.20                | -17%
-raylib_node_raylib | 258.9 µs       | x1.00                | (ref)
-raylib_koffi       | 311.6 µs       | x0.83                | +20%
-raylib_node_ffi    | 928.4 µs       | x0.28                | +259%
-
-## Windows x86_64
-
-The results presented below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460).
-
-### rand results
-
-This test is based around repeated calls to a simple standard C function atoi, and has three implementations:
-
-- the first one is the reference, it calls atoi through an N-API module, and is close to the theoretical limit of a perfect (no overhead) Node.js > C FFI implementation (pre-compiled static glue code)
-- the second one calls atoi through Koffi
-- the third one uses the official Node.js FFI implementation, node-ffi-napi
-
-Benchmark     | Iteration time | Relative performance | Overhead
-------------- | -------------- | -------------------- | --------
-rand_napi     | 965 ns         | x1.00                | (ref)
-rand_koffi    | 1248 ns        | x0.77                | +29%
-rand_node_ffi | 41500 ns       | x0.02                | +4203%
-
-Because rand is a pretty small function, the FFI overhead is clearly visible.
-
-### atoi results
-
-This test is similar to the rand one, but it is based on atoi, which takes a string parameter. Javascript (V8) to C string conversion is relatively slow and heavy.
-
-The results below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460):
-
-Benchmark     | Iteration time | Relative performance | Overhead
-------------- | -------------- | -------------------- | --------
-atoi_napi     | 1393 ns        | x1.00                | (ref)
-atoi_koffi    | 2246 ns        | x0.62                | +61%
-atoi_node_ffi | 157550 ns      | x0.009               | +11210%
-
-Because atoi is a pretty small function, the FFI overhead is clearly visible.
-
-### Raylib results
-
-This benchmark uses the CPU-based image drawing functions in Raylib. The calls are much heavier than in the atoi benchmark, thus the FFI overhead is reduced. In this implementation, Koffi is compared to:
-
-- [node-raylib](https://github.com/RobLoach/node-raylib) (baseline): This is a native wrapper implemented with N-API
-- raylib_cc: C++ implementation of the benchmark, without any Javascript
-
-Benchmark          | Iteration time | Relative performance | Overhead
------------------- | -------------- | -------------------- | --------
-raylib_cc          | 211.8 µs       | x1.25                | -20%
-raylib_node_raylib | 264.4 µs       | x1.00                | (ref)
-raylib_koffi       | 318.9 µs       | x0.83                | +21%
-raylib_node_ffi    | 1146.2 µs      | x0.23                | +334%
-
-Please note that in order to get fair numbers for raylib_node_raylib, it was recompiled with clang-cl before running the benchmark with the following commands:
-
-```batch
-cd node_modules\raylib
-rmdir /S /Q bin build
-npx cmake-js compile -t ClangCL
-```
-
-## Running benchmarks
-
-Open a console, go to `koffi/benchmark` and run `../../cnoke/cnoke.js` (or `node ..\..\cnoke\cnoke.js` on Windows) before doing anything else.
-
-Please note that all benchmark results are made with Clang-built binaries.
-
-```sh
-cd koffi/benchmark
-node ../../cnoke/cnoke.js --prefer-clang
-```
-
-Once everything is built and ready, run:
-
-```sh
-node benchmark.js
-```

package/doc/dist/html/_sources/changes.md.txt

@@ -1,157 +0,0 @@
-```{include} ../ChangeLog.md
-```
-
-## Migration guide
-
-### Koffi 1.x to 2.x
-
-The API was changed in 2.x in a few ways, in order to reduce some excessively "magic" behavior and reduce the syntax differences between C and the C-like prototypes.
-
-You may need to change your code if you use:
-
-- Callback functions
-- Opaque handles
-- `koffi.introspect()`
-
-#### Callback types
-
-In Koffi 1.x, callbacks were defined in a way that made them usable directly as parameter and return types, obscuring the underlying pointer. Now, you must use them through a pointer: `void CallIt(CallbackType func)` in Koffi 1.x becomes `void CallIt(CallbackType *func)` in version 2.0 and newer.
-
-Given the following C code:
-
-```c
-#include <string.h>
-
-int TransferToJS(const char *name, int age, int (*cb)(const char *str, int age))
-{
-    char buf[64];
-    snprintf(buf, sizeof(buf), "Hello %s!", str);
-    return cb(buf, age);
-}
-```
-
-The two versions below illustrate the API difference between Koffi 1.x and Koffi 2.x:
-
-```js
-// Koffi 1.x
-
-const TransferCallback = koffi.callback('int TransferCallback(const char *str, int age)');
-
-const TransferToJS = lib.func('TransferToJS', 'int', ['str', 'int', TransferCallback]);
-// Equivalent to: const TransferToJS = lib.func('int TransferToJS(str s, int x, TransferCallback cb)');
-
-let ret = TransferToJS('Niels', 27, (str, age) => {
-    console.log(str);
-    console.log('Your age is:', age);
-    return 42;
-});
-console.log(ret);
-```
-
-```js
-// Koffi 2.x
-
-const TransferCallback = koffi.callback('int TransferCallback(const char *str, int age)');
-
-const TransferToJS = lib.func('TransferToJS', 'int', ['str', 'int', koffi.pointer(TransferCallback)]);
-// Equivalent to: const TransferToJS = lib.func('int TransferToJS(str s, int x, TransferCallback *cb)');
-
-let ret = TransferToJS('Niels', 27, (str, age) => {
-    console.log(str);
-    console.log('Your age is:', age);
-    return 42;
-});
-console.log(ret);
-```
-
-Koffi 1.x only supported [transient callbacks](functions.md#javascript-callbacks), you must use Koffi 2.x for registered callbacks.
-
-#### Opaque handles
-
-In Koffi 1.x, opaque handles were defined in a way that made them usable directly as parameter and return types, obscuring the underlying pointer. Now, you must use them through a pointer, and use an array for output parameters.
-
-For functions that return handles or pass them by parameter:
-
-```js
-// Koffi 1.x
-
-const FILE = koffi.handle('FILE');
-const fopen = lib.func('FILE fopen(const char *path, const char *mode)');
-const fclose = lib.func('int fclose(FILE stream)');
-
-let fp = fopen('touch', 'wb');
-if (!fp)
-    throw new Error('Failed to open file');
-fclose(fp);
-```
-
-```js
-// Koffi 2.x
-
-const FILE = koffi.handle('FILE');
-const fopen = lib.func('FILE *fopen(const char *path, const char *mode)');
-const fclose = lib.func('int fclose(FILE *stream)');
-
-let fp = fopen('touch', 'wb');
-if (!fp)
-    throw new Error('Failed to open file');
-fclose(fp);
-```
-
-For functions that set opaque handles through output parameters (such as `sqlite3_open_v2`), you must now use a single element array as shown below:
-
-```js
-// Koffi 1.x
-
-const sqlite3_db = koffi.handle('sqlite3_db');
-
-const sqlite3_open_v2 = lib.func('sqlite3_open_v2', 'int', ['str', koffi.out(sqlite3_db), 'int', 'str']);
-const sqlite3_close_v2 = lib.func('sqlite3_close_v2', 'int', [sqlite3_db]);
-
-const SQLITE_OPEN_READWRITE = 0x2;
-const SQLITE_OPEN_CREATE = 0x4;
-
-let db = {};
-
-if (sqlite3_open_v2(':memory:', db, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, null) != 0)
-    throw new Error('Failed to open database');
-
-sqlite3_close_v2(db);
-```
-
-```js
-// Koffi 2.x
-
-const sqlite3_db = koffi.handle('sqlite3_db');
-
-const sqlite3_open_v2 = lib.func('sqlite3_open_v2', 'int', ['str', koffi.out(koffi.pointer(sqlite3_db, 2)), 'int', 'str']);
-const sqlite3_close_v2 = lib.func('sqlite3_close_v2', 'int', [koffi.pointer(sqlite3_db)]);
-
-const SQLITE_OPEN_READWRITE = 0x2;
-const SQLITE_OPEN_CREATE = 0x4;
-
-let db = null;
-
-let ptr = [null];
-if (sqlite3_open_v2(':memory:', ptr, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, null) != 0)
-    throw new Error('Failed to open database');
-db = ptr[0];
-
-sqlite3_close_v2(db);
-```
-
-#### koffi.introspect()
-
-In Koffi 1.x, `koffi.introspect()` would only work with struct types, and return the object passed to `koffi.struct()` to initialize the type. Now this function works with all types.
-
-You can still get the list of struct members:
-
-```js
-const StructType = koffi.struct('StructType', { dummy: 'int' });
-
-// Koffi 1.x
-let members = koffi.introspect(StructType);
-
-// Koffi 2.x
-let members = koffi.introspect(StructType).members;
-```

package/doc/dist/html/_sources/contribute.md.txt

@@ -1,127 +0,0 @@
-# Contributing
-
-## Bugs and feature requests
-
-Use the official repository (named Luigi, because this is a monorepo containing multiple projects) for bugs, ideas and features requests.
-
-Go here: https://github.com/Koromix/luigi/
-
-## Build from source
-
-We provide prebuilt binaries, packaged in the NPM archive, so in most cases it should be as simple as `npm install koffi`. If you want to hack Koffi or use a specific platform, follow the instructions below.
-
-Start by cloning the repository with [Git](https://git-scm.com/):
-
-```sh
-git clone https://github.com/Koromix/luigi
-cd luigi/koffi
-```
-
-As said before, this is a monorepository containg multiple projects, hence the name.
-
-### Windows
-
-First, make sure the following dependencies are met:
-
-- The "Desktop development with C++" workload from [Visual Studio 2022 or 2019](https://visualstudio.microsoft.com/downloads/) or the "C++ build tools" workload from the [Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022), with the default optional components.
-- [CMake meta build system](https://cmake.org/)
-- [Node.js](https://nodejs.org/) 12 or later
-
-Once this is done, run this command _from the test or the benchmark directory_ (depending on what you want to build):
-
-```sh
-cd koffi/test # or cd koffi/benchmark
-node ../../cnoke/cnoke.js
-```
-
-### Other platforms
-
-Make sure the following dependencies are met:
-
-- `gcc` and `g++` >= 8.3 or newer
-- GNU Make 3.81 or newer
-- [CMake meta build system](https://cmake.org/)
-- [Node.js](https://nodejs.org/) 12 or later
-
-Once this is done, run this command _from the test or the benchmark directory_ (depending on what you want to build):
-
-```sh
-cd koffi/test # or cd koffi/benchmark
-node ../../cnoke/cnoke.js
-```
-
-## Running tests
-
-Koffi is tested on multiple architectures using emulated (accelerated when possible) QEMU machines. First, you need to install qemu packages, such as `qemu-system` (or even `qemu-system-gui`) on Ubuntu.
-
-These machines are not included directly in this repository (for license and size reasons), but they are available here: https://koromix.dev/files/machines/
-
-For example, if you want to run the tests on Debian ARM64, run the following commands:
-
-```sh
-cd luigi/koffi/qemu/
-wget -q -O- https://koromix.dev/files/machines/qemu_debian_arm64.tar.zst | zstd -d | tar xv
-sha256sum -c --ignore-missing registry/sha256sum.txt
-```
-
-Note that the machine disk content may change each time the machine runs, so the checksum test will fail once a machine has been used at least once.
-
-And now you can run the tests with:
-
-```sh
-node qemu.js test # Several options are available, use --help
-```
-
-And be patient, this can be pretty slow for emulated machines. The Linux machines have and use ccache to build Koffi, so subsequent build steps will get much more tolerable.
-
-By default, machines are started and stopped for each test. But you can start the machines ahead of time and run the tests multiple times instead:
-
-```sh
-node qemu.js start # Start the machines
-node qemu.js test # Test (without shutting down)
-node qemu.js test # Test again
-node qemu.js stop # Stop everything
-```
-
-You can also restrict the test to a subset of machines:
-
-```sh
-# Full test cycle
-node qemu.js test debian_x64 debian_i386
-
-# Separate start, test, shutdown
-node qemu.js start debian_x64 debian_i386
-node qemu.js test debian_x64 debian_i386
-node qemu.js stop
-```
-
-Finally, you can join a running machine with SSH with the following shortcut, if you need to do some debugging or any other manual procedure:
-
-```sh
-node qemu.js ssh debian_i386
-```
-
-Each machine is configured to run a VNC server available locally, which you can use to access the display, using KRDC or any other compatible viewer. Use the `info` command to get the VNC port.
-
-```sh
-node qemu.js info debian_x64
-```
-
-## Todo list
-
-The following features and improvements are planned, not necessarily in that order:
-
-- Optimize passing of structs and arrays (avoid setting named properties one by one? separate HFA-specific helper functions?)
-- Automate Windows/AArch64 (qemu) and macOS/AArch64 (how? ... thanks Apple) tests
-- Create a real-world example, using several libraries (Raylib, SQLite, libsodium) to illustrate various C API styles
-- Add simple struct type parser
-- Add more ways to manually encode and decode various types to and from byte arrays
-- Add support for unions
-- Port Koffi to PowerPC (POWER9+) ABI
-- Fix assembly unwind and CFI directives for better debugging experience
-
-## Code style
-
-Koffi is programmed in a mix of C++ and assembly code (architecture-specific code). It uses [node-addon-api](https://github.com/nodejs/node-addon-api) (C++ N-API wrapper) to interact with Node.js.
-
-My personal preference goes to a rather C-like C++ style, with careful use of templates (mainly for containers) and little object-oriented programming. I strongly prefer tagged unions and code locality over inheritance and virtual methods. Exceptions are disabled.