koffi 1.3.12 → 2.0.0

package/CMakeLists.txt

@@ -113,8 +113,13 @@ endif()
 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
-                                         -fno-delete-null-pointer-checks)
+    if(NOT MSVC)
+        target_compile_options(koffi PRIVATE -fno-exceptions -fno-strict-aliasing -fwrapv
+                                             -fno-delete-null-pointer-checks)
+    else()
+        target_compile_options(koffi PRIVATE -fno-strict-aliasing /clang:-fwrapv
+                                             -fno-delete-null-pointer-checks)
+    endif()
 
     check_cxx_compiler_flag(-fno-finite-loops use_no_finite_loops)
     if(use_no_finite_loops)

package/ChangeLog.md

@@ -1,18 +1,44 @@
 # Changelog
 
-## Koffi 1.3.12
+## History
+
+### 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
+- Support named pointer types
+- Support complex type specifications outside of prototype parser
+
+**Minor new features:**
+
+- Support type aliases with `koffi.alias()`
+- Add `koffi.resolve()` to resolve type strings
+- Expose all primitive type aliases in `koffi.types`
+- Correctly pass exceptions thrown in JS callbacks
+
+**Breaking API changes:**
+
+- Change handling of callback types, which must be used through pointers
+- Change handling of opaque handles, which must be used through pointers
+- Support all types in `koffi.introspect(type)`
+
+Consult the [migration guide](changes.md#migration-guide) for more information.
+
+### Koffi 1.3.12
 
 **Main fixes:**
 
 - Fix support for Yarn package manager
 
-## Koffi 1.3.11
+### Koffi 1.3.11
 
 **Main fixes:**
 
 - Fix broken parsing of `void *` when used for first parameter
 
-## Koffi 1.3.10
+### Koffi 1.3.10
 
 **Main fixes:**
 
@@ -24,13 +50,13 @@
 
 - Various documentation fixes and improvements
 
-## Koffi 1.3.9
+### Koffi 1.3.9
 
 **Main fixes:**
 
 - Fix prebuild compatibility with Electron on Windows x64
 
-## Koffi 1.3.8
+### Koffi 1.3.8
 
 **Main changes:**
 
@@ -41,7 +67,7 @@
 
 - Fix and harmonize a few error messages
 
-## Koffi 1.3.7
+### Koffi 1.3.7
 
 **Main fixes:**
 
@@ -54,7 +80,7 @@
 - Add str/str16 type aliases for string/string16
 - Various documentation fixes and improvements
 
-## Koffi 1.3.6
+### Koffi 1.3.6
 
 **Main fixes:**
 
@@ -66,7 +92,7 @@
 - Prebuild with Clang for Windows x64 and Linux x64 binaries
 - Various documentation improvements
 
-## Koffi 1.3.5
+### Koffi 1.3.5
 
 **Main changes:**
 
@@ -78,13 +104,13 @@
 - Reduce default async memory stack and heap size
 - Various documentation improvements
 
-## Koffi 1.3.4
+### Koffi 1.3.4
 
 **Main fixes:**
 
 - Fix possible OpenBSD i386 crash with `(void)` functions
 
-## Koffi 1.3.3
+### Koffi 1.3.3
 
 **Main fixes:**
 
@@ -96,20 +122,20 @@
 - Disable unsafe compiler optimizations
 - Various documentation improvements
 
-## Koffi 1.3.2
+### 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:**
 
 - 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:**
 
@@ -125,19 +151,19 @@
 - 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:**
 
 - Windows ARM64 is now supported
 
-## Koffi 1.2.3
+### Koffi 1.2.3
 
 **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.
 

package/README.md

@@ -23,6 +23,12 @@ RISC-V 64 [^3]     | ⬜️ *N/A*    | ✅ Yes   | ⬜️ *N/A*    | 🟨 Probab
 
 Go to the web site for more information: https://koffi.dev/
 
+# Project history
+
+You can consult the [changelog](https://koffi.dev/changes) on the official website.
+
+Major version increments can include breaking API changes, use the [migration guide](https://koffi.dev/changes#migration-guide) for more information.
+
 # License
 
 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.

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

@@ -1,2 +1,157 @@
 ```{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 handles
+- `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 handles
+
+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.
+
+For functions that return handles 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)');
+
+let fp = fopen('touch', 'wb');
+if (!fp)
+    throw new Error('Failed to open file');
+fclose(fp);
+```
+
+```js
+// Koffi 2.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)');
+
+let fp = fopen('touch', '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_db = koffi.handle('sqlite3_db');
+
+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 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.x
+
+const sqlite3_db = koffi.handle('sqlite3_db');
+
+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 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/contribute.md

@@ -111,7 +111,6 @@ node qemu.js info debian_x64
 
 The following features and improvements are planned, not necessarily in that order:
 
-- 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

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

@@ -1,2 +1,157 @@
 ```{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 handles
+- `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 handles
+
+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.
+
+For functions that return handles 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)');
+
+let fp = fopen('touch', 'wb');
+if (!fp)
+    throw new Error('Failed to open file');
+fclose(fp);
+```
+
+```js
+// Koffi 2.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)');
+
+let fp = fopen('touch', '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_db = koffi.handle('sqlite3_db');
+
+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 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.x
+
+const sqlite3_db = koffi.handle('sqlite3_db');
+
+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 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/functions.md.txt

@@ -1,4 +1,4 @@
-# Function calls
+# Functions
 
 ## Function definitions
 
@@ -158,7 +158,7 @@ This example opens an in-memory SQLite database, and uses the node-ffi-style fun
 
 ```js
 const koffi = require('koffi');
-const lib = koffi.load('sqlite.so');
+const lib = koffi.load('sqlite3.so');
 
 const sqlite3_db = koffi.handle('sqlite3_db');
 
@@ -169,9 +169,11 @@ const sqlite3_close_v2 = lib.func('sqlite3_close_v2', 'int', [koffi.pointer(sqli
 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)
+let out = [null];
+if (sqlite3_open_v2(':memory:', out, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, null) != 0)
     throw new Error('Failed to open database');
+let db = out[0];
+
 sqlite3_close_v2(db);
 ```
 
@@ -246,6 +248,8 @@ Callbacks **have changed in version 2.0**.
 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.
+
+Consult the [migration guide](changes.md) for more information.
 ```
 
 Koffi only uses predefined static trampolines, and does not need to generate code at runtime, which makes it compatible with platforms with hardened W^X migitations (such as PaX mprotect). However, this imposes some restrictions on the maximum number of callbacks, and their duration.

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

@@ -154,6 +154,8 @@ Opaque handles **have changed in version 2.0**.
 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. This is shown in the example below (look for the call to `ConcatNewOut` in the JS part), and is described in the section on [output parameters](functions.md#output-parameters).
+
+Consult the [migration guide](changes.md) for more information.
 ```
 
 The full example below implements an iterative string builder (concatenator) in C, and uses it from Javascript to output a mix of Hello World and FizzBuzz. The builder is hidden behind an opaque handle, and is created and destroyed using a pair of C functions: `ConcatNew` (or `ConcatNewOut`) and `ConcatFree`.
@@ -520,11 +522,14 @@ Koffi exposes three functions to explore type information:
 - `koffi.sizeof(type)` to get the size of a type
 - `koffi.alignof(type)` to get the alignment of a type
 - `koffi.introspect(type)` to get the definition of a type in an object containing: name, primitive, size, alignment, members (structs), reference (array, pointer) and length (array)
+- `koffi.resolve(type)` to get the resolved type object from a type string
 
 ```{note}
 The value returned by `introspect()` has **changed in version 2.0**.
 
 In Koffi 1.x, it could only be used with struct types and returned the object passed to koffi.struct() with the member names and types.
+
+Consult the [migration guide](changes.md) for more information.
 ```
 
 Just like before, you can refer to primitive types by their name or through `koffi.types`:
@@ -534,3 +539,7 @@ Just like before, you can refer to primitive types by their name or through `kof
 console.log(koffi.sizeof('long'));
 console.log(koffi.sizeof(koffi.types.long));
 ```
+
+## Type aliasing
+
+You can alias a type with `koffi.alias(name, type)`. Aliased types are completely equivalent.

package/doc/dist/html/benchmarks.html

@@ -165,7 +165,7 @@
 <li class="toctree-l1"><a class="reference internal" href="platforms">Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="start">Quick start</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types">Data types</a></li>
-<li class="toctree-l1"><a class="reference internal" href="functions">Function calls</a></li>
+<li class="toctree-l1"><a class="reference internal" href="functions">Functions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="memory">Memory usage</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Benchmarks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="contribute">Contributing</a></li>