koffi 1.3.11 → 2.0.1

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

@@ -1,4 +1,4 @@
-# Function calls
+# Functions
 
 ## Function definitions
 
@@ -158,20 +158,22 @@ 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');
+const sqlite3 = koffi.handle('sqlite3');
 
 // Use koffi.out() on a double pointer to copy out (from C to JS) after the call
-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('sqlite3_open_v2', 'int', ['str', koffi.out(koffi.pointer(sqlite3, 2)), 'int', 'str']);
+const sqlite3_close_v2 = lib.func('sqlite3_close_v2', 'int', [koffi.pointer(sqlite3)]);
 
 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);
 ```
 
@@ -181,7 +183,7 @@ Some C functions return heap-allocated values directly or through output paramet
 
 For opaque handles, such as FILE, this does not matter because you will explicitly call `fclose()` on them. But some values (such as strings) get implicitly converted by Koffi, and you lose access to the original pointer. This creates a leak if the string is heap-allocated.
 
-To avoid this, you can instruct Koffi to call a function on the original pointer once the conversion is done, by creating a disposable type with `koffi.dispose(name, type, func)`. This creates a type derived from another type, the only difference being that *func* gets called with the original pointer once the value has been converted and is not needed anymore.
+To avoid this, you can instruct Koffi to call a function on the original pointer once the conversion is done, by creating a **disposable type** with `koffi.dispose(name, type, func)`. This creates a type derived from another type, the only difference being that *func* gets called with the original pointer once the value has been converted and is not needed anymore.
 
 The *name* can be omitted to create an anonymous disposable type. If *func* is omitted or is null, Koffi will use `koffi.free(ptr)` (which calls the standard C library *free* function under the hood).
 
@@ -197,7 +199,7 @@ The following example illustrates the use of a disposable type derived from *str
 const koffi = require('koffi');
 const lib = koffi.load('libc.so.6');
 
-// You can also use: const strdup = lib.func('const char *! asprintf(const char *str)')
+// You can also use: const strdup = lib.func('const char *! strdup(const char *str)')
 const HeapStr = koffi.disposable('str');
 const strdup = lib.cdecl('strdup', HeapStr, ['str']);
 
@@ -205,7 +207,7 @@ let copy = strdup('Hello!');
 console.log(copy); // Prints Hello!
 ```
 
-When you declare functions with the [prototype-like syntax](#c-like-prototypes), you can either use named disposables types or use the '!' shortcut qualifier with compatibles types, as shown in the example below. This qualifier creates an anonymous disposable type that calls `koffi.free(ptr)`.
+When you declare functions with the [prototype-like syntax](#c-like-prototypes), you can either use named disposable types or use the '!' shortcut qualifier with compatibles types, as shown in the example below. This qualifier creates an anonymous disposable type that calls `koffi.free(ptr)`.
 
 ```js
 const koffi = require('koffi');
@@ -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`.
@@ -513,18 +515,29 @@ Koffi can also convert JS strings to fixed-sized arrays in the following cases:
 
 The reverse case is also true, Koffi can convert a C fixed-size buffer to a JS string. This happens by default for char, char16 and char16_t arrays, but you can also explicitly ask for this with the `string` array hint (e.g. `koffi.array('char', 8, 'string')`).
 
-## Type introspection
+## Disposable types
+
+Disposable types allow you to register a function that will automatically called after each C to JS conversion performed by Koffi. This can be used to avoid leaking heap-allocated strings, for example.
+
+Read the documentation for [disposable types](functions.md#heap-allocated-values) on the page about function calls.
+
+## Utility functions
+
+### Type introspection
 
 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 +547,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 aliases
+
+You can alias a type with `koffi.alias(name, type)`. Aliased types are completely equivalent.

package/doc/dist/html/benchmarks.html

@@ -165,13 +165,17 @@
 <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>
 <li class="toctree-l1"><a class="reference internal" href="changes">Changelog</a></li>
 </ul>
 
+</div>
+<div style="text-align: center; margin-top: 2em;">
+    <a href="https://github.com/Koromix/luigi/tree/master/koffi"><img src="https://img.shields.io/badge/GitHub-Koffi-ff6600" alt="GitHub"/></a>
+    <a href="https://github.com/Koromix/luigi/tree/master/koffi"><img src="https://img.shields.io/badge/NPM-2.0.0-brightgreen" alt="NPM"/></a>
 </div>
 </div>
 
@@ -215,8 +219,8 @@
 </ul>
 <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>
 <p>These results are detailed and explained below, and compared to node-ffi/node-ffi-napi.</p>

package/doc/dist/html/changes.html

@@ -165,13 +165,17 @@
 <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"><a class="reference internal" href="benchmarks">Benchmarks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="contribute">Contributing</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Changelog</a></li>
 </ul>
 
+</div>
+<div style="text-align: center; margin-top: 2em;">
+    <a href="https://github.com/Koromix/luigi/tree/master/koffi"><img src="https://img.shields.io/badge/GitHub-Koffi-ff6600" alt="GitHub"/></a>
+    <a href="https://github.com/Koromix/luigi/tree/master/koffi"><img src="https://img.shields.io/badge/NPM-2.0.0-brightgreen" alt="NPM"/></a>
 </div>
 </div>
 
@@ -205,15 +209,68 @@
         <article role="main">
           <section id="changelog">
 <h1>Changelog<a class="headerlink" href="#changelog" title="Permalink to this heading">#</a></h1>
+<section id="history">
+<h2>History<a class="headerlink" href="#history" title="Permalink to this heading">#</a></h2>
+<section id="koffi-2-0-0">
+<h3>Koffi 2.0.0<a class="headerlink" href="#koffi-2-0-0" title="Permalink to this heading">#</a></h3>
+<p><strong>Major new features:</strong></p>
+<ul class="simple">
+<li><p>Add <a class="reference internal" href="functions#heap-allocated-values"><span class="std std-doc">disposable types</span></a> for automatic disposal of C values (such as heap-allocated strings)</p></li>
+<li><p>Add support for <a class="reference internal" href="functions#registered-callbacks"><span class="std std-doc">registered callbacks</span></a>, that can be called after the initial FFI call</p></li>
+<li><p>Support named pointer types</p></li>
+<li><p>Support complex type specifications outside of prototype parser</p></li>
+</ul>
+<p><strong>Minor new features:</strong></p>
+<ul class="simple">
+<li><p>Support type aliases with <code class="docutils literal notranslate"><span class="pre">koffi.alias()</span></code></p></li>
+<li><p>Add <code class="docutils literal notranslate"><span class="pre">koffi.resolve()</span></code> to resolve type strings</p></li>
+<li><p>Expose all primitive type aliases in <code class="docutils literal notranslate"><span class="pre">koffi.types</span></code></p></li>
+<li><p>Correctly pass exceptions thrown in JS callbacks</p></li>
+</ul>
+<p><strong>Breaking API changes:</strong></p>
+<ul class="simple">
+<li><p>Change handling of callback types, which must be used through pointers</p></li>
+<li><p>Change handling of opaque handles, which must be used through pointers</p></li>
+<li><p>Support all types in <code class="docutils literal notranslate"><span class="pre">koffi.introspect(type)</span></code></p></li>
+</ul>
+<p>Consult the <a class="reference internal" href="#migration-guide"><span class="std std-doc">migration guide</span></a> for more information.</p>
+</section>
+<section id="koffi-1-3-12">
+<h3>Koffi 1.3.12<a class="headerlink" href="#koffi-1-3-12" title="Permalink to this heading">#</a></h3>
+<p><strong>Main fixes:</strong></p>
+<ul class="simple">
+<li><p>Fix support for Yarn package manager</p></li>
+</ul>
+</section>
+<section id="koffi-1-3-11">
+<h3>Koffi 1.3.11<a class="headerlink" href="#koffi-1-3-11" title="Permalink to this heading">#</a></h3>
+<p><strong>Main fixes:</strong></p>
+<ul class="simple">
+<li><p>Fix broken parsing of <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> when used for first parameter</p></li>
+</ul>
+</section>
+<section id="koffi-1-3-10">
+<h3>Koffi 1.3.10<a class="headerlink" href="#koffi-1-3-10" title="Permalink to this heading">#</a></h3>
+<p><strong>Main fixes:</strong></p>
+<ul class="simple">
+<li><p>Fix support for callbacks with more than 4 parameters on Windows x64</p></li>
+<li><p>Fix support for callbacks with multiple floating-point arguments on ARM32 platforms</p></li>
+<li><p>Fix possibly incorrect conversion for uint32_t callback parameters</p></li>
+</ul>
+<p><strong>Other changes:</strong></p>
+<ul class="simple">
+<li><p>Various documentation fixes and improvements</p></li>
+</ul>
+</section>
 <section id="koffi-1-3-9">
-<h2>Koffi 1.3.9<a class="headerlink" href="#koffi-1-3-9" title="Permalink to this heading">#</a></h2>
+<h3>Koffi 1.3.9<a class="headerlink" href="#koffi-1-3-9" title="Permalink to this heading">#</a></h3>
 <p><strong>Main fixes:</strong></p>
 <ul class="simple">
 <li><p>Fix prebuild compatibility with Electron on Windows x64</p></li>
 </ul>
 </section>
 <section id="koffi-1-3-8">
-<h2>Koffi 1.3.8<a class="headerlink" href="#koffi-1-3-8" title="Permalink to this heading">#</a></h2>
+<h3>Koffi 1.3.8<a class="headerlink" href="#koffi-1-3-8" title="Permalink to this heading">#</a></h3>
 <p><strong>Main changes:</strong></p>
 <ul class="simple">
 <li><p>Prevent callback reuse beyond FFI call</p></li>
@@ -225,7 +282,7 @@
 </ul>
 </section>
 <section id="koffi-1-3-7">
-<h2>Koffi 1.3.7<a class="headerlink" href="#koffi-1-3-7" title="Permalink to this heading">#</a></h2>
+<h3>Koffi 1.3.7<a class="headerlink" href="#koffi-1-3-7" title="Permalink to this heading">#</a></h3>
 <p><strong>Main fixes:</strong></p>
 <ul class="simple">
 <li><p>Fix crash when using callbacks inside structs</p></li>
@@ -239,7 +296,7 @@
 </ul>
 </section>
 <section id="koffi-1-3-6">
-<h2>Koffi 1.3.6<a class="headerlink" href="#koffi-1-3-6" title="Permalink to this heading">#</a></h2>
+<h3>Koffi 1.3.6<a class="headerlink" href="#koffi-1-3-6" title="Permalink to this heading">#</a></h3>
 <p><strong>Main fixes:</strong></p>
 <ul class="simple">
 <li><p>Fix install error with Node &lt; 15 on Windows (build system bug)</p></li>
@@ -252,7 +309,7 @@
 </ul>
 </section>
 <section id="koffi-1-3-5">
-<h2>Koffi 1.3.5<a class="headerlink" href="#koffi-1-3-5" title="Permalink to this heading">#</a></h2>
+<h3>Koffi 1.3.5<a class="headerlink" href="#koffi-1-3-5" title="Permalink to this heading">#</a></h3>
 <p><strong>Main changes:</strong></p>
 <ul class="simple">
 <li><p>Fix memory leak when many async calls are running</p></li>
@@ -265,14 +322,14 @@
 </ul>
 </section>
 <section id="koffi-1-3-4">
-<h2>Koffi 1.3.4<a class="headerlink" href="#koffi-1-3-4" title="Permalink to this heading">#</a></h2>
+<h3>Koffi 1.3.4<a class="headerlink" href="#koffi-1-3-4" title="Permalink to this heading">#</a></h3>
 <p><strong>Main fixes:</strong></p>
 <ul class="simple">
 <li><p>Fix possible OpenBSD i386 crash with <code class="docutils literal notranslate"><span class="pre">(void)</span></code> functions</p></li>
 </ul>
 </section>
 <section id="koffi-1-3-3">
-<h2>Koffi 1.3.3<a class="headerlink" href="#koffi-1-3-3" title="Permalink to this heading">#</a></h2>
+<h3>Koffi 1.3.3<a class="headerlink" href="#koffi-1-3-3" title="Permalink to this heading">#</a></h3>
 <p><strong>Main fixes:</strong></p>
 <ul class="simple">
 <li><p>Fix misconversion of signed integer return value as unsigned</p></li>
@@ -285,7 +342,7 @@
 </ul>
 </section>
 <section id="koffi-1-3-2">
-<h2>Koffi 1.3.2<a class="headerlink" href="#koffi-1-3-2" title="Permalink to this heading">#</a></h2>
+<h3>Koffi 1.3.2<a class="headerlink" href="#koffi-1-3-2" title="Permalink to this heading">#</a></h3>
 <p><strong>Main fixes:</strong></p>
 <ul class="simple">
 <li><p>Support compilation in C++14 mode (graceful degradation)</p></li>
@@ -293,14 +350,14 @@
 </ul>
 </section>
 <section id="koffi-1-3-1">
-<h2>Koffi 1.3.1<a class="headerlink" href="#koffi-1-3-1" title="Permalink to this heading">#</a></h2>
+<h3>Koffi 1.3.1<a class="headerlink" href="#koffi-1-3-1" title="Permalink to this heading">#</a></h3>
 <p><strong>Main fixes:</strong></p>
 <ul class="simple">
 <li><p>The prebuilt binary is tested when Koffi is installed, and a rebuild happens if it fails to load</p></li>
 </ul>
 </section>
 <section id="koffi-1-3-0">
-<h2>Koffi 1.3.0<a class="headerlink" href="#koffi-1-3-0" title="Permalink to this heading">#</a></h2>
+<h3>Koffi 1.3.0<a class="headerlink" href="#koffi-1-3-0" title="Permalink to this heading">#</a></h3>
 <p><strong>Major changes:</strong></p>
 <ul class="simple">
 <li><p>Expand and move documentation to <a class="reference external" href="https://koffi.dev/">https://koffi.dev/</a></p></li>
@@ -317,21 +374,21 @@
 </ul>
 </section>
 <section id="koffi-1-2-4">
-<h2>Koffi 1.2.4<a class="headerlink" href="#koffi-1-2-4" title="Permalink to this heading">#</a></h2>
+<h3>Koffi 1.2.4<a class="headerlink" href="#koffi-1-2-4" title="Permalink to this heading">#</a></h3>
 <p><strong>New features:</strong></p>
 <ul class="simple">
 <li><p>Windows ARM64 is now supported</p></li>
 </ul>
 </section>
 <section id="koffi-1-2-3">
-<h2>Koffi 1.2.3<a class="headerlink" href="#koffi-1-2-3" title="Permalink to this heading">#</a></h2>
+<h3>Koffi 1.2.3<a class="headerlink" href="#koffi-1-2-3" title="Permalink to this heading">#</a></h3>
 <p><strong>New features:</strong></p>
 <ul class="simple">
 <li><p>A prebuilt binary for macOS ARM64 (M1) is now included</p></li>
 </ul>
 </section>
 <section id="koffi-1-2-1">
-<h2>Koffi 1.2.1<a class="headerlink" href="#koffi-1-2-1" title="Permalink to this heading">#</a></h2>
+<h3>Koffi 1.2.1<a class="headerlink" href="#koffi-1-2-1" title="Permalink to this heading">#</a></h3>
 <p>This entry documents changes since version 1.1.0.</p>
 <p><strong>New features:</strong></p>
 <ul class="simple">
@@ -355,6 +412,149 @@
 <li><p>Use slower allocation for big objects instead of failing</p></li>
 </ul>
 </section>
+</section>
+<section id="migration-guide">
+<h2>Migration guide<a class="headerlink" href="#migration-guide" title="Permalink to this heading">#</a></h2>
+<section id="koffi-1-x-to-2-x">
+<h3>Koffi 1.x to 2.x<a class="headerlink" href="#koffi-1-x-to-2-x" title="Permalink to this heading">#</a></h3>
+<p>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.</p>
+<p>You may need to change your code if you use:</p>
+<ul class="simple">
+<li><p>Callback functions</p></li>
+<li><p>Opaque handles</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">koffi.introspect()</span></code></p></li>
+</ul>
+<section id="callback-types">
+<h4>Callback types<a class="headerlink" href="#callback-types" title="Permalink to this heading">#</a></h4>
+<p>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: <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">CallIt(CallbackType</span> <span class="pre">func)</span></code> in Koffi 1.x becomes <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">CallIt(CallbackType</span> <span class="pre">*func)</span></code> in version 2.0 and newer.</p>
+<p>Given the following C code:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;string.h&gt;</span><span class="cp"></span>
+<span class="linenos">2</span>
+<span class="linenos">3</span><span class="kt">int</span><span class="w"> </span><span class="nf">TransferToJS</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">name</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">age</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">cb</span><span class="p">)(</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">str</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">age</span><span class="p">))</span><span class="w"></span>
+<span class="linenos">4</span><span class="p">{</span><span class="w"></span>
+<span class="linenos">5</span><span class="w">    </span><span class="kt">char</span><span class="w"> </span><span class="n">buf</span><span class="p">[</span><span class="mi">64</span><span class="p">];</span><span class="w"></span>
+<span class="linenos">6</span><span class="w">    </span><span class="n">snprintf</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="k">sizeof</span><span class="p">(</span><span class="n">buf</span><span class="p">),</span><span class="w"> </span><span class="s">&quot;Hello %s!&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">str</span><span class="p">);</span><span class="w"></span>
+<span class="linenos">7</span><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">cb</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="n">age</span><span class="p">);</span><span class="w"></span>
+<span class="linenos">8</span><span class="p">}</span><span class="w"></span>
+</pre></div>
+</div>
+<p>The two versions below illustrate the API difference between Koffi 1.x and Koffi 2.x:</p>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="c1">// Koffi 1.x</span>
+<span class="linenos"> 2</span>
+<span class="linenos"> 3</span><span class="kd">const</span> <span class="nx">TransferCallback</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">callback</span><span class="p">(</span><span class="s1">&#39;int TransferCallback(const char *str, int age)&#39;</span><span class="p">);</span>
+<span class="linenos"> 4</span>
+<span class="linenos"> 5</span><span class="kd">const</span> <span class="nx">TransferToJS</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;TransferToJS&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;str&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="nx">TransferCallback</span><span class="p">]);</span>
+<span class="linenos"> 6</span><span class="c1">// Equivalent to: const TransferToJS = lib.func(&#39;int TransferToJS(str s, int x, TransferCallback cb)&#39;);</span>
+<span class="linenos"> 7</span>
+<span class="linenos"> 8</span><span class="kd">let</span> <span class="nx">ret</span> <span class="o">=</span> <span class="nx">TransferToJS</span><span class="p">(</span><span class="s1">&#39;Niels&#39;</span><span class="p">,</span> <span class="mf">27</span><span class="p">,</span> <span class="p">(</span><span class="nx">str</span><span class="p">,</span> <span class="nx">age</span><span class="p">)</span> <span class="p">=&gt;</span> <span class="p">{</span>
+<span class="linenos"> 9</span>    <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">str</span><span class="p">);</span>
+<span class="linenos">10</span>    <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">&#39;Your age is:&#39;</span><span class="p">,</span> <span class="nx">age</span><span class="p">);</span>
+<span class="linenos">11</span>    <span class="k">return</span> <span class="mf">42</span><span class="p">;</span>
+<span class="linenos">12</span><span class="p">});</span>
+<span class="linenos">13</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">ret</span><span class="p">);</span>
+</pre></div>
+</div>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="c1">// Koffi 2.x</span>
+<span class="linenos"> 2</span>
+<span class="linenos"> 3</span><span class="kd">const</span> <span class="nx">TransferCallback</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">callback</span><span class="p">(</span><span class="s1">&#39;int TransferCallback(const char *str, int age)&#39;</span><span class="p">);</span>
+<span class="linenos"> 4</span>
+<span class="linenos"> 5</span><span class="kd">const</span> <span class="nx">TransferToJS</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;TransferToJS&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;str&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">pointer</span><span class="p">(</span><span class="nx">TransferCallback</span><span class="p">)]);</span>
+<span class="linenos"> 6</span><span class="c1">// Equivalent to: const TransferToJS = lib.func(&#39;int TransferToJS(str s, int x, TransferCallback *cb)&#39;);</span>
+<span class="linenos"> 7</span>
+<span class="linenos"> 8</span><span class="kd">let</span> <span class="nx">ret</span> <span class="o">=</span> <span class="nx">TransferToJS</span><span class="p">(</span><span class="s1">&#39;Niels&#39;</span><span class="p">,</span> <span class="mf">27</span><span class="p">,</span> <span class="p">(</span><span class="nx">str</span><span class="p">,</span> <span class="nx">age</span><span class="p">)</span> <span class="p">=&gt;</span> <span class="p">{</span>
+<span class="linenos"> 9</span>    <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">str</span><span class="p">);</span>
+<span class="linenos">10</span>    <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">&#39;Your age is:&#39;</span><span class="p">,</span> <span class="nx">age</span><span class="p">);</span>
+<span class="linenos">11</span>    <span class="k">return</span> <span class="mf">42</span><span class="p">;</span>
+<span class="linenos">12</span><span class="p">});</span>
+<span class="linenos">13</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">ret</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Koffi 1.x only supported <a class="reference internal" href="functions#javascript-callbacks"><span class="std std-doc">transient callbacks</span></a>, you must use Koffi 2.x for registered callbacks.</p>
+</section>
+<section id="opaque-handles">
+<h4>Opaque handles<a class="headerlink" href="#opaque-handles" title="Permalink to this heading">#</a></h4>
+<p>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.</p>
+<p>For functions that return handles or pass them by parameter:</p>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="c1">// Koffi 1.x</span>
+<span class="linenos"> 2</span>
+<span class="linenos"> 3</span><span class="kd">const</span> <span class="nx">FILE</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">handle</span><span class="p">(</span><span class="s1">&#39;FILE&#39;</span><span class="p">);</span>
+<span class="linenos"> 4</span><span class="kd">const</span> <span class="nx">fopen</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;fopen&#39;</span><span class="p">,</span> <span class="s1">&#39;FILE&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;str&#39;</span><span class="p">,</span> <span class="s1">&#39;str&#39;</span><span class="p">]);</span>
+<span class="linenos"> 5</span><span class="kd">const</span> <span class="nx">fopen</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;fclose&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;FILE&#39;</span><span class="p">]);</span>
+<span class="linenos"> 6</span>
+<span class="linenos"> 7</span><span class="kd">let</span> <span class="nx">fp</span> <span class="o">=</span> <span class="nx">fopen</span><span class="p">(</span><span class="s1">&#39;EMPTY&#39;</span><span class="p">,</span> <span class="s1">&#39;wb&#39;</span><span class="p">);</span>
+<span class="linenos"> 8</span><span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">fp</span><span class="p">)</span>
+<span class="linenos"> 9</span>    <span class="k">throw</span> <span class="ow">new</span> <span class="ne">Error</span><span class="p">(</span><span class="s1">&#39;Failed to open file&#39;</span><span class="p">);</span>
+<span class="linenos">10</span><span class="nx">fclose</span><span class="p">(</span><span class="nx">fp</span><span class="p">);</span>
+</pre></div>
+</div>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="c1">// Koffi 2.x</span>
+<span class="linenos"> 2</span>
+<span class="linenos"> 3</span><span class="kd">const</span> <span class="nx">FILE</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">handle</span><span class="p">(</span><span class="s1">&#39;FILE&#39;</span><span class="p">);</span>
+<span class="linenos"> 4</span><span class="kd">const</span> <span class="nx">fopen</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;fopen&#39;</span><span class="p">,</span> <span class="s1">&#39;FILE *&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;str&#39;</span><span class="p">,</span> <span class="s1">&#39;str&#39;</span><span class="p">]);</span>
+<span class="linenos"> 5</span><span class="kd">const</span> <span class="nx">fopen</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;fclose&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;FILE *&#39;</span><span class="p">]);</span>
+<span class="linenos"> 6</span>
+<span class="linenos"> 7</span><span class="kd">let</span> <span class="nx">fp</span> <span class="o">=</span> <span class="nx">fopen</span><span class="p">(</span><span class="s1">&#39;EMPTY&#39;</span><span class="p">,</span> <span class="s1">&#39;wb&#39;</span><span class="p">);</span>
+<span class="linenos"> 8</span><span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">fp</span><span class="p">)</span>
+<span class="linenos"> 9</span>    <span class="k">throw</span> <span class="ow">new</span> <span class="ne">Error</span><span class="p">(</span><span class="s1">&#39;Failed to open file&#39;</span><span class="p">);</span>
+<span class="linenos">10</span><span class="nx">fclose</span><span class="p">(</span><span class="nx">fp</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>For functions that set opaque handles through output parameters (such as <code class="docutils literal notranslate"><span class="pre">sqlite3_open_v2</span></code>), you must now use a single element array as shown below:</p>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="c1">// Koffi 1.x</span>
+<span class="linenos"> 2</span>
+<span class="linenos"> 3</span><span class="kd">const</span> <span class="nx">sqlite3</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">handle</span><span class="p">(</span><span class="s1">&#39;sqlite3&#39;</span><span class="p">);</span>
+<span class="linenos"> 4</span>
+<span class="linenos"> 5</span><span class="kd">const</span> <span class="nx">sqlite3_open_v2</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int sqlite3_open_v2(const char *, _Out_ sqlite3 *db, int, const char *)&#39;</span><span class="p">);</span>
+<span class="linenos"> 6</span><span class="kd">const</span> <span class="nx">sqlite3_close_v2</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int sqlite3_close_v2(sqlite3 db)&#39;</span><span class="p">);</span>
+<span class="linenos"> 7</span>
+<span class="linenos"> 8</span><span class="kd">const</span> <span class="nx">SQLITE_OPEN_READWRITE</span> <span class="o">=</span> <span class="mh">0x2</span><span class="p">;</span>
+<span class="linenos"> 9</span><span class="kd">const</span> <span class="nx">SQLITE_OPEN_CREATE</span> <span class="o">=</span> <span class="mh">0x4</span><span class="p">;</span>
+<span class="linenos">10</span>
+<span class="linenos">11</span><span class="kd">let</span> <span class="nx">db</span> <span class="o">=</span> <span class="p">{};</span>
+<span class="linenos">12</span>
+<span class="linenos">13</span><span class="k">if</span> <span class="p">(</span><span class="nx">sqlite3_open_v2</span><span class="p">(</span><span class="s1">&#39;:memory:&#39;</span><span class="p">,</span> <span class="nx">db</span><span class="p">,</span> <span class="nx">SQLITE_OPEN_READWRITE</span> <span class="o">|</span> <span class="nx">SQLITE_OPEN_CREATE</span><span class="p">,</span> <span class="kc">null</span><span class="p">)</span> <span class="o">!=</span> <span class="mf">0</span><span class="p">)</span>
+<span class="linenos">14</span>    <span class="k">throw</span> <span class="ow">new</span> <span class="ne">Error</span><span class="p">(</span><span class="s1">&#39;Failed to open database&#39;</span><span class="p">);</span>
+<span class="linenos">15</span>
+<span class="linenos">16</span><span class="nx">sqlite3_close_v2</span><span class="p">(</span><span class="nx">db</span><span class="p">);</span>
+</pre></div>
+</div>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="c1">// Koffi 2.x</span>
+<span class="linenos"> 2</span>
+<span class="linenos"> 3</span><span class="kd">const</span> <span class="nx">sqlite3</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">handle</span><span class="p">(</span><span class="s1">&#39;sqlite3&#39;</span><span class="p">);</span>
+<span class="linenos"> 4</span>
+<span class="linenos"> 5</span><span class="kd">const</span> <span class="nx">sqlite3_open_v2</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int sqlite3_open_v2(const char *, _Out_ sqlite3 **db, int, const char *)&#39;</span><span class="p">);</span>
+<span class="linenos"> 6</span><span class="kd">const</span> <span class="nx">sqlite3_close_v2</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int sqlite3_close_v2(sqlite3 *db)&#39;</span><span class="p">);</span>
+<span class="linenos"> 7</span>
+<span class="linenos"> 8</span><span class="kd">const</span> <span class="nx">SQLITE_OPEN_READWRITE</span> <span class="o">=</span> <span class="mh">0x2</span><span class="p">;</span>
+<span class="linenos"> 9</span><span class="kd">const</span> <span class="nx">SQLITE_OPEN_CREATE</span> <span class="o">=</span> <span class="mh">0x4</span><span class="p">;</span>
+<span class="linenos">10</span>
+<span class="linenos">11</span><span class="kd">let</span> <span class="nx">db</span> <span class="o">=</span> <span class="kc">null</span><span class="p">;</span>
+<span class="linenos">12</span>
+<span class="linenos">13</span><span class="kd">let</span> <span class="nx">ptr</span> <span class="o">=</span> <span class="p">[</span><span class="kc">null</span><span class="p">];</span>
+<span class="linenos">14</span><span class="k">if</span> <span class="p">(</span><span class="nx">sqlite3_open_v2</span><span class="p">(</span><span class="s1">&#39;:memory:&#39;</span><span class="p">,</span> <span class="nx">ptr</span><span class="p">,</span> <span class="nx">SQLITE_OPEN_READWRITE</span> <span class="o">|</span> <span class="nx">SQLITE_OPEN_CREATE</span><span class="p">,</span> <span class="kc">null</span><span class="p">)</span> <span class="o">!=</span> <span class="mf">0</span><span class="p">)</span>
+<span class="linenos">15</span>    <span class="k">throw</span> <span class="ow">new</span> <span class="ne">Error</span><span class="p">(</span><span class="s1">&#39;Failed to open database&#39;</span><span class="p">);</span>
+<span class="linenos">16</span><span class="nx">db</span> <span class="o">=</span> <span class="nx">ptr</span><span class="p">[</span><span class="mf">0</span><span class="p">];</span>
+<span class="linenos">17</span>
+<span class="linenos">18</span><span class="nx">sqlite3_close_v2</span><span class="p">(</span><span class="nx">db</span><span class="p">);</span>
+</pre></div>
+</div>
+</section>
+<section id="koffi-introspect">
+<h4>koffi.introspect()<a class="headerlink" href="#koffi-introspect" title="Permalink to this heading">#</a></h4>
+<p>In Koffi 1.x, <code class="docutils literal notranslate"><span class="pre">koffi.introspect()</span></code> would only work with struct types, and return the object passed to <code class="docutils literal notranslate"><span class="pre">koffi.struct()</span></code> to initialize the type. Now this function works with all types.</p>
+<p>You can still get the list of struct members:</p>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span> <span class="nx">StructType</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">struct</span><span class="p">(</span><span class="s1">&#39;StructType&#39;</span><span class="p">,</span> <span class="p">{</span> <span class="nx">dummy</span><span class="o">:</span> <span class="s1">&#39;int&#39;</span> <span class="p">});</span>
+<span class="linenos">2</span>
+<span class="linenos">3</span><span class="c1">// Koffi 1.x</span>
+<span class="linenos">4</span><span class="kd">let</span> <span class="nx">members</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">introspect</span><span class="p">(</span><span class="nx">StructType</span><span class="p">);</span>
+<span class="linenos">5</span>
+<span class="linenos">6</span><span class="c1">// Koffi 2.x</span>
+<span class="linenos">7</span><span class="kd">let</span> <span class="nx">members</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">introspect</span><span class="p">(</span><span class="nx">StructType</span><span class="p">).</span><span class="nx">members</span><span class="p">;</span>
+</pre></div>
+</div>
+</section>
+</section>
+</section>
 </section>
 
         </article>
@@ -407,6 +607,11 @@
           <div class="toc-tree">
             <ul>
 <li><a class="reference internal" href="#">Changelog</a><ul>
+<li><a class="reference internal" href="#history">History</a><ul>
+<li><a class="reference internal" href="#koffi-2-0-0">Koffi 2.0.0</a></li>
+<li><a class="reference internal" href="#koffi-1-3-12">Koffi 1.3.12</a></li>
+<li><a class="reference internal" href="#koffi-1-3-11">Koffi 1.3.11</a></li>
+<li><a class="reference internal" href="#koffi-1-3-10">Koffi 1.3.10</a></li>
 <li><a class="reference internal" href="#koffi-1-3-9">Koffi 1.3.9</a></li>
 <li><a class="reference internal" href="#koffi-1-3-8">Koffi 1.3.8</a></li>
 <li><a class="reference internal" href="#koffi-1-3-7">Koffi 1.3.7</a></li>
@@ -422,6 +627,17 @@
 <li><a class="reference internal" href="#koffi-1-2-1">Koffi 1.2.1</a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#migration-guide">Migration guide</a><ul>
+<li><a class="reference internal" href="#koffi-1-x-to-2-x">Koffi 1.x to 2.x</a><ul>
+<li><a class="reference internal" href="#callback-types">Callback types</a></li>
+<li><a class="reference internal" href="#opaque-handles">Opaque handles</a></li>
+<li><a class="reference internal" href="#koffi-introspect">koffi.introspect()</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
 </ul>
 
           </div>

package/doc/dist/html/contribute.html

@@ -165,13 +165,17 @@
 <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"><a class="reference internal" href="benchmarks">Benchmarks</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Contributing</a></li>
 <li class="toctree-l1"><a class="reference internal" href="changes">Changelog</a></li>
 </ul>
 
+</div>
+<div style="text-align: center; margin-top: 2em;">
+    <a href="https://github.com/Koromix/luigi/tree/master/koffi"><img src="https://img.shields.io/badge/GitHub-Koffi-ff6600" alt="GitHub"/></a>
+    <a href="https://github.com/Koromix/luigi/tree/master/koffi"><img src="https://img.shields.io/badge/NPM-2.0.0-brightgreen" alt="NPM"/></a>
 </div>
 </div>