koffi 1.3.2 → 1.3.5

package/CMakeLists.txt

@@ -14,6 +14,13 @@
 cmake_minimum_required(VERSION 3.6)
 project(koffi C CXX ASM)
 
+include(CheckCXXCompilerFlag)
+if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.9.0")
+    cmake_policy(SET CMP0069 NEW)
+    include(CheckIPOSupported)
+    check_ipo_supported(RESULT USE_LTO)
+endif()
+
 find_package(CNoke)
 
 if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.8.0")
@@ -22,7 +29,7 @@ else()
     set(CMAKE_CXX_STANDARD 14)
 endif()
 if(MSVC)
-    add_compile_options(/W4 /wd4200 /wd4458 /wd4706 /wd4100 /wd4127 /wd4702 /wd4201 /wd4324)
+    add_compile_options(/Zc:__cplusplus /W4 /wd4200 /wd4458 /wd4706 /wd4100 /wd4127 /wd4702 /wd4201 /wd4324)
 
     # ASM_MASM does not (yet) work on Windows ARM64
     if(NOT CMAKE_GENERATOR_PLATFORM MATCHES "ARM64")
@@ -47,10 +54,16 @@ set(KOFFI_SRC
 if(CMAKE_SIZEOF_VOID_P EQUAL 8)
     # CMAKE_SYSTEM_PROCESSOR is wrong on Windows ARM64
 
-    if(CMAKE_SYSTEM_PROCESSOR MATCHES "aarch|arm" OR CMAKE_GENERATOR_PLATFORM STREQUAL "ARM64")
+    if(CMAKE_SYSTEM_PROCESSOR MATCHES "aarch|arm" OR CMAKE_GENERATOR_PLATFORM STREQUAL "ARM64" OR CMAKE_OSX_ARCHITECTURES MATCHES "arm")
         if(WIN32)
             get_filename_component(cl_dir "${CMAKE_CXX_COMPILER}" DIRECTORY)
             file(TO_CMAKE_PATH "${cl_dir}/armasm64.exe" asm_compiler)
+
+            # Work around missing ARM64-native ARMASM64 compiler (at least in VS 17.3 Preview 2)
+            if(NOT EXISTS "${asm_compiler}")
+                file(TO_CMAKE_PATH "${cl_dir}/../../Hostx64/arm64/armasm64.exe" asm_compiler)
+            endif()
+
             message(STATUS "Using ARMASM64 compiler: ${asm_compiler}")
 
             file(TO_CMAKE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/src/abi_arm64_fwd.asm" asm_source)
@@ -98,5 +111,16 @@ if(WIN32)
     target_link_libraries(koffi PRIVATE ws2_32)
 endif()
 if(NOT MSVC)
-    target_compile_options(koffi PRIVATE -fno-exceptions -fno-strict-aliasing)
+    # Restore C/C++ compiler sanity
+
+    target_compile_options(koffi PRIVATE -fno-exceptions -fno-strict-aliasing -fwrapv
+                                         -fno-delete-null-pointer-checks)
+
+    check_cxx_compiler_flag(-fno-finite-loops use_no_finite_loops)
+    if(use_no_finite_loops)
+        target_compile_options(koffi PRIVATE -fno-finite-loops)
+    endif()
+endif()
+if(USE_LTO)
+    set_target_properties(koffi PROPERTIES INTERPROCEDURAL_OPTIMIZATION TRUE)
 endif()

package/ChangeLog.md

@@ -1,24 +1,56 @@
-# Koffi 1.3.2
+# Changelog
 
-## Main fixes
+## Koffi 1.3.5
+
+**Main changes:**
+
+- Fix memory leak when many async calls are running
+- Add configurable limit for maximum number of async calls (max_async_calls)
+
+**Other changes:**
+
+- Reduce default async memory stack and heap size
+- Various documentation improvements
+
+## Koffi 1.3.4
+
+**Main fixes:**
+
+- Fix possible OpenBSD i386 crash with `(void)` functions
+
+## Koffi 1.3.3
+
+**Main fixes:**
+
+- Fix misconversion of signed integer return value as unsigned
+
+**Other changes:**
+
+- Support `(void)` (empty) function signatures
+- Disable unsafe compiler optimizations
+- Various documentation improvements
+
+## Koffi 1.3.2
+
+**Main fixes:**
 
 - Support compilation in C++14 mode (graceful degradation)
 - Support older toolchains on Linux (tested on Debian 9)
 
-# Koffi 1.3.1
+## Koffi 1.3.1
 
-## Main fixes
+**Main fixes:**
 
 - The prebuilt binary is tested when Koffi is installed, and a rebuild happens if it fails to load
 
-# Koffi 1.3.0
+## Koffi 1.3.0
 
-## Major changes
+**Major changes:**
 
 - Expand and move documentation to https://koffi.dev/
 - Support JS arrays and TypedArrays for pointer arguments (input, output and mixed)
 
-## Other changes
+**Other changes:**
 
 - Convert NULL string pointers to null instead of crashing (return values, struct and array members, callbacks)
 - Default to 'string' array hint for char, char16 and char16_t arrays
@@ -27,23 +59,23 @@
 - Detect floating-point ABI before using prebuilt binaries (ARM32, RISC-V)
 - Forbid duplicate member names in struct types
 
-# Koffi 1.2.4
+## Koffi 1.2.4
 
-## New features
+**New features:**
 
 - Windows ARM64 is now supported
 
-# Koffi 1.2.3
+## Koffi 1.2.3
 
-## New features
+**New features:**
 
 - A prebuilt binary for macOS ARM64 (M1) is now included
 
-# Koffi 1.2.1
+## Koffi 1.2.1
 
 This entry documents changes since version 1.1.0.
 
-## New features
+**New features:**
 
 - JS functions can be used as C callbacks (cdecl, stdcall) on all platforms
 - RISC-V 64 LP64D ABI is supported (LP64 is untested)
@@ -51,7 +83,7 @@ This entry documents changes since version 1.1.0.
 - Transparent conversion between C buffers and strings
 - Tentative support for Windows ARM64 (untested)
 
-## Main fixes
+**Main fixes:**
 
 - Fix excessive stack alignment of structs on x86 platforms
 - Fix potential problems with big int64_t/uint64_t values

package/doc/benchmarks.md

@@ -1,11 +1,15 @@
 # Benchmarks
 
-Here is a quick overview of the execution time of Koffi calls on three test cases (one based around rand, one based on atoi and one based on Raylib) compared to theoretical ideal implementations.
+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><img src="_static/bench_linux.png" alt="Linux performance" style="width: 350px;"/></td>
-        <td><img src="_static/bench_windows.png" alt="Windows performance" style="width: 350px;"/></td>
+        <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>
     </tr>
 </table>
 
@@ -15,7 +19,7 @@ These results are detailed and explained below, and compared to node-ffi/node-ff
 
 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.
+- 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
 
@@ -25,21 +29,21 @@ Because rand is a pretty small function, the FFI overhead is clearly visible.
 
 The results below were measured on my x86_64 Linux machine (AMD® Ryzen™ 7 4700U):
 
-Benchmark     | Iterations | Total time  | Overhead
-------------- | ---------- | ----------- | ----------
-rand_napi     | 20000000   | 1.44s       | (baseline)
-rand_koffi    | 20000000   | 2.60s       | x1.81
-rand_node_ffi | 20000000   | 107.58s     | x75
+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%
 
 ### Windows x86_64
 
 The results below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460):
 
-Benchmark     | Iterations | Total time  | Overhead
-------------- | ---------- | ----------- | ----------
-rand_napi     | 20000000   | 2.10s       | (baseline)
-rand_koffi    | 20000000   | 3.87s       | x1.84
-rand_node_ffi | 20000000   | 87.84s      | x42
+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%
 
 ## atoi results
 
@@ -51,21 +55,21 @@ Because rand is a pretty small function, the FFI overhead is clearly visible.
 
 The results below were measured on my x86_64 Linux machine (AMD® Ryzen™ 7 4700U):
 
-Benchmark     | Iterations | Total time  | Overhead
-------------- | ---------- | ----------- | ----------
-atoi_napi     | 20000000   | 2.97s       | (baseline)
-atoi_koffi    | 20000000   | 5.07s       | x1.71
-atoi_node_ffi | 20000000   | 693.16s     | x233
+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%
 
 ### Windows x86_64
 
 The results below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460):
 
-Benchmark     | Iterations | Total time  | Overhead
-------------- | ---------- | ----------- | ----------
-atoi_napi     | 20000000   | 2.97s       | (baseline)
-atoi_koffi    | 20000000   | 5.91s       | x1.99
-atoi_node_ffi | 20000000   | 479.34s     | x161
+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%
 
 ## Raylib results
 
@@ -78,23 +82,23 @@ This benchmark uses the CPU-based image drawing functions in Raylib. The calls a
 
 The results below were measured on my x86_64 Linux machine (AMD® Ryzen™ 7 4700U):
 
-Benchmark          | Iterations | Total time  | Overhead
----------------    | ---------- | ----------- | ----------
-raylib_cc          | 100        | 9.31s       | (baseline)
-raylib_node_raylib | 100        | 10.90s      | x1.17
-raylib_koffi       | 100        | 12.86s      | x1.38
-raylib_node_ffi    | 100        | 35.76s      | x3.84
+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%
 
 ### Windows x86_64
 
 The results below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460):
 
-Benchmark          | Iterations | Total time  | Overhead
----------------    | ---------- | ----------- | ----------
-raylib_cc          | 100        | 10.67s      | (baseline)
-raylib_node_raylib | 100        | 12.05s      | x1.13
-raylib_koffi       | 100        | 14.84s      | x1.39
-raylib_node_ffi    | 100        | 44.63s      | x4.18
+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%
 
 ## Running benchmarks
 

package/doc/changes.md

@@ -0,0 +1,2 @@
+```{include} ../ChangeLog.md
+```

package/doc/conf.py

@@ -1,10 +1,17 @@
+import json
+import os
+
 # -- Project information -----------------------------------------------------
 
 project = 'Koffi'
 copyright = '2022, Niels Martignène'
 author = 'Niels Martignène'
-version = '1.3.2'
-revision = '1.3.2'
+
+with open(os.path.dirname(__file__) + '/../package.json') as f:
+    config = json.load(f)
+
+    version = config['version']
+    revision = config['version']
 
 # -- General configuration ---------------------------------------------------
 
@@ -20,7 +27,7 @@ exclude_patterns = []
 
 # -- Options for HTML output -------------------------------------------------
 
-html_title = 'Koffi'
+html_title = project
 
 html_theme = 'furo'
 

package/doc/contribute.md

@@ -10,6 +10,15 @@ Go here: https://github.com/Koromix/luigi/issues
 
 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:
@@ -113,3 +122,10 @@ The following features are also planned eventually, not necessarily in that orde
 - 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
+
+## 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.

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

@@ -1,11 +1,15 @@
 # Benchmarks
 
-Here is a quick overview of the execution time of Koffi calls on three test cases (one based around rand, one based on atoi and one based on Raylib) compared to theoretical ideal implementations.
+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><img src="_static/bench_linux.png" alt="Linux performance" style="width: 350px;"/></td>
-        <td><img src="_static/bench_windows.png" alt="Windows performance" style="width: 350px;"/></td>
+        <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>
     </tr>
 </table>
 
@@ -15,7 +19,7 @@ These results are detailed and explained below, and compared to node-ffi/node-ff
 
 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.
+- 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
 
@@ -25,21 +29,21 @@ Because rand is a pretty small function, the FFI overhead is clearly visible.
 
 The results below were measured on my x86_64 Linux machine (AMD® Ryzen™ 7 4700U):
 
-Benchmark     | Iterations | Total time  | Overhead
-------------- | ---------- | ----------- | ----------
-rand_napi     | 20000000   | 1.44s       | (baseline)
-rand_koffi    | 20000000   | 2.60s       | x1.81
-rand_node_ffi | 20000000   | 107.58s     | x75
+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%
 
 ### Windows x86_64
 
 The results below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460):
 
-Benchmark     | Iterations | Total time  | Overhead
-------------- | ---------- | ----------- | ----------
-rand_napi     | 20000000   | 2.10s       | (baseline)
-rand_koffi    | 20000000   | 3.87s       | x1.84
-rand_node_ffi | 20000000   | 87.84s      | x42
+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%
 
 ## atoi results
 
@@ -51,21 +55,21 @@ Because rand is a pretty small function, the FFI overhead is clearly visible.
 
 The results below were measured on my x86_64 Linux machine (AMD® Ryzen™ 7 4700U):
 
-Benchmark     | Iterations | Total time  | Overhead
-------------- | ---------- | ----------- | ----------
-atoi_napi     | 20000000   | 2.97s       | (baseline)
-atoi_koffi    | 20000000   | 5.07s       | x1.71
-atoi_node_ffi | 20000000   | 693.16s     | x233
+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%
 
 ### Windows x86_64
 
 The results below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460):
 
-Benchmark     | Iterations | Total time  | Overhead
-------------- | ---------- | ----------- | ----------
-atoi_napi     | 20000000   | 2.97s       | (baseline)
-atoi_koffi    | 20000000   | 5.91s       | x1.99
-atoi_node_ffi | 20000000   | 479.34s     | x161
+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%
 
 ## Raylib results
 
@@ -78,23 +82,23 @@ This benchmark uses the CPU-based image drawing functions in Raylib. The calls a
 
 The results below were measured on my x86_64 Linux machine (AMD® Ryzen™ 7 4700U):
 
-Benchmark          | Iterations | Total time  | Overhead
----------------    | ---------- | ----------- | ----------
-raylib_cc          | 100        | 9.31s       | (baseline)
-raylib_node_raylib | 100        | 10.90s      | x1.17
-raylib_koffi       | 100        | 12.86s      | x1.38
-raylib_node_ffi    | 100        | 35.76s      | x3.84
+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%
 
 ### Windows x86_64
 
 The results below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460):
 
-Benchmark          | Iterations | Total time  | Overhead
----------------    | ---------- | ----------- | ----------
-raylib_cc          | 100        | 10.67s      | (baseline)
-raylib_node_raylib | 100        | 12.05s      | x1.13
-raylib_koffi       | 100        | 14.84s      | x1.39
-raylib_node_ffi    | 100        | 44.63s      | x4.18
+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%
 
 ## Running benchmarks
 

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

@@ -0,0 +1,2 @@
+```{include} ../ChangeLog.md
+```

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

@@ -10,6 +10,15 @@ Go here: https://github.com/Koromix/luigi/issues
 
 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:
@@ -113,3 +122,10 @@ The following features are also planned eventually, not necessarily in that orde
 - 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
+
+## 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.