koffi 1.3.5 → 1.3.8

package/CMakeLists.txt

@@ -110,7 +110,7 @@ if(WIN32)
     target_compile_definitions(koffi PRIVATE _CRT_SECURE_NO_WARNINGS _CRT_NONSTDC_NO_DEPRECATE)
     target_link_libraries(koffi PRIVATE ws2_32)
 endif()
-if(NOT MSVC)
+if(NOT MSVC OR CMAKE_C_COMPILER_ID MATCHES "[Cc]lang")
     # Restore C/C++ compiler sanity
 
     target_compile_options(koffi PRIVATE -fno-exceptions -fno-strict-aliasing -fwrapv

package/ChangeLog.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## Koffi 1.3.8
+
+**Main changes:**
+
+- Prevent callback reuse beyond FFI call
+- Add BTI support for AAarch64 platforms (except Windows)
+
+**Other changes:**
+
+- Fix and harmonize a few error messages
+
+## Koffi 1.3.7
+
+**Main fixes:**
+
+- Fix crash when using callbacks inside structs
+- Support for null strings in record members
+
+**Other changes:**
+
+- Add intptr_t and uintptr_t primitive types
+- Add str/str16 type aliases for string/string16
+- Various documentation fixes and improvements
+
+## Koffi 1.3.6
+
+**Main fixes:**
+
+- Fix install error with Node < 15 on Windows (build system bug)
+
+**Other changes:**
+
+- Detect incompatible Node.js versions when installing Koffi
+- Prebuild with Clang for Windows x64 and Linux x64 binaries
+- Various documentation improvements
+
 ## Koffi 1.3.5
 
 **Main changes:**

package/benchmark/atoi_koffi.js

@@ -35,11 +35,10 @@ function main() {
         if (iterations < 1)
             throw new Error('Value must be positive');
     }
-    console.log('Iterations:', iterations);
 
     let lib = koffi.load(process.platform == 'win32' ? 'msvcrt.dll' : null);
 
-    const atoi = lib.cdecl('atoi', 'int', ['string']);
+    const atoi = lib.cdecl('atoi', 'int', ['str']);
 
     let start = performance.now();
 
@@ -47,6 +46,6 @@ function main() {
         sum += atoi(strings[i % strings.length]);
     }
 
-    let time = performance.now()- start;
-    console.log('Time:', (time / 1000.0).toFixed(2) + 's');
+    let time = performance.now() - start;
+    console.log(JSON.stringify({ iterations: iterations, time: Math.round(time) }));
 }

package/benchmark/atoi_napi.js

@@ -35,7 +35,6 @@ function main() {
         if (iterations < 1)
             throw new Error('Value must be positive');
     }
-    console.log('Iterations:', iterations);
 
     let start = performance.now();
 
@@ -43,6 +42,6 @@ function main() {
         sum += atoi.atoi(strings[i % strings.length]);
     }
 
-    let time = performance.now()- start;
-    console.log('Time:', (time / 1000.0).toFixed(2) + 's');
+    let time = performance.now() - start;
+    console.log(JSON.stringify({ iterations: iterations, time: Math.round(time) }));
 }

package/benchmark/atoi_node_ffi.js

@@ -28,7 +28,7 @@ let sum = 0;
 main();
 
 async function main() {
-    let iterations = 20000000;
+    let iterations = 200000;
 
     if (process.argv.length >= 3) {
         iterations = parseInt(process.argv[2], 10);
@@ -37,7 +37,6 @@ async function main() {
         if (iterations < 1)
             throw new Error('Value must be positive');
     }
-    console.log('Iterations:', iterations);
 
     const lib = ffi.Library(process.platform == 'win32' ? 'msvcrt.dll' : null, {
         atoi: ['int', ['string']]
@@ -52,6 +51,6 @@ async function main() {
         sum += lib.atoi(strings[i % strings.length]);
     }
 
-    let time = performance.now()- start;
-    console.log('Time:', (time / 1000.0).toFixed(2) + 's');
+    let time = performance.now() - start;
+    console.log(JSON.stringify({ iterations: iterations, time: Math.round(time) }));
 }

package/benchmark/raylib_cc.cc

@@ -18,13 +18,12 @@ namespace RG {
 
 int Main(int argc, char **argv)
 {
-    int iterations = 100;
+    int iterations = 360000;
 
     if (argc >= 2) {
         if (!ParseInt(argv[1], &iterations))
             return 1;
     }
-    LogInfo("Iterations: %1", iterations);
 
     // We need to call InitWindow before using anything else (such as fonts)
     SetTraceLogLevel(LOG_WARNING);
@@ -36,7 +35,7 @@ int Main(int argc, char **argv)
 
     int64_t start = GetMonotonicTime();
 
-    for (int i = 0; i < iterations; i++) {
+    for (int i = 0; i < iterations; i += 3600) {
         ImageClearBackground(&img, Color { 0, 0, 0, 255 });
 
         for (int j = 0; j < 3600; j++) {
@@ -60,7 +59,7 @@ int Main(int argc, char **argv)
     }
 
     int64_t time = GetMonotonicTime() - start;
-    LogInfo("Time: %1s", FmtDouble((double)time / 1000.0, 2));
+    PrintLn("{\"iterations\": %1,\"time\": %2}", iterations, time);
 
     return 0;
 }

package/benchmark/raylib_cc.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see https://www.gnu.org/licenses/.
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+main();
+
+function main() {
+    let filename = path.join(__dirname, 'build/raylib_cc' + (process.platform == 'win32' ? '.exe' : ''));
+    let proc = spawnSync(filename, process.argv.slice(2), { stdio: 'inherit' });
+
+    if (proc.status == null) {
+        console.error(proc.error);
+        process.exit(1);
+    }
+
+    process.exit(proc.status);
+}

package/benchmark/raylib_koffi.js

@@ -71,7 +71,7 @@ const Font = koffi.struct('Font', {
 main();
 
 function main() {
-    let iterations = 100;
+    let iterations = 360000;
 
     if (process.argv.length >= 3) {
         iterations = parseInt(process.argv[2], 10);
@@ -80,20 +80,19 @@ function main() {
         if (iterations < 1)
             throw new Error('Value must be positive');
     }
-    console.log('Iterations:', iterations);
 
     let lib_filename = path.dirname(__filename) + '/build/raylib' + koffi.extension;
     let lib = koffi.load(lib_filename);
 
-    const InitWindow = lib.cdecl('InitWindow', 'void', ['int', 'int', 'string']);
+    const InitWindow = lib.cdecl('InitWindow', 'void', ['int', 'int', 'str']);
     const SetTraceLogLevel = lib.cdecl('SetTraceLogLevel', 'void', ['int']);
     const SetWindowState = lib.cdecl('SetWindowState', 'void', ['uint']);
     const GenImageColor = lib.cdecl('GenImageColor', Image, ['int', 'int', Color]);
     const GetFontDefault = lib.cdecl('GetFontDefault', Font, []);
-    const MeasureTextEx = lib.cdecl('MeasureTextEx', Vector2, [Font, 'string', 'float', 'float']);
+    const MeasureTextEx = lib.cdecl('MeasureTextEx', Vector2, [Font, 'str', 'float', 'float']);
     const ImageClearBackground = lib.cdecl('ImageClearBackground', 'void', [koffi.pointer(Image), Color]);
-    const ImageDrawTextEx = lib.cdecl('ImageDrawTextEx', 'void', [koffi.pointer(Image), Font, 'string', Vector2, 'float', 'float', Color]);
-    const ExportImage = lib.cdecl('ExportImage', 'bool', [Image, 'string']);
+    const ImageDrawTextEx = lib.cdecl('ImageDrawTextEx', 'void', [koffi.pointer(Image), Font, 'str', Vector2, 'float', 'float', Color]);
+    const ExportImage = lib.cdecl('ExportImage', 'bool', [Image, 'str']);
 
     // We need to call InitWindow before using anything else (such as fonts)
     SetTraceLogLevel(4); // Warnings
@@ -105,7 +104,7 @@ function main() {
 
     let start = performance.now();
 
-    for (let i = 0; i < iterations; i++) {
+    for (let i = 0; i < iterations; i += 3600) {
         ImageClearBackground(img, { r: 0, g: 0, b: 0, a: 255 });
 
         for (let j = 0; j < 3600; j++) {
@@ -128,6 +127,6 @@ function main() {
         }
     }
 
-    let time = performance.now()- start;
-    console.log('Time:', (time / 1000.0).toFixed(2) + 's');
+    let time = performance.now() - start;
+    console.log(JSON.stringify({ iterations: iterations, time: Math.round(time) }));
 }

package/benchmark/raylib_node_ffi.js

@@ -87,7 +87,7 @@ const Font = struct({
 main();
 
 function main() {
-    let iterations = 100;
+    let iterations = 180000;
 
     if (process.argv.length >= 3) {
         iterations = parseInt(process.argv[2], 10);
@@ -96,7 +96,6 @@ function main() {
         if (iterations < 1)
             throw new Error('Value must be positive');
     }
-    console.log('Iterations:', iterations);
 
     let lib_filename = path.dirname(__filename) + '/build/raylib' + koffi.extension;
 
@@ -123,7 +122,7 @@ function main() {
 
     let start = performance.now();
 
-    for (let i = 0; i < iterations; i++) {
+    for (let i = 0; i < iterations; i += 3600) {
         r.ImageClearBackground(imgp, new Color({ r: 0, g: 0, b: 0, a: 255 }));
 
         for (let j = 0; j < 3600; j++) {
@@ -146,6 +145,6 @@ function main() {
         }
     }
 
-    let time = performance.now()- start;
-    console.log('Time:', (time / 1000.0).toFixed(2) + 's');
+    let time = performance.now() - start;
+    console.log(JSON.stringify({ iterations: iterations, time: Math.round(time) }));
 }

package/benchmark/raylib_node_raylib.js

@@ -18,7 +18,7 @@ const r = require('raylib');
 main();
 
 function main() {
-    let iterations = 100;
+    let iterations = 360000;
 
     if (process.argv.length >= 3) {
         iterations = parseInt(process.argv[2], 10);
@@ -27,7 +27,6 @@ function main() {
         if (iterations < 1)
             throw new Error('Value must be positive');
     }
-    console.log('Iterations:', iterations);
 
     // We need to call InitWindow before using anything else (such as fonts)
     r.SetTraceLogLevel(4); // Warnings
@@ -39,7 +38,7 @@ function main() {
 
     let start = performance.now();
 
-    for (let i = 0; i < iterations; i++) {
+    for (let i = 0; i < iterations; i += 3600) {
         r.ImageClearBackground(img, { r: 0, g: 0, b: 0, a: 255 });
 
         for (let j = 0; j < 3600; j++) {
@@ -62,6 +61,6 @@ function main() {
         }
     }
 
-    let time = performance.now()- start;
-    console.log('Time:', (time / 1000.0).toFixed(2) + 's');
+    let time = performance.now() - start;
+    console.log(JSON.stringify({ iterations: iterations, time: Math.round(time) }));
 }

package/doc/benchmarks.md

@@ -1,5 +1,7 @@
 # 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
@@ -8,14 +10,18 @@ Here is a quick overview of the execution time of Koffi calls on three benchmark
 
 <table style="margin: 0 auto;">
     <tr>
-        <td><a href="_static/perf_linux_20220623_2.png" target="_blank"><img src="_static/perf_linux_20220623_2.png" alt="Linux performance" style="width: 350px;"/></a></td>
-        <td><a href="_static/perf_windows_20220623_2.png" target="_blank"><img src="_static/perf_windows_20220623_2.png" alt="Windows performance" style="width: 350px;"/></a></td>
+        <td><a href="_static/perf_linux_20220628.png" target="_blank"><img src="_static/perf_linux_20220628.png" alt="Linux 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 performance" style="width: 350px;"/></a></td>
     </tr>
 </table>
 
 These results are detailed and explained below, and compared to node-ffi/node-ffi-napi.
 
-## rand results
+## 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:
 
@@ -23,95 +29,109 @@ This test is based around repeated calls to a simple standard C function atoi, a
 - 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.
 
-### Linux x86_64
+### atoi results
 
-The results below were measured on my x86_64 Linux machine (AMD® Ryzen™ 7 4700U):
+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     | Iterations | Total time  | Relative performance | Overhead
-------------- | ---------- | ----------- | -------------------- | ----------
-rand_napi     | 20000000   | 1.44s       | (baseline)           | (baseline)
-rand_koffi    | 20000000   | 2.60s       | x0.55                | +81%
-rand_node_ffi | 20000000   | 107.58s     | x0.01                | +7400%
+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%
 
-### Windows x86_64
+Because atoi is a pretty small function, the FFI overhead is clearly visible.
 
-The results below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460):
+### 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:
 
-Benchmark     | Iterations | Total time  | Relative performance | Overhead
-------------- | ---------- | ----------- | -------------------- | ----------
-rand_napi     | 20000000   | 2.10s       | (baseline)           | (baseline)
-rand_koffi    | 20000000   | 3.87s       | x0.54                | +84%
-rand_node_ffi | 20000000   | 87.84s      | x0.02                | +4100%
+- 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
 
-## atoi results
+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%
 
-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.
+## Windows x86_64
 
-Because rand is a pretty small function, the FFI overhead is clearly visible.
+The results presented below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460).
+
+### rand results
 
-### Linux x86_64
+This test is based around repeated calls to a simple standard C function atoi, and has three implementations:
 
-The results below were measured on my x86_64 Linux machine (AMD® Ryzen™ 7 4700U):
+- 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     | Iterations | Total time  | Relative performance | Overhead
-------------- | ---------- | ----------- | -------------------- | ----------
-atoi_napi     | 20000000   | 2.97s       | (baseline)           | (baseline)
-atoi_koffi    | 20000000   | 5.07s       | x0.58                | +71%
-atoi_node_ffi | 20000000   | 693.16s     | x0.005               | +23000%
+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%
 
-### Windows x86_64
+Because rand is a pretty small function, the FFI overhead is clearly visible.
 
-The results below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460):
+### atoi results
 
-Benchmark     | Iterations | Total time  | Relative performance | Overhead
-------------- | ---------- | ----------- | -------------------- | ----------
-atoi_napi     | 20000000   | 2.97s       | (baseline)           | (baseline)
-atoi_koffi    | 20000000   | 5.91s       | x0.50                | +99%
-atoi_node_ffi | 20000000   | 479.34s     | x0.006               | +16000%
+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.
 
-## Raylib results
+The results below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460):
 
-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:
+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%
 
-- 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
+Because atoi is a pretty small function, the FFI overhead is clearly visible.
 
-### Linux x86_64
+### Raylib results
 
-The results below were measured on my x86_64 Linux machine (AMD® Ryzen™ 7 4700U):
+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:
 
-Benchmark          | Iterations | Total time  | Relative performance | Overhead
----------------    | ---------- | ----------- | -------------------- | ----------
-raylib_cc          | 100        | 9.31s       | x1.17                | -15%
-raylib_node_raylib | 100        | 10.90s      | (baseline)           | (baseline)
-raylib_koffi       | 100        | 12.86s      | x0.84                | +18%
-raylib_node_ffi    | 100        | 35.76s      | x0.30                | +228%
+- [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
 
-### Windows x86_64
+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%
 
-The results below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460):
+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:
 
-Benchmark          | Iterations | Total time  | Relative performance | Overhead
----------------    | ---------- | ----------- | -------------------- | ----------
-raylib_cc          | 100        | 10.67s      | x1.17                | -12%
-raylib_node_raylib | 100        | 12.05s      | (baseline)           | (baseline)
-raylib_koffi       | 100        | 14.84s      | x0.81                | +23%
-raylib_node_ffi    | 100        | 44.63s      | x0.27                | +270%
+```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
+node ../../cnoke/cnoke.js --prefer-clang
 ```
 
-Once this is done, you can execute each implementation, e.g. `build/raylib_cc` or `node ./atoi_koffi.js`. You can optionally define a custom number of iterations, e.g. `node ./atoi_koffi.js 10000000`.
+Once everything is built and ready, run:
 
 ```sh
-node ./atoi_napi.js
-node ./atoi_koffi.js
+node benchmark.js
 ```

package/doc/conf.py

@@ -58,4 +58,4 @@ myst_heading_anchors = 3
 
 myst_linkify_fuzzy_links = False
 
-myst_number_code_blocks = ['c', 'js']
+myst_number_code_blocks = ['c', 'js', 'sh', 'batch']

package/doc/contribute.md

@@ -69,7 +69,7 @@ Note that the machine disk content may change each time the machine runs, so the
 And now you can run the tests with:
 
 ```sh
-node qemu.js # Several options are available, use --help
+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.
@@ -78,8 +78,8 @@ By default, machines are started and stopped for each test. But you can start th
 
 ```sh
 node qemu.js start # Start the machines
-node qemu.js # Test (without shutting down)
-node qemu.js # Test again
+node qemu.js test # Test (without shutting down)
+node qemu.js test # Test again
 node qemu.js stop # Stop everything
 ```
 
@@ -109,18 +109,15 @@ node qemu.js info debian_x64
 
 ## Todo list
 
-After the release of version 1.3.0, the current priorities for the next major release are:
+The following features and improvements are planned, not necessarily in that order:
 
-- Automate Windows/AArch64 (qemu) and macOS/AArch64 (how?) tests and builds
-- Create a real-world example, using several libraries (Raylib, SQLite, libsodium) to illustrate how to work with various C API styles
-
-The following features are also planned eventually, not necessarily in that order:
-
-- Optimize passing of structs and arrays, with separate HFA-specific helper functions
+- Provide better ways to automatically deal with caller/heap-allocated memory (strings, etc.)
+- 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
-- Provide better ways to automatically deal with caller/heap-allocated memory (strings, etc.)
 - Port Koffi to PowerPC (POWER9+) ABI
 - Fix assembly unwind and CFI directives for better debugging experience