koffi 2.0.0 → 2.1.0-beta.2

package/CMakeLists.txt

@@ -15,11 +15,6 @@ 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)
 
@@ -36,7 +31,7 @@ if(MSVC)
         enable_language(ASM_MASM)
     endif()
 else()
-    add_compile_options(-Wall -Wextra -Wno-missing-field-initializers -Wno-unused-parameter)
+    add_compile_options(-Wall -Wextra -Wno-missing-field-initializers -Wno-unused-parameter -Wswitch -Werror=switch)
     if(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
         add_compile_options(-Wno-unknown-warning-option)
     endif()
@@ -126,6 +121,4 @@ if(NOT MSVC OR CMAKE_C_COMPILER_ID MATCHES "[Cc]lang")
         target_compile_options(koffi PRIVATE -fno-finite-loops)
     endif()
 endif()
-if(USE_LTO)
-    set_target_properties(koffi PROPERTIES INTERPROCEDURAL_OPTIMIZATION TRUE)
-endif()
+enable_unity_build(koffi)

package/ChangeLog.md

@@ -2,12 +2,35 @@
 
 ## History
 
+### Koffi 2.1.0 (in beta)
+
+**Main changes:**
+
+- Add [koffi.as()](functions.md#polymorphic-parameters) to support polymorphic APIs based on `void *` parameters
+- Add [endian-sensitive integer types](types.md#endian-sensitive-types): `intX_le_t`, `intX_be_t`
+- Accept typed arrays for `void *` parameters
+- Introduce `koffi.opaque()` to replace `koffi.handle()` (which remains supported until Koffi 3.0)
+
+**Other changes:**
+
+- 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)
+- Various documentation fixes and improvements
+
+### Koffi 2.0.1
+
+**Main changes:**
+
+- Return `undefined` (instead of null) for `void` functions
+
 ### Koffi 2.0.0
 
 **Major new features:**
 
-- Add disposable types for automatic disposal of C values (such as heap-allocated strings)
-- Add support for registered callbacks, that can be called after the initial FFI call
+- Add [disposable types](functions.md#heap-allocated-values) for automatic disposal of C values (such as heap-allocated strings)
+- Add support for [registered callbacks](functions.md#registered-callbacks), that can be called after the initial FFI call
 - Support named pointer types
 - Support complex type specifications outside of prototype parser
 

package/benchmark/atoi_koffi.js

@@ -26,14 +26,14 @@ let sum = 0;
 main();
 
 function main() {
-    let iterations = 20000000;
+    let time = 5000;
 
     if (process.argv.length >= 3) {
-        iterations = parseInt(process.argv[2], 10);
-        if (Number.isNaN(iterations))
+        time = parseFloat(process.argv[2]) * 1000;
+        if (Number.isNaN(time))
             throw new Error('Not a valid number');
-        if (iterations < 1)
-            throw new Error('Value must be positive');
+        if (time < 0)
+            throw new Error('Time must be positive');
     }
 
     let lib = koffi.load(process.platform == 'win32' ? 'msvcrt.dll' : null);
@@ -41,11 +41,15 @@ function main() {
     const atoi = lib.cdecl('atoi', 'int', ['str']);
 
     let start = performance.now();
+    let iterations = 0;
 
-    for (let i = 0; i < iterations; i++) {
-        sum += atoi(strings[i % strings.length]);
+    while (performance.now() - start < time) {
+        for (let i = 0; i < 1000000; i++)
+            sum += atoi(strings[i % strings.length]);
+
+        iterations += 1000000;
     }
 
-    let time = performance.now() - start;
+    time = performance.now() - start;
     console.log(JSON.stringify({ iterations: iterations, time: Math.round(time) }));
 }

package/benchmark/atoi_napi.js

@@ -26,22 +26,26 @@ let sum = 0;
 main();
 
 function main() {
-    let iterations = 20000000;
+    let time = 5000;
 
     if (process.argv.length >= 3) {
-        iterations = parseInt(process.argv[2], 10);
-        if (Number.isNaN(iterations))
+        time = parseFloat(process.argv[2]) * 1000;
+        if (Number.isNaN(time))
             throw new Error('Not a valid number');
-        if (iterations < 1)
-            throw new Error('Value must be positive');
+        if (time < 0)
+            throw new Error('Time must be positive');
     }
 
     let start = performance.now();
+    let iterations = 0;
 
-    for (let i = 0; i < iterations; i++) {
-        sum += atoi.atoi(strings[i % strings.length]);
+    while (performance.now() - start < time) {
+        for (let i = 0; i < 1000000; i++)
+            sum += atoi.atoi(strings[i % strings.length]);
+
+        iterations += 1000000;
     }
 
-    let time = performance.now() - start;
+    time = performance.now() - start;
     console.log(JSON.stringify({ iterations: iterations, time: Math.round(time) }));
 }

package/benchmark/atoi_node_ffi.js

@@ -28,14 +28,14 @@ let sum = 0;
 main();
 
 async function main() {
-    let iterations = 200000;
+    let time = 5000;
 
     if (process.argv.length >= 3) {
-        iterations = parseInt(process.argv[2], 10);
-        if (Number.isNaN(iterations))
+        time = parseFloat(process.argv[2]) * 1000;
+        if (Number.isNaN(time))
             throw new Error('Not a valid number');
-        if (iterations < 1)
-            throw new Error('Value must be positive');
+        if (time < 0)
+            throw new Error('Time must be positive');
     }
 
     const lib = ffi.Library(process.platform == 'win32' ? 'msvcrt.dll' : null, {
@@ -43,14 +43,15 @@ async function main() {
     });
 
     let start = performance.now();
+    let iterations = 0;
 
-    for (let i = 0; i < iterations; i++) {
-        if (i % 1000000 == 0)
-            await new Promise(resolve => setTimeout(resolve, 0));
+    while (performance.now() - start < time) {
+        for (let i = 0; i < 1000000; i++)
+            sum += lib.atoi(strings[i % strings.length]);
 
-        sum += lib.atoi(strings[i % strings.length]);
+        iterations += 1000000;
     }
 
-    let time = performance.now() - start;
+    time = performance.now() - start;
     console.log(JSON.stringify({ iterations: iterations, time: Math.round(time) }));
 }

package/benchmark/raylib_cc.cc

@@ -18,10 +18,10 @@ namespace RG {
 
 int Main(int argc, char **argv)
 {
-    int iterations = 360000;
+    int time = 5000;
 
     if (argc >= 2) {
-        if (!ParseInt(argv[1], &iterations))
+        if (!ParseInt(argv[1], &time))
             return 1;
     }
 
@@ -34,15 +34,16 @@ int Main(int argc, char **argv)
     Font font = GetFontDefault();
 
     int64_t start = GetMonotonicTime();
+    int64_t iterations = 0;
 
-    for (int i = 0; i < iterations; i += 3600) {
+    while (GetMonotonicTime() - start < time) {
         ImageClearBackground(&img, Color { 0, 0, 0, 255 });
 
-        for (int j = 0; j < 3600; j++) {
+        for (int i = 0; i < 3600; i++) {
             const char *text = "Hello World!";
             float text_width = MeasureTextEx(font, text, 10, 1).x;
 
-            double angle = (j * 7) * PI / 180;
+            double angle = (i * 7) * PI / 180;
             Color color = {
                 (unsigned char)(127.5 + 127.5 * sin(angle)),
                 (unsigned char)(127.5 + 127.5 * sin(angle + PI / 2)),
@@ -50,16 +51,18 @@ int Main(int argc, char **argv)
                 255
             };
             Vector2 pos = {
-                (float)((img.width / 2 - text_width / 2) + j * 0.1 * cos(angle - PI / 2)),
-                (float)((img.height / 2 - 16) + j * 0.1 * sin(angle - PI / 2))
+                (float)((img.width / 2 - text_width / 2) + i * 0.1 * cos(angle - PI / 2)),
+                (float)((img.height / 2 - 16) + i * 0.1 * sin(angle - PI / 2))
             };
 
             ImageDrawTextEx(&img, font, text, pos, 10, 1, color);
         }
+
+        iterations += 3600;
     }
 
-    int64_t time = GetMonotonicTime() - start;
-    PrintLn("{\"iterations\": %1,\"time\": %2}", iterations, time);
+    time = GetMonotonicTime() - start;
+    PrintLn("{\"iterations\": %1, \"time\": %2}", iterations, time);
 
     return 0;
 }

package/benchmark/raylib_koffi.js

@@ -14,7 +14,6 @@
 // along with this program. If not, see https://www.gnu.org/licenses/.
 
 const koffi = require('./build/koffi.node');
-const path = require('path');
 
 const Color = koffi.struct('Color', {
     r: 'uchar',
@@ -71,17 +70,17 @@ const Font = koffi.struct('Font', {
 main();
 
 function main() {
-    let iterations = 360000;
+    let time = 5000;
 
     if (process.argv.length >= 3) {
-        iterations = parseInt(process.argv[2], 10);
-        if (Number.isNaN(iterations))
+        time = parseFloat(process.argv[2]) * 1000;
+        if (Number.isNaN(time))
             throw new Error('Not a valid number');
-        if (iterations < 1)
-            throw new Error('Value must be positive');
+        if (time < 0)
+            throw new Error('Time must be positive');
     }
 
-    let lib_filename = path.dirname(__filename) + '/build/raylib' + koffi.extension;
+    let lib_filename = __dirname + '/build/raylib' + koffi.extension;
     let lib = koffi.load(lib_filename);
 
     const InitWindow = lib.cdecl('InitWindow', 'void', ['int', 'int', 'str']);
@@ -103,15 +102,16 @@ function main() {
     let font = GetFontDefault();
 
     let start = performance.now();
+    let iterations = 0;
 
-    for (let i = 0; i < iterations; i += 3600) {
+    while (performance.now() - start < time) {
         ImageClearBackground(img, { r: 0, g: 0, b: 0, a: 255 });
 
-        for (let j = 0; j < 3600; j++) {
+        for (let i = 0; i < 3600; i++) {
             let text = 'Hello World!';
             let text_width = MeasureTextEx(font, text, 10, 1).x;
 
-            let angle = (j * 7) * Math.PI / 180;
+            let angle = (i * 7) * Math.PI / 180;
             let color = {
                 r: 127.5 + 127.5 * Math.sin(angle),
                 g: 127.5 + 127.5 * Math.sin(angle + Math.PI / 2),
@@ -119,14 +119,16 @@ function main() {
                 a: 255
             };
             let pos = {
-                x: (img.width / 2 - text_width / 2) + j * 0.1 * Math.cos(angle - Math.PI / 2),
-                y: (img.height / 2 - 16) + j * 0.1 * Math.sin(angle - Math.PI / 2)
+                x: (img.width / 2 - text_width / 2) + i * 0.1 * Math.cos(angle - Math.PI / 2),
+                y: (img.height / 2 - 16) + i * 0.1 * Math.sin(angle - Math.PI / 2)
             };
 
             ImageDrawTextEx(img, font, text, pos, 10, 1, color);
         }
+
+        iterations += 3600;
     }
 
-    let time = performance.now() - start;
+    time = performance.now() - start;
     console.log(JSON.stringify({ iterations: iterations, time: Math.round(time) }));
 }

package/benchmark/raylib_node_ffi.js

@@ -17,7 +17,6 @@ const ref = require('ref-napi');
 const ffi = require('ffi-napi');
 const struct = require('ref-struct-di')(ref);
 const koffi = require('./build/koffi.node');
-const path = require('path');
 
 const Color = struct({
     r: 'uchar',
@@ -87,17 +86,17 @@ const Font = struct({
 main();
 
 function main() {
-    let iterations = 180000;
+    let time = 5000;
 
     if (process.argv.length >= 3) {
-        iterations = parseInt(process.argv[2], 10);
-        if (Number.isNaN(iterations))
+        time = parseFloat(process.argv[2]) * 1000;
+        if (Number.isNaN(time))
             throw new Error('Not a valid number');
-        if (iterations < 1)
-            throw new Error('Value must be positive');
+        if (time < 0)
+            throw new Error('Time must be positive');
     }
 
-    let lib_filename = path.dirname(__filename) + '/build/raylib' + koffi.extension;
+    let lib_filename = __dirname + '/build/raylib' + koffi.extension;
 
     const r = ffi.Library(lib_filename, {
         InitWindow: ['void', ['int', 'int', 'string']],
@@ -121,15 +120,16 @@ function main() {
     let font = r.GetFontDefault();
 
     let start = performance.now();
+    let iterations = 0;
 
-    for (let i = 0; i < iterations; i += 3600) {
+    while (performance.now() - start < time) {
         r.ImageClearBackground(imgp, new Color({ r: 0, g: 0, b: 0, a: 255 }));
 
-        for (let j = 0; j < 3600; j++) {
+        for (let i = 0; i < 3600; i++) {
             let text = 'Hello World!';
             let text_width = r.MeasureTextEx(font, text, 10, 1).x;
 
-            let angle = (j * 7) * Math.PI / 180;
+            let angle = (i * 7) * Math.PI / 180;
             let color = new Color({
                 r: 127.5 + 127.5 * Math.sin(angle),
                 g: 127.5 + 127.5 * Math.sin(angle + Math.PI / 2),
@@ -137,14 +137,16 @@ function main() {
                 a: 255
             });
             let pos = new Vector2({
-                x: (img.width / 2 - text_width / 2) + j * 0.1 * Math.cos(angle - Math.PI / 2),
-                y: (img.height / 2 - 16) + j * 0.1 * Math.sin(angle - Math.PI / 2)
+                x: (img.width / 2 - text_width / 2) + i * 0.1 * Math.cos(angle - Math.PI / 2),
+                y: (img.height / 2 - 16) + i * 0.1 * Math.sin(angle - Math.PI / 2)
             });
 
             r.ImageDrawTextEx(imgp, font, text, pos, 10, 1, color);
         }
+
+        iterations += 3600;
     }
 
-    let time = performance.now() - start;
+    time = performance.now() - start;
     console.log(JSON.stringify({ iterations: iterations, time: Math.round(time) }));
 }

package/benchmark/raylib_node_raylib.js

@@ -18,14 +18,14 @@ const r = require('raylib');
 main();
 
 function main() {
-    let iterations = 360000;
+    let time = 5000;
 
     if (process.argv.length >= 3) {
-        iterations = parseInt(process.argv[2], 10);
-        if (Number.isNaN(iterations))
+        time = parseFloat(process.argv[2]) * 1000;
+        if (Number.isNaN(time))
             throw new Error('Not a valid number');
-        if (iterations < 1)
-            throw new Error('Value must be positive');
+        if (time < 0)
+            throw new Error('Time must be positive');
     }
 
     // We need to call InitWindow before using anything else (such as fonts)
@@ -37,15 +37,16 @@ function main() {
     let font = r.GetFontDefault();
 
     let start = performance.now();
+    let iterations = 0;
 
-    for (let i = 0; i < iterations; i += 3600) {
+    while (performance.now() - start < time) {
         r.ImageClearBackground(img, { r: 0, g: 0, b: 0, a: 255 });
 
-        for (let j = 0; j < 3600; j++) {
+        for (let i = 0; i < 3600; i++) {
             let text = 'Hello World!';
             let text_width = r.MeasureTextEx(font, text, 10, 1).x;
 
-            let angle = (j * 7) * Math.PI / 180;
+            let angle = (i * 7) * Math.PI / 180;
             let color = {
                 r: 127.5 + 127.5 * Math.sin(angle),
                 g: 127.5 + 127.5 * Math.sin(angle + Math.PI / 2),
@@ -53,14 +54,16 @@ function main() {
                 a: 255
             };
             let pos = {
-                x: (img.width / 2 - text_width / 2) + j * 0.1 * Math.cos(angle - Math.PI / 2),
-                y: (img.height / 2 - 16) + j * 0.1 * Math.sin(angle - Math.PI / 2)
+                x: (img.width / 2 - text_width / 2) + i * 0.1 * Math.cos(angle - Math.PI / 2),
+                y: (img.height / 2 - 16) + i * 0.1 * Math.sin(angle - Math.PI / 2)
             };
 
             r.ImageDrawTextEx(img, font, text, pos, 10, 1, color);
         }
+
+        iterations += 3600;
     }
 
-    let time = performance.now() - start;
+    time = performance.now() - start;
     console.log(JSON.stringify({ iterations: iterations, time: Math.round(time) }));
 }

package/doc/benchmarks.md

@@ -10,8 +10,8 @@ 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_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>
+        <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>
 

package/doc/changes.md

@@ -10,7 +10,7 @@ The API was changed in 2.x in a few ways, in order to reduce some excessively "m
 You may need to change your code if you use:
 
 - Callback functions
-- Opaque handles
+- Opaque types
 - `koffi.introspect()`
 
 #### Callback types
@@ -66,33 +66,36 @@ 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
+#### 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, you must use them through a pointer, and use an array for output parameters.
+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.
 
-For functions that return handles or pass them by parameter:
+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('FILE fopen(const char *path, const char *mode)');
-const fclose = lib.func('int fclose(FILE stream)');
+const fopen = lib.func('fopen', 'FILE', ['str', 'str']);
+const fopen = lib.func('fclose', 'int', ['FILE']);
 
-let fp = fopen('touch', 'wb');
+let fp = fopen('EMPTY', 'wb');
 if (!fp)
     throw new Error('Failed to open file');
 fclose(fp);
 ```
 
 ```js
-// Koffi 2.x
+// Koffi 2.1
 
-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)');
+// 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('touch', 'wb');
+let fp = fopen('EMPTY', 'wb');
 if (!fp)
     throw new Error('Failed to open file');
 fclose(fp);
@@ -103,10 +106,10 @@ For functions that set opaque handles through output parameters (such as `sqlite
 ```js
 // Koffi 1.x
 
-const sqlite3_db = koffi.handle('sqlite3_db');
+const sqlite3 = koffi.handle('sqlite3');
 
-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 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;
@@ -120,12 +123,13 @@ sqlite3_close_v2(db);
 ```
 
 ```js
-// Koffi 2.x
+// Koffi 2.1
 
-const sqlite3_db = koffi.handle('sqlite3_db');
+// If you use Koffi 2.0: const sqlite3 = koffi.handle('sqlite3');
+const sqlite3 = koffi.opaque('sqlite3');
 
-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 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;

package/doc/conf.py

@@ -21,7 +21,7 @@ extensions = [
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ['templates']
 
 exclude_patterns = []
 
@@ -48,6 +48,19 @@ html_link_suffix = ''
 
 html_css_files = ['custom.css']
 
+html_sidebars = {
+    "**": [
+        "sidebar/brand.html",
+        "sidebar/search.html",
+        "sidebar/scroll-start.html",
+        "sidebar/navigation.html",
+        "sidebar/ethical-ads.html",
+        "badges.html",
+        "sidebar/scroll-end.html",
+        "sidebar/variant-selector.html"
+    ]
+}
+
 # -- MyST parser options -------------------------------------------------
 
 myst_enable_extensions = [