koffi 2.16.0 → 3.0.0-alpha.1

package/CHANGELOG.md

@@ -7,6 +7,13 @@
 
 ### Koffi 2.16
 
+#### Koffi 2.16.1
+
+*Released on 2026-04-17*
+
+- Fix possible stack check crash when relaying callbacks on Windows
+- Improve exception handling inside callbacks
+
 #### Koffi 2.16.0
 
 *Released on 2026-04-14*
@@ -14,7 +21,7 @@
 - Support buffers and typed arrays in `koffi.address()`
 - Put x86 SEH record at the top of stack frame
 - Optimize Koffi binaries produced by GCC (with `-fno-semantic-interposition`)
-- Fix nonsensical addresses in Koffi call dumps (when using DUMP_CALLS=1 environement variable)
+- Fix nonsensical addresses in Koffi call dumps (when using DUMP_CALLS=1 environment variable)
 
 - Reduce Koffi package size even more:
   * Replace table of callback trampoline pointers with simple offset computation
@@ -52,7 +59,7 @@
 
 *Released on 2026-04-03*
 
-- Fix *IsOnCentralStack()* assertion/crash when using callbacks in recent Node versions
+- Fix "IsOnCentralStack()" assertion/crash when using callbacks in recent Node versions
 - Support SetUnhandledExceptionFilter on Windows x64 and x86 ([@longhun12346](https://github.com/longhun12346))
 - Fix incorrect stack alignment when relaying callbacks on 32-bit x86 platforms
 
@@ -68,7 +75,7 @@
 
 #### Koffi 2.15.1
 
-*Released on 2025-01-24*
+*Released on 2026-01-24*
 
 - Fix possible union-related crashes
 - Support MinGW-w64 x64 builds on Windows

package/README.md

@@ -9,14 +9,14 @@ Koffi is a fast and easy-to-use C FFI module for Node.js, featuring:
 
 The following combinations of OS and architectures __are officially supported and tested__ at the moment:
 
-ISA / OS           | Windows     | Linux (glibc) | Linux (musl) | macOS       | FreeBSD     | OpenBSD
------------------- | ----------- | ------------- | ------------ | ----------- | ----------- | --------
-x86 (IA32) [^1]    | ✅ Yes      | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | ✅ Yes      | ✅ Yes
-x86_64 (AMD64)     | ✅ Yes      | ✅ Yes        | ✅ Yes       | ✅ Yes      | ✅ Yes      | ✅ Yes
-ARM32 LE [^2]      | ⬜️ *N/A*    | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
-ARM64 (AArch64) LE | ✅ Yes      | ✅ Yes        | ✅ Yes       | ✅ Yes      | ✅ Yes      | 🟨 Probably
-RISC-V 64 [^3]     | ⬜️ *N/A*    | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
-LoongArch64        | ⬜️ *N/A*    | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
+ISA / OS           | Windows     | Linux/glibc | Linux/musl  | macOS       | FreeBSD     | OpenBSD
+------------------ | ----------- | ----------- | ----------- | ----------- | ----------- | --------
+x86 (IA32) [^1]    | ✅ Yes      | ✅ Yes      | 🟨 Probably | ⬜️ *N/A*    | ✅ Yes      | ✅ Yes
+x86_64 (AMD64)     | ✅ Yes      | ✅ Yes      | ✅ Yes      | ✅ Yes      | ✅ Yes      | ✅ Yes
+ARM32 LE [^2]      | ⬜️ *N/A*    | ✅ Yes      | 🟨 Probably | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
+ARM64 (AArch64) LE | ✅ Yes      | ✅ Yes      | ✅ Yes      | ✅ Yes      | ✅ Yes      | 🟨 Probably
+RISC-V 64 [^3]     | ⬜️ *N/A*    | ✅ Yes      | 🟨 Probably | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
+LoongArch64        | ⬜️ *N/A*    | ✅ Yes      | 🟨 Probably | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
 
 [^1]: The following call conventions are supported: cdecl, stdcall, MS fastcall, thiscall.
 [^2]: The prebuilt binary uses the hard float ABI and expects a VFP coprocessor. Build from source to use Koffi with a different ABI (softfp, soft).

package/doc/benchmarks.md

@@ -15,7 +15,7 @@ These results are detailed and explained below, and compared to node-ffi/node-ff
 
 # Linux x86_64
 
-The results presented below were measured on my x86_64 Linux machine (AMD Ryzen™ 5 2600).
+The results presented below were measured on my x86_64 Linux machine (Intel® Core™ Ultra 9 185H).
 
 ## rand results
 
@@ -25,11 +25,11 @@ This test is based around repeated calls to a simple standard C function `rand`,
 - the second one calls rand through Koffi
 - the third one uses the official Node.js FFI implementation, node-ffi-napi
 
-Benchmark     | Iteration time | Relative performance | Overhead
+rand          | Iteration time | Relative performance | Overhead
 ------------- | -------------- | -------------------- | --------
-rand_napi     | 569 ns         | x1.00                | (ref)
-rand_koffi    | 855 ns         | x0.67                | +50%
-rand_node_ffi | 58730 ns       | x0.010               | +10228%
+napi          | 256 ns         | x1.00                | +0%
+koffi         | 375 ns         | x0.68                | +46%
+node-ffi-napi | 29783 ns       | x0.009               | +11544%
 
 Because rand is a pretty small function, the FFI overhead is clearly visible.
 
@@ -37,11 +37,11 @@ Because rand is a pretty small function, the FFI overhead is clearly visible.
 
 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          | Iteration time | Relative performance | Overhead
 ------------- | -------------- | -------------------- | --------
-atoi_napi     | 1039 ns        | x1.00                | (ref)
-atoi_koffi    | 1642 ns        | x0.63                | +58%
-atoi_node_ffi | 164790 ns      | x0.006               | +15767%
+napi          | 371 ns         | x1.00                | +0%
+koffi         | 557 ns         | x0.67                | +50%
+node-ffi-napi | 104340 ns      | x0.004               | +27988%
 
 Because atoi is a pretty small function, the FFI overhead is clearly visible.
 
@@ -52,12 +52,12 @@ This benchmark uses the CPU-based image drawing functions in Raylib. The calls a
 - 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          | 17.5 µs        | x1.34                | -25%
-raylib_node_raylib | 23.4 µs        | x1.00                | (ref)
-raylib_koffi       | 28.8 µs        | x0.81                | +23%
-raylib_node_ffi    | 103.9 µs       | x0.23                | +344%
+raylib        | Iteration time | Relative performance | Overhead
+------------- | -------------- | -------------------- | --------
+C++           | 10.8 µs        | x1.14                | -12%
+node-raylib   | 12.3 µs        | x1.00                | +0%
+koffi         | 13.2 µs        | x0.92                | +8%
+node-ffi-napi | 80.3 µs        | x0.15                | +555%
 
 # Windows x86_64
 
@@ -71,11 +71,11 @@ This test is based around repeated calls to a simple standard C function `rand`,
 - the second one calls rand through Koffi
 - the third one uses the official Node.js FFI implementation, node-ffi-napi
 
-Benchmark     | Iteration time | Relative performance | Overhead
+rand          | Iteration time | Relative performance | Overhead
 ------------- | -------------- | -------------------- | --------
-rand_napi     | 859 ns         | x1.00                | (ref)
-rand_koffi    | 1352 ns        | x0.64                | +57%
-rand_node_ffi | 35640 ns       | x0.02                | +4048%
+napi          | 859 ns         | x1.00                | (ref)
+koffi         | 1352 ns        | x0.64                | +57%
+node-ffi-napi | 35640 ns       | x0.02                | +4048%
 
 Because rand is a pretty small function, the FFI overhead is clearly visible.
 
@@ -85,11 +85,11 @@ This test is similar to the rand one, but it is based on `atoi`, which takes a s
 
 The results below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460):
 
-Benchmark     | Iteration time | Relative performance | Overhead
+atoi          | Iteration time | Relative performance | Overhead
 ------------- | -------------- | -------------------- | --------
-atoi_napi     | 1336 ns        | x1.00                | (ref)
-atoi_koffi    | 2440 ns        | x0.55                | +83%
-atoi_node_ffi | 136890 ns      | x0.010               | +10144%
+napi          | 1336 ns        | x1.00                | (ref)
+koffi         | 2440 ns        | x0.55                | +83%
+node-ffi-napi | 136890 ns      | x0.010               | +10144%
 
 Because atoi is a pretty small function, the FFI overhead is clearly visible.
 
@@ -100,23 +100,23 @@ This benchmark uses the CPU-based image drawing functions in Raylib. The calls a
 - [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          | 18.2 µs        | x1.50                | -33%
-raylib_node_raylib | 27.3 µs        | x1.00                | (ref)
-raylib_koffi       | 29.8 µs        | x0.92                | +9%
-raylib_node_ffi    | 96.3 µs        | x0.28                | +253%
+raylib        | Iteration time | Relative performance | Overhead
+------------- | -------------- | -------------------- | --------
+C++           | 18.2 µs        | x1.50                | -33%
+node-raylib   | 27.3 µs        | x1.00                | (ref)
+koffi         | 29.8 µs        | x0.92                | +9%
+node-ffi-napi | 96.3 µs        | x0.28                | +253%
 
 # Running benchmarks
 
 Please note that all benchmark results on this page are made with Clang-built binaries.
 
 ```sh
-cd koffi
-node ../../cnoke/cnoke.js --prefer-clang
+cd src/koffi
+node ../cnoke/cnoke.js --clang --release
 
-cd koffi/benchmark
-node ../../cnoke/cnoke.js --prefer-clang
+cd benchmark
+node ../../cnoke/cnoke.js --clang --release
 ```
 
 Once everything is built and ready, run:

package/doc/contribute.md

@@ -32,6 +32,9 @@ cd src/koffi
 node ../cnoke/cnoke.js
 ```
 
+> [!NOTE]
+> Use `node ../cnoke/cnoke.js --debug` to make debug builds
+
 ## Other platforms
 
 Make sure the following dependencies are met:
@@ -48,6 +51,9 @@ cd src/koffi
 node ../cnoke/cnoke.js
 ```
 
+> [!NOTE]
+> Use `node ../cnoke/cnoke.js --debug` to make debug builds
+
 # Run tests
 
 ## On your machine
@@ -56,8 +62,7 @@ Once Koffi is built, you can build the tests and run them with the following com
 
 ```sh
 cd src/koffi/test
-node ../../cnoke/cnoke.js
-
+node ../../cnoke/cnoke.js # Build C test code
 node test.js
 ```
 
@@ -65,15 +70,20 @@ node test.js
 
 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:
+The Linux machines are based on Debian, they are not included in the repository but they can be created at any time with the scripts in `tools/cross/build`. For example, to create the Debian ARM64 machine, use the following commands:
 
 ```sh
-cd deploy/qemu/
+cd tools/cross/build
+./debian_arm64/build.sh
+```
+
+The other machines (Alpine, FreeBSD, OpenBSD, macOS and Windows) are created manually, at least for now. These machines are not included directly in this repository (for license and size reasons), but they are available here: https://download.koromix.dev/qemu/
 
-wget -q -O- https://koromix.dev/files/machines/qemu_debian_arm64.tar.zst | zstd -d | tar xv
-b3sum -c b3sum.txt
+For example, if you want to build and test for Windows, run the following commands:
+
+```sh
+cd tools/cross/
+wget -q -O- https://download.koromix.dev/qemu/qemu_windows_x64.tar.zst | zstd -d | tar xv
 ```
 
 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.
@@ -81,42 +91,42 @@ 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 test # Several options are available, use --help
+cd src/koffi
+
+node tools/brew.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:
+Machines are started for each test if needed, and stay active until you stop them. You can start and stop them at any time with the following commands:
 
 ```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
+node tools/brew.js start # Start all available machines
+node tools/brew.js stop # Stop everything
 ```
 
-You can also restrict the test to a subset of machines:
+You can also restrict these commands to a subset of machines:
 
 ```sh
 # Full test cycle
-node qemu.js test debian_x64 debian_i386
+node tools/brew.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
+node tools/brew.js start debian_x64 debian_i386
+node tools/brew.js test debian_x64 debian_i386
+node tools/brew.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
+node tools/brew.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.
+Each machine is configured to run a VNC server or SPICE, which you can use to access the display, using KRDC or any other compatible viewer. Use the `info` command to get the VNC or the SPICE port.
 
 ```sh
-node qemu.js info debian_x64
+node tools/brew.js info debian_x64
 ```
 
 # Making a release
@@ -130,10 +140,12 @@ First, you must update the code in three steps:
 Once this is done, you can publish a new release with the following commands:
 
 ```sh
-node tools/qemu.js test # If not done before
-node tools/qemu.js build
+cd src/koffi
+
+node tools/brew.js test # If not done before
+node tools/brew.js build
 
-cd build/dist
+cd ../../bin/Koffi/package
 npm publish
 ```
 

package/doc/index.md

@@ -19,14 +19,14 @@ Koffi requires [Node.js](https://nodejs.org/) version 16 or later. Use [NVM](htt
 
 The following combinations of OS and architectures __are officially supported and tested__ at the moment:
 
-ISA / OS           | Windows | Linux (glibc) | Linux (musl) | macOS | FreeBSD | OpenBSD
------------------- | ------- | ------------- | ------------ | ----- | ------- | -------
-x86 (IA32) [^2]    | ✅       | ✅             | 🟨            | ⬜️    | ✅       | ✅
-x86_64 (AMD64)     | ✅       | ✅             | ✅            | ✅    | ✅       | ✅
-ARM32 LE [^3]      | ⬜️       | ✅             | 🟨            | ⬜️    | 🟨       | 🟨
-ARM64 (AArch64) LE | ✅       | ✅             | ✅            | ✅    | ✅       | 🟨
-RISC-V 64 [^4]     | ⬜️       | ✅             | 🟨            | ⬜️    | 🟨       | 🟨
-LoongArch64        | ⬜️       | ✅             | 🟨            | ⬜️    | 🟨       | 🟨
+ISA / OS           | Windows | Linux/glibc | Linux/musl | macOS | FreeBSD | OpenBSD
+------------------ | ------- | ----------- | ---------- | ----- | ------- | -------
+x86 (IA32) [^2]    | ✅      | ✅          | 🟨         | ⬜️    | ✅      | ✅
+x86_64 (AMD64)     | ✅      | ✅          | ✅         | ✅    | ✅      | ✅
+ARM32 LE [^3]      | ⬜️      | ✅          | 🟨         | ⬜️    | 🟨      | 🟨
+ARM64 (AArch64) LE | ✅      | ✅          | ✅         | ✅    | ✅      | 🟨
+RISC-V 64 [^4]     | ⬜️      | ✅          | 🟨         | ⬜️    | 🟨      | 🟨
+LoongArch64        | ⬜️      | ✅          | 🟨         | ⬜️    | 🟨      | 🟨
 
 <div class="legend">✅ Yes | 🟨 Probably | ⬜️ Not applicable</div>
 

package/doc/variables.md

@@ -17,7 +17,7 @@ const my_string = lib.symbol('my_string', 'const char *');
 You cannot directly manipulate these variables, use:
 
 - [koffi.decode()](#decode-to-js-values) to read their value
-- [koffi.encode()](#encode-to-c-memory) to change their valuèe
+- [koffi.encode()](#encode-to-c-memory) to change their value
 
 # Decode to JS values
 

package/index.d.ts

@@ -145,13 +145,15 @@ export function introspect(type: TypeSpec): TypeInfo;
 export function alias(name: string, type: TypeSpec): IKoffiCType;
 
 type KoffiConfig = {
-    sync_stack_size?: number
-    sync_heap_size?: number
-    async_stack_size?: number
-    async_heap_size?: number
-    resident_async_pools?: number
-    max_async_calls?: number
-    max_type_size?: number
+    sync_stack_size?: number;
+    sync_heap_size?: number;
+    async_stack_size?: number;
+    async_heap_size?: number;
+    resident_async_pools?: number;
+    max_async_calls?: number;
+    max_type_size?: number;
+    fast_pointers?: boolean;
+    fast_callbacks?: boolean;
 };
 type KoffiStats = {
     disposed: number
@@ -169,8 +171,8 @@ export function errno(value: number): number;
 
 export function reset(): void;
 
-export const internal: Boolean;
-export const extension: String;
+export const internal: boolean;
+export const extension: string;
 
 export const os: {
     errno: Record<string, number>