koffi 2.1.0-beta.2 → 2.1.0-beta.3

package/ChangeLog.md

@@ -15,8 +15,8 @@
 
 - Improve global performance with inlining and unity builds
 - Add `size_t` primitive type
-- Support member-specific alignement value in structs
-- Detect impossible parameters and return types (such as non-pointer opaque types)
+- Support member-specific alignement values in structs
+- Detect impossible parameter and return types (such as non-pointer opaque types)
 - Various documentation fixes and improvements
 
 ### Koffi 2.0.1

package/doc/Makefile

@@ -6,7 +6,7 @@
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
-BUILDDIR      = dist
+BUILDDIR      = ../build/doc
 
 # Put it first so that "make" without argument is like "make help".
 help:

package/doc/conf.py

@@ -12,6 +12,7 @@ with open(os.path.dirname(__file__) + '/../package.json') as f:
 
     version = config['version']
     revision = config['version']
+    stable = config['stable']
 
 # -- General configuration ---------------------------------------------------
 
@@ -61,6 +62,10 @@ html_sidebars = {
     ]
 }
 
+html_context = {
+    "stable": stable
+}
+
 # -- MyST parser options -------------------------------------------------
 
 myst_enable_extensions = [

package/doc/dist/html/.buildinfo

@@ -0,0 +1,4 @@
+# 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: 83ba69ef407ede43e4983bdec338c734
+tags: 645f666f9bcd5a90fca523b33c5a78b7

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

@@ -0,0 +1,137 @@
+# 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

@@ -0,0 +1,161 @@
+```{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 types
+- `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 types
+
+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, in Koffi 2.0, you must use them through a pointer, and use an array for output parameters.
+
+In addition to that, `koffi.handle()` has been deprecated in Koffi 2.1 and replaced with `koffi.opaque()`. They work the same but new code should use `koffi.opaque()`, the former one will eventually be removed in Koffi 3.0.
+
+For functions that return opaque pointers or pass them by parameter:
+
+```js
+// Koffi 1.x
+
+const FILE = koffi.handle('FILE');
+const fopen = lib.func('fopen', 'FILE', ['str', 'str']);
+const fopen = lib.func('fclose', 'int', ['FILE']);
+
+let fp = fopen('EMPTY', 'wb');
+if (!fp)
+    throw new Error('Failed to open file');
+fclose(fp);
+```
+
+```js
+// Koffi 2.1
+
+// If you use Koffi 2.0: const FILE = koffi.handle('FILE');
+const FILE = koffi.opaque('FILE');
+const fopen = lib.func('fopen', 'FILE *', ['str', 'str']);
+const fopen = lib.func('fclose', 'int', ['FILE *']);
+
+let fp = fopen('EMPTY', '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 = koffi.handle('sqlite3');
+
+const sqlite3_open_v2 = lib.func('int sqlite3_open_v2(const char *, _Out_ sqlite3 *db, int, const char *)');
+const sqlite3_close_v2 = lib.func('int sqlite3_close_v2(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.1
+
+// If you use Koffi 2.0: const sqlite3 = koffi.handle('sqlite3');
+const sqlite3 = koffi.opaque('sqlite3');
+
+const sqlite3_open_v2 = lib.func('int sqlite3_open_v2(const char *, _Out_ sqlite3 **db, int, const char *)');
+const sqlite3_close_v2 = lib.func('int sqlite3_close_v2(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

@@ -0,0 +1,127 @@
+# 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.