npm - koffi - Versions diffs - 1.3.12 → 2.1.0-beta.1 - Mend

koffi 1.3.12 → 2.1.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (104) hide show

package/CMakeLists.txt +8 -10
package/ChangeLog.md +48 -16
package/README.md +6 -0
package/benchmark/atoi_koffi.js +12 -8
package/benchmark/atoi_napi.js +12 -8
package/benchmark/atoi_node_ffi.js +11 -10
package/benchmark/raylib_cc.cc +12 -9
package/benchmark/raylib_koffi.js +15 -13
package/benchmark/raylib_node_ffi.js +15 -13
package/benchmark/raylib_node_raylib.js +14 -11
package/build/qemu/2.1.0-beta.1/koffi_darwin_arm64.tar.gz +0 -0
package/build/qemu/2.1.0-beta.1/koffi_darwin_x64.tar.gz +0 -0
package/build/qemu/2.1.0-beta.1/koffi_freebsd_arm64.tar.gz +0 -0
package/build/qemu/2.1.0-beta.1/koffi_freebsd_ia32.tar.gz +0 -0
package/build/qemu/2.1.0-beta.1/koffi_freebsd_x64.tar.gz +0 -0
package/build/qemu/2.1.0-beta.1/koffi_linux_arm32hf.tar.gz +0 -0
package/build/qemu/2.1.0-beta.1/koffi_linux_arm64.tar.gz +0 -0
package/build/qemu/2.1.0-beta.1/koffi_linux_ia32.tar.gz +0 -0
package/build/qemu/2.1.0-beta.1/koffi_linux_riscv64hf64.tar.gz +0 -0
package/build/qemu/2.1.0-beta.1/koffi_linux_x64.tar.gz +0 -0
package/build/qemu/2.1.0-beta.1/koffi_openbsd_ia32.tar.gz +0 -0
package/build/qemu/2.1.0-beta.1/koffi_openbsd_x64.tar.gz +0 -0
package/build/qemu/2.1.0-beta.1/koffi_win32_arm64.tar.gz +0 -0
package/build/qemu/2.1.0-beta.1/koffi_win32_ia32.tar.gz +0 -0
package/build/qemu/2.1.0-beta.1/koffi_win32_x64.tar.gz +0 -0
package/doc/changes.md +160 -1
package/doc/conf.py +14 -1
package/doc/contribute.md +0 -1
package/doc/dist/doctrees/benchmarks.doctree +0 -0
package/doc/dist/doctrees/changes.doctree +0 -0
package/doc/dist/doctrees/environment.pickle +0 -0
package/doc/dist/doctrees/functions.doctree +0 -0
package/doc/dist/doctrees/index.doctree +0 -0
package/doc/dist/doctrees/types.doctree +0 -0
package/doc/dist/html/.buildinfo +1 -1
package/doc/dist/html/_sources/benchmarks.md.txt +2 -2
package/doc/dist/html/_sources/changes.md.txt +160 -1
package/doc/dist/html/_sources/functions.md.txt +17 -13
package/doc/dist/html/_sources/types.md.txt +87 -35
package/doc/dist/html/benchmarks.html +7 -3
package/doc/dist/html/changes.html +241 -14
package/doc/dist/html/contribute.html +5 -1
package/doc/dist/html/functions.html +30 -23
package/doc/dist/html/genindex.html +5 -1
package/doc/dist/html/index.html +13 -19
package/doc/dist/html/memory.html +7 -3
package/doc/dist/html/objects.inv +0 -0
package/doc/dist/html/platforms.html +6 -2
package/doc/dist/html/search.html +5 -1
package/doc/dist/html/searchindex.js +1 -1
package/doc/dist/html/start.html +5 -1
package/doc/dist/html/types.html +104 -43
package/doc/functions.md +139 -15
package/doc/templates/badges.html +5 -0
package/doc/types.md +108 -40
package/package.json +2 -2
package/qemu/qemu.js +1 -1
package/qemu/registry/machines.json +5 -5
package/qemu/registry/sha256sum.txt +16 -16
package/src/abi_arm32.cc +91 -19
package/src/abi_arm32_fwd.S +121 -57
package/src/abi_arm64.cc +91 -19
package/src/abi_arm64_fwd.S +96 -0
package/src/abi_arm64_fwd.asm +128 -0
package/src/abi_riscv64.cc +89 -19
package/src/abi_riscv64_fwd.S +96 -0
package/src/abi_x64_sysv.cc +94 -22
package/src/abi_x64_sysv_fwd.S +96 -0
package/src/abi_x64_win.cc +89 -19
package/src/abi_x64_win_fwd.asm +128 -0
package/src/abi_x86.cc +94 -19
package/src/abi_x86_fwd.S +96 -0
package/src/abi_x86_fwd.asm +128 -0
package/src/call.cc +128 -78
package/src/call.hh +17 -4
package/src/ffi.cc +514 -145
package/src/ffi.hh +30 -9
package/src/index.js +4 -2
package/src/parser.cc +19 -44
package/src/util.cc +160 -27
package/src/util.hh +7 -2
package/test/async.js +1 -2
package/test/callbacks.js +56 -11
package/test/misc.c +50 -15
package/test/raylib.js +2 -2
package/test/sqlite.js +27 -19
package/test/sync.js +71 -35
package/vendor/libcc/libcc.cc +18 -5
package/vendor/libcc/libcc.hh +70 -23
package/build/qemu/1.3.12/koffi_darwin_arm64.tar.gz +0 -0
package/build/qemu/1.3.12/koffi_darwin_x64.tar.gz +0 -0
package/build/qemu/1.3.12/koffi_freebsd_arm64.tar.gz +0 -0
package/build/qemu/1.3.12/koffi_freebsd_ia32.tar.gz +0 -0
package/build/qemu/1.3.12/koffi_freebsd_x64.tar.gz +0 -0
package/build/qemu/1.3.12/koffi_linux_arm32hf.tar.gz +0 -0
package/build/qemu/1.3.12/koffi_linux_arm64.tar.gz +0 -0
package/build/qemu/1.3.12/koffi_linux_ia32.tar.gz +0 -0
package/build/qemu/1.3.12/koffi_linux_riscv64hf64.tar.gz +0 -0
package/build/qemu/1.3.12/koffi_linux_x64.tar.gz +0 -0
package/build/qemu/1.3.12/koffi_openbsd_ia32.tar.gz +0 -0
package/build/qemu/1.3.12/koffi_openbsd_x64.tar.gz +0 -0
package/build/qemu/1.3.12/koffi_win32_arm64.tar.gz +0 -0
package/build/qemu/1.3.12/koffi_win32_ia32.tar.gz +0 -0
package/build/qemu/1.3.12/koffi_win32_x64.tar.gz +0 -0

package/doc/dist/html/types.html CHANGED Viewed

@@ -3,7 +3,7 @@
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
-<link rel="index" title="Index" href="genindex" /><link rel="search" title="Search" href="search" /><link rel="next" title="Function calls" href="functions" /><link rel="prev" title="Quick start" href="start" />
+<link rel="index" title="Index" href="genindex" /><link rel="search" title="Search" href="search" /><link rel="next" title="Functions" href="functions" /><link rel="prev" title="Quick start" href="start" />
     <meta name="generator" content="sphinx-5.0.1, furo 2022.06.04.1"/>
         <title>Data types - Koffi</title>
@@ -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 current current-page"><a class="current reference internal" href="#">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"><a class="reference internal" href="changes">Changelog</a></li>
 </ul>
+</div>
+<div style="text-align: center; margin-top: 2em;">
+    <a href="https://www.npmjs.com/package/koffi"><img src="https://img.shields.io/badge/NPM-2.0.1-brightgreen" alt="NPM"/></a>
+    <a href="https://github.com/Koromix/luigi/tree/master/koffi"><img src="https://img.shields.io/badge/GitHub-Koffi-ff6600" alt="GitHub"/></a>
 </div>
 </div>
@@ -219,7 +223,7 @@
 </tr>
 </thead>
 <tbody>
-<tr class="row-even"><td><p>Null</p></td>
+<tr class="row-even"><td><p>Undefined</p></td>
 <td><p>void</p></td>
 <td><p>0</p></td>
 <td><p></p></td>
@@ -506,6 +510,8 @@
 </section>
 <section id="struct-types">
 <h2>Struct types<a class="headerlink" href="#struct-types" title="Permalink to this heading">#</a></h2>
+<section id="struct-definition">
+<h3>Struct definition<a class="headerlink" href="#struct-definition" title="Permalink to this heading">#</a></h3>
 <p>Koffi converts JS objects to C structs, and vice-versa.</p>
 <p>Unlike function declarations, as of now there is only one way to create a struct type, with the <code class="docutils literal notranslate"><span class="pre">koffi.struct()</span></code> function. This function takes two arguments: the first one is the name of the type, and the second one is an object containing the struct member names and types. You can omit the first argument to declare an anonymous struct.</p>
 <p>The following example illustrates how to declare the same struct in C and in JS with Koffi:</p>
@@ -538,50 +544,38 @@
 <span class="linenos">3</span><span class="kd">const</span> <span class="nx">Function2</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;Function&#39;</span><span class="p">,</span> <span class="nx">A</span><span class="p">,</span> <span class="p">[</span><span class="nx">A</span><span class="p">]);</span>
 </pre></div>
 </div>
-</section>
-<section id="pointer-types">
-<h2>Pointer types<a class="headerlink" href="#pointer-types" title="Permalink to this heading">#</a></h2>
-<p>In C, pointer arguments are used for differenty purposes. It is important to distinguish these use cases because Koffi provides different ways to deal with each of them:</p>
+<p>Koffi automatically follows the platform C ABI regarding alignment and padding. However, you can override these rules if needed with:</p>
 <ul class="simple">
-<li><p><strong>Struct pointers</strong>: Use of struct pointers by C libraries fall in two cases: avoid (potentially) expensive copies, and to let the function change struct contents (output or input/output arguments).</p></li>
-<li><p><strong>Opaque handles</strong>: the library does not expose the contents of the structs, and only provides you with a pointer to it (e.g. <code class="docutils literal notranslate"><span class="pre">FILE</span> <span class="pre">*</span></code>). Only the functions provided by the library can do something with this pointer, in Koffi we call this a handle. This is usually done for ABI-stability reason, and to prevent library users from messing directly with library internals.</p></li>
-<li><p><strong>Arrays</strong>: in C, you dynamically-sized arrays are usually passed to functions with pointers, either NULL-terminated (or any other sentinel value) or with an additional length argument.</p></li>
-<li><p><strong>Pointers to primitive types</strong>: This is more rare, and generally used for output or input/output arguments. The Win32 API has a lot of these.</p></li>
+<li><p>Pack all members without padding with <code class="docutils literal notranslate"><span class="pre">koffi.pack()</span></code> (instead of <code class="docutils literal notranslate"><span class="pre">koffi.struct()</span></code>)</p></li>
+<li><p>Change alignment of a specific member as shown below</p></li>
 </ul>
-<section id="struct-pointers">
-<h3>Struct pointers<a class="headerlink" href="#struct-pointers" title="Permalink to this heading">#</a></h3>
-<p>The following Win32 example uses <code class="docutils literal notranslate"><span class="pre">GetCursorPos()</span></code> (with an output parameter) to retrieve and show the current cursor position.</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">koffi</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span>
-<span class="linenos"> 2</span><span class="kd">const</span> <span class="nx">lib</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;kernel32.dll&#39;</span><span class="p">);</span>
-<span class="linenos"> 3</span>
-<span class="linenos"> 4</span><span class="c1">// Type declarations</span>
-<span class="linenos"> 5</span><span class="kd">const</span> <span class="nx">POINT</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;POINT&#39;</span><span class="p">,</span> <span class="p">{</span>
-<span class="linenos"> 6</span>    <span class="nx">x</span><span class="o">:</span> <span class="s1">&#39;long&#39;</span><span class="p">,</span>
-<span class="linenos"> 7</span>    <span class="nx">y</span><span class="o">:</span> <span class="s1">&#39;long&#39;</span>
-<span class="linenos"> 8</span><span class="p">});</span>
-<span class="linenos"> 9</span>
-<span class="linenos">10</span><span class="c1">// Functions declarations</span>
-<span class="linenos">11</span><span class="kd">const</span> <span class="nx">GetCursorPos</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 __stdcall GetCursorPos(_Out_ POINT *pos)&#39;</span><span class="p">);</span>
-<span class="linenos">12</span>
-<span class="linenos">13</span><span class="c1">// Get and show cursor position</span>
-<span class="linenos">14</span><span class="kd">let</span> <span class="nx">pos</span> <span class="o">=</span> <span class="p">{};</span>
-<span class="linenos">15</span><span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">GetCursorPos</span><span class="p">(</span><span class="nx">pos</span><span class="p">))</span>
-<span class="linenos">16</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 get cursor position&#39;</span><span class="p">);</span>
-<span class="linenos">17</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">pos</span><span class="p">);</span>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="c1">// This struct is 3 bytes long</span>
+<span class="linenos"> 2</span><span class="kd">const</span> <span class="nx">PackedStruct</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">pack</span><span class="p">(</span><span class="s1">&#39;PackedStruct&#39;</span><span class="p">,</span> <span class="p">{</span>
+<span class="linenos"> 3</span>    <span class="nx">a</span><span class="o">:</span> <span class="s1">&#39;int8_t&#39;</span><span class="p">,</span>
+<span class="linenos"> 4</span>    <span class="nx">b</span><span class="o">:</span> <span class="s1">&#39;int16_t&#39;</span>
+<span class="linenos"> 5</span><span class="p">});</span>
+<span class="linenos"> 6</span>
+<span class="linenos"> 7</span><span class="c1">// This one is 18 bytes long, the second member has an alignment requirement of 16 bytes</span>
+<span class="linenos"> 8</span><span class="kd">const</span> <span class="nx">BigStruct</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;BigStruct&#39;</span><span class="p">,</span> <span class="p">{</span>
+<span class="linenos"> 9</span>    <span class="nx">a</span><span class="o">:</span> <span class="s1">&#39;int8_t&#39;</span><span class="p">,</span>
+<span class="linenos">10</span>    <span class="nx">b</span><span class="o">:</span> <span class="p">[</span><span class="mf">16</span><span class="p">,</span> <span class="s1">&#39;int16_t&#39;</span><span class="p">]</span>
+<span class="linenos">11</span><span class="p">})</span>
 </pre></div>
 </div>
 </section>
-<section id="opaque-handles">
-<h3>Opaque handles<a class="headerlink" href="#opaque-handles" title="Permalink to this heading">#</a></h3>
-<p>Many C libraries use some kind of object-oriented API, with a pair of functions dedicated to create and delete objects. An obvious example of this can be found in stdio.h, with the opaque <code class="docutils literal notranslate"><span class="pre">FILE</span> <span class="pre">*</span></code> pointer. You can open and close files with <code class="docutils literal notranslate"><span class="pre">fopen()</span></code> and <code class="docutils literal notranslate"><span class="pre">fclose()</span></code>, and manipule the handle with other functions such as <code class="docutils literal notranslate"><span class="pre">fread()</span></code> or <code class="docutils literal notranslate"><span class="pre">ftell()</span></code>.</p>
-<p>In Koffi, you can manage this with opaque handles. Declare the handle type with <code class="docutils literal notranslate"><span class="pre">koffi.handle(name)</span></code>, and use a pointer to this type either as a return type or some kind of <a class="reference internal" href="functions#output-parameters"><span class="std std-doc">output parameter</span></a> (with a double pointer).</p>
+<section id="opaque-types">
+<h3>Opaque types<a class="headerlink" href="#opaque-types" title="Permalink to this heading">#</a></h3>
+<p>Many C libraries use some kind of object-oriented API, with a pair of functions dedicated to create and delete objects. An obvious example of this can be found in stdio.h, with the opaque <code class="docutils literal notranslate"><span class="pre">FILE</span> <span class="pre">*</span></code> pointer. You can open and close files with <code class="docutils literal notranslate"><span class="pre">fopen()</span></code> and <code class="docutils literal notranslate"><span class="pre">fclose()</span></code>, and manipule the opaque pointer with other functions such as <code class="docutils literal notranslate"><span class="pre">fread()</span></code> or <code class="docutils literal notranslate"><span class="pre">ftell()</span></code>.</p>
+<p>In Koffi, you can manage this with opaque types. Declare the opaque type with <code class="docutils literal notranslate"><span class="pre">koffi.opaque(name)</span></code>, and use a pointer to this type either as a return type or some kind of <a class="reference internal" href="functions#output-parameters"><span class="std std-doc">output parameter</span></a> (with a double pointer).</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
-<p>Opaque handles <strong>have changed in version 2.0</strong>.</p>
+<p>Opaque types <strong>have changed in version 2.0, and again in version 2.1</strong>.</p>
 <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.</p>
 <p>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 <code class="docutils literal notranslate"><span class="pre">ConcatNewOut</span></code> in the JS part), and is described in the section on <a class="reference internal" href="functions#output-parameters"><span class="std std-doc">output parameters</span></a>.</p>
+<p>In addition to this, you should use <code class="docutils literal notranslate"><span class="pre">koffi.opaque()</span></code> (introduced in Koffi 2.1) instead of <code class="docutils literal notranslate"><span class="pre">koffi.handle()</span></code> which is deprecated, and will be removed eventually in Koffi 3.0.</p>
+<p>Consult the <a class="reference internal" href="changes"><span class="doc std std-doc">migration guide</span></a> for more information.</p>
 </div>
-<p>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: <code class="docutils literal notranslate"><span class="pre">ConcatNew</span></code> (or <code class="docutils literal notranslate"><span class="pre">ConcatNewOut</span></code>) and <code class="docutils literal notranslate"><span class="pre">ConcatFree</span></code>.</p>
+<p>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 type, and is created and destroyed using a pair of C functions: <code class="docutils literal notranslate"><span class="pre">ConcatNew</span></code> (or <code class="docutils literal notranslate"><span class="pre">ConcatNewOut</span></code>) and <code class="docutils literal notranslate"><span class="pre">ConcatFree</span></code>.</p>
 <div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="linenos">  1</span><span class="c1">// Build with: clang -fPIC -o handles.so -shared handles.c -Wall -O2</span>
 <span class="linenos">  2</span>
 <span class="linenos">  3</span><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;stdlib.h&gt;</span><span class="cp"></span>
@@ -703,7 +697,7 @@
 <div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span> <span class="nx">koffi</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span>
 <span class="linenos"> 2</span><span class="kd">const</span> <span class="nx">lib</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;./handles.so&#39;</span><span class="p">);</span>
 <span class="linenos"> 3</span>
-<span class="linenos"> 4</span><span class="kd">const</span> <span class="nx">Concat</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;Concat&#39;</span><span class="p">);</span>
+<span class="linenos"> 4</span><span class="kd">const</span> <span class="nx">Concat</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">opaque</span><span class="p">(</span><span class="s1">&#39;Concat&#39;</span><span class="p">);</span>
 <span class="linenos"> 5</span><span class="kd">const</span> <span class="nx">ConcatNewOut</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;bool ConcatNewOut(_Out_ Concat **out)&#39;</span><span class="p">);</span>
 <span class="linenos"> 6</span><span class="kd">const</span> <span class="nx">ConcatNew</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;Concat *ConcatNew()&#39;</span><span class="p">);</span>
 <span class="linenos"> 7</span><span class="kd">const</span> <span class="nx">ConcatFree</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;void ConcatFree(Concat *c)&#39;</span><span class="p">);</span>
@@ -753,6 +747,50 @@
 </pre></div>
 </div>
 </section>
+</section>
+<section id="pointer-types">
+<h2>Pointer types<a class="headerlink" href="#pointer-types" title="Permalink to this heading">#</a></h2>
+<p>In C, pointer arguments are used for differenty purposes. It is important to distinguish these use cases because Koffi provides different ways to deal with each of them:</p>
+<ul class="simple">
+<li><p><strong>Struct pointers</strong>: Use of struct pointers by C libraries fall in two cases: avoid (potentially) expensive copies, and to let the function change struct contents (output or input/output arguments).</p></li>
+<li><p><strong>Opaque pointers</strong>: the library does not expose the contents of the structs, and only provides you with a pointer to it (e.g. <code class="docutils literal notranslate"><span class="pre">FILE</span> <span class="pre">*</span></code>). Only the functions provided by the library can do something with this pointer, in Koffi we call this an opaque type. This is usually done for ABI-stability reason, and to prevent library users from messing directly with library internals.</p></li>
+<li><p><strong>Arrays</strong>: in C, you dynamically-sized arrays are usually passed to functions with pointers, either NULL-terminated (or any other sentinel value) or with an additional length argument.</p></li>
+<li><p><strong>Pointers to primitive types</strong>: This is more rare, and generally used for output or input/output arguments. The Win32 API has a lot of these.</p></li>
+</ul>
+<section id="struct-pointers">
+<h3>Struct pointers<a class="headerlink" href="#struct-pointers" title="Permalink to this heading">#</a></h3>
+<p>The following Win32 example uses <code class="docutils literal notranslate"><span class="pre">GetCursorPos()</span></code> (with an output parameter) to retrieve and show the current cursor position.</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">koffi</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span>
+<span class="linenos"> 2</span><span class="kd">const</span> <span class="nx">lib</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;kernel32.dll&#39;</span><span class="p">);</span>
+<span class="linenos"> 3</span>
+<span class="linenos"> 4</span><span class="c1">// Type declarations</span>
+<span class="linenos"> 5</span><span class="kd">const</span> <span class="nx">POINT</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;POINT&#39;</span><span class="p">,</span> <span class="p">{</span>
+<span class="linenos"> 6</span>    <span class="nx">x</span><span class="o">:</span> <span class="s1">&#39;long&#39;</span><span class="p">,</span>
+<span class="linenos"> 7</span>    <span class="nx">y</span><span class="o">:</span> <span class="s1">&#39;long&#39;</span>
+<span class="linenos"> 8</span><span class="p">});</span>
+<span class="linenos"> 9</span>
+<span class="linenos">10</span><span class="c1">// Functions declarations</span>
+<span class="linenos">11</span><span class="kd">const</span> <span class="nx">GetCursorPos</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 __stdcall GetCursorPos(_Out_ POINT *pos)&#39;</span><span class="p">);</span>
+<span class="linenos">12</span>
+<span class="linenos">13</span><span class="c1">// Get and show cursor position</span>
+<span class="linenos">14</span><span class="kd">let</span> <span class="nx">pos</span> <span class="o">=</span> <span class="p">{};</span>
+<span class="linenos">15</span><span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">GetCursorPos</span><span class="p">(</span><span class="nx">pos</span><span class="p">))</span>
+<span class="linenos">16</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 get cursor position&#39;</span><span class="p">);</span>
+<span class="linenos">17</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">pos</span><span class="p">);</span>
+</pre></div>
+</div>
+</section>
+<section id="named-pointer-types">
+<h3>Named pointer types<a class="headerlink" href="#named-pointer-types" title="Permalink to this heading">#</a></h3>
+<p>Some C libraries use handles, which behave as pointers to opaque structs. An example of this is the HANDLE type in the Win32 API. If you want to reproduce this behavior, you can define a <strong>named pointer type</strong> to an opaque type, like so:</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">HANDLE</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">pointer</span><span class="p">(</span><span class="s1">&#39;HANDLE&#39;</span><span class="p">,</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">opaque</span><span class="p">());</span>
+<span class="linenos">2</span>
+<span class="linenos">3</span><span class="c1">// And now you get to use it this way:</span>
+<span class="linenos">4</span><span class="kd">const</span> <span class="nx">GetHandleInformation</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;bool __stdcall GetHandleInformation(HANDLE h, _Out_ uint32_t *flags)&#39;</span><span class="p">);</span>
+<span class="linenos">5</span><span class="kd">const</span> <span class="nx">CloseHandle</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;bool __stdcall CloseHandle(HANDLE h)&#39;</span><span class="p">);</span>
+</pre></div>
+</div>
+</section>
 <section id="array-pointers">
 <h3>Array pointers<a class="headerlink" href="#array-pointers" title="Permalink to this heading">#</a></h3>
 <p>In C, dynamically-sized arrays are usually passed around as pointers. The length is either passed as an additional argument, or inferred from the array content itself, for example with a terminating sentinel value (such as a NULL pointers in the case of an array of strings).</p>
@@ -793,7 +831,7 @@
 <div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span> <span class="nx">koffi</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span>
 <span class="linenos"> 2</span><span class="kd">const</span> <span class="nx">lib</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;kernel32.dll&#39;</span><span class="p">);</span>
 <span class="linenos"> 3</span>
-<span class="linenos"> 4</span><span class="kd">const</span> <span class="nx">HANDLE</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">pointer</span><span class="p">(</span><span class="s1">&#39;HANDLE&#39;</span><span class="p">,</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">handle</span><span class="p">());</span>
+<span class="linenos"> 4</span><span class="kd">const</span> <span class="nx">HANDLE</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">pointer</span><span class="p">(</span><span class="s1">&#39;HANDLE&#39;</span><span class="p">,</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">opaque</span><span class="p">());</span>
 <span class="linenos"> 5</span><span class="kd">const</span> <span class="nx">FILETIME</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;FILETIME&#39;</span><span class="p">,</span> <span class="p">{</span>
 <span class="linenos"> 6</span>    <span class="nx">dwLowDateTime</span><span class="o">:</span> <span class="s1">&#39;uint&#39;</span><span class="p">,</span>
 <span class="linenos"> 7</span>    <span class="nx">dwHighDateTime</span><span class="o">:</span> <span class="s1">&#39;uint&#39;</span>
@@ -921,18 +959,27 @@
 <p>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 <code class="docutils literal notranslate"><span class="pre">string</span></code> array hint (e.g. <code class="docutils literal notranslate"><span class="pre">koffi.array('char',</span> <span class="pre">8,</span> <span class="pre">'string')</span></code>).</p>
 </section>
 </section>
+<section id="disposable-types">
+<h2>Disposable types<a class="headerlink" href="#disposable-types" title="Permalink to this heading">#</a></h2>
+<p>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.</p>
+<p>Read the documentation for <a class="reference internal" href="functions#heap-allocated-values"><span class="std std-doc">disposable types</span></a> on the page about function calls.</p>
+</section>
+<section id="utility-functions">
+<h2>Utility functions<a class="headerlink" href="#utility-functions" title="Permalink to this heading">#</a></h2>
 <section id="type-introspection">
-<h2>Type introspection<a class="headerlink" href="#type-introspection" title="Permalink to this heading">#</a></h2>
+<h3>Type introspection<a class="headerlink" href="#type-introspection" title="Permalink to this heading">#</a></h3>
 <p>Koffi exposes three functions to explore type information:</p>
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">koffi.sizeof(type)</span></code> to get the size of a type</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">koffi.alignof(type)</span></code> to get the alignment of a type</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">koffi.introspect(type)</span></code> to get the definition of a type in an object containing: name, primitive, size, alignment, members (structs), reference (array, pointer) and length (array)</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">koffi.resolve(type)</span></code> to get the resolved type object from a type string</p></li>
 </ul>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>The value returned by <code class="docutils literal notranslate"><span class="pre">introspect()</span></code> has <strong>changed in version 2.0</strong>.</p>
 <p>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.</p>
+<p>Consult the <a class="reference internal" href="changes"><span class="doc std std-doc">migration guide</span></a> for more information.</p>
 </div>
 <p>Just like before, you can refer to primitive types by their name or through <code class="docutils literal notranslate"><span class="pre">koffi.types</span></code>:</p>
 <div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="c1">// These two lines do the same:</span>
@@ -941,6 +988,11 @@
 </pre></div>
 </div>
 </section>
+<section id="type-aliases">
+<h3>Type aliases<a class="headerlink" href="#type-aliases" title="Permalink to this heading">#</a></h3>
+<p>You can alias a type with <code class="docutils literal notranslate"><span class="pre">koffi.alias(name,</span> <span class="pre">type)</span></code>. Aliased types are completely equivalent.</p>
+</section>
+</section>
 </section>
         </article>
@@ -953,7 +1005,7 @@
                 <div class="context">
                   <span>Next</span>
                 </div>
-                <div class="title">Function calls</div>
+                <div class="title">Functions</div>
               </div>
               <svg><use href="#svg-arrow-right"></use></svg>
             </a>
@@ -1002,10 +1054,14 @@
             <ul>
 <li><a class="reference internal" href="#">Data types</a><ul>
 <li><a class="reference internal" href="#primitive-types">Primitive types</a></li>
-<li><a class="reference internal" href="#struct-types">Struct types</a></li>
+<li><a class="reference internal" href="#struct-types">Struct types</a><ul>
+<li><a class="reference internal" href="#struct-definition">Struct definition</a></li>
+<li><a class="reference internal" href="#opaque-types">Opaque types</a></li>
+</ul>
+</li>
 <li><a class="reference internal" href="#pointer-types">Pointer types</a><ul>
 <li><a class="reference internal" href="#struct-pointers">Struct pointers</a></li>
-<li><a class="reference internal" href="#opaque-handles">Opaque handles</a></li>
+<li><a class="reference internal" href="#named-pointer-types">Named pointer types</a></li>
 <li><a class="reference internal" href="#array-pointers">Array pointers</a></li>
 <li><a class="reference internal" href="#pointers-to-primitive-types">Pointers to primitive types</a></li>
 </ul>
@@ -1014,7 +1070,12 @@
 <li><a class="reference internal" href="#handling-of-strings">Handling of strings</a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#disposable-types">Disposable types</a></li>
+<li><a class="reference internal" href="#utility-functions">Utility functions</a><ul>
 <li><a class="reference internal" href="#type-introspection">Type introspection</a></li>
+<li><a class="reference internal" href="#type-aliases">Type aliases</a></li>
+</ul>
+</li>
 </ul>
 </li>
 </ul>

package/doc/functions.md CHANGED Viewed

@@ -105,14 +105,16 @@ printf('Integer %d, double %g, str %s', 'int', 6, 'double', 8.5, 'str', 'THE END
 On x86 platforms, only the Cdecl convention can be used for variadic functions.
-## Output parameters
+## C to JS conversion gotchas
+### Output parameters
 By default, Koffi will only forward arguments from Javascript to C. However, many C functions use pointer arguments for output values, or input/output values.
 For simplicity, and because Javascript only has value semantics for primitive types, Koffi can marshal out (or in/out) two types of parameters:
 - [Structs](types.md#struct-types) (to/from JS objects)
-- [Opaque handles](types.md#opaque-handles)
+- [Opaque types](types.md#opaque-types)
 In order to change an argument from input-only to output or input/output, use the following functions:
@@ -124,7 +126,7 @@ The same can be done when declaring a function with a C-like prototype string, w
 - `_Out_` for output parameters
 - `_Inout_` for dual input/output parameters
-### Struct example
+#### Struct example
 This example calls the POSIX function `gettimeofday()`, and uses the prototype-like syntax.
@@ -150,29 +152,80 @@ gettimeofday(tv, null);
 console.log(tv);
 ```
-### Opaque handle example
+#### Opaque type example
 This example opens an in-memory SQLite database, and uses the node-ffi-style function declaration syntax.
 ```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.opaque('sqlite3');
-// Use koffi.out() on a 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)), 'int', 'str']);
-const sqlite3_close_v2 = lib.func('sqlite3_close_v2', 'int', [sqlite3_db]);
+// 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, 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);
 ```
+### Heap-allocated values
+Some C functions return heap-allocated values directly or through output parameters. While Koffi automatically converts values from C to JS (to a string or an object), it does not know when something needs to be freed, or how.
+For opaque types, 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.
+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).
+```js
+const AnonHeapStr = koffi.disposable('str'); // Anonymous type (cannot be used in function prototypes)
+const NamedHeapStr = koffi.disposable('HeapStr', 'str'); // Same thing, but named so usable in function prototypes
+const ExplicitFree = koffi.disposable('HeapStr16', 'str16', koffi.free); // You can specify any other JS function
+```
+The following example illustrates the use of a disposable type derived from *str*.
+```js
+const koffi = require('koffi');
+const lib = koffi.load('libc.so.6');
+// 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']);
+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 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');
+const lib = koffi.load('libc.so.6');
+// You can also use: const strdup = lib.func('const char *! strdup(const char *str)')
+const strdup = lib.func('str! strdup(const char *str)');
+let copy = strdup('World!');
+console.log(copy); // Prints World!
+```
+Disposable types can only be created from pointer or string types.
+```{warning}
+Be careful on Windows: if your shared library uses a different CRT (such as msvcrt), the memory could have been allocated by a different malloc/free implementation or heap, resulting in undefined behavior if you use `koffi.free()`.
+```
 ## Javascript callbacks
 In order to pass a JS function to a C function expecting a callback, you must first create a callback type with the expected return type and parameters. The syntax is similar to the one used to load functions from a shared library.
@@ -187,9 +240,30 @@ const ExampleCallback = koffi.callback('ExampleCallback', 'void', ['int']);
 const AddDoubleFloat = koffi.callback('double AddDoubleFloat(double d, float f)');
 ```
-Once your callback type is declared, you can use it in struct definitions, or as function parameter and/or return type.
+Once your callback type is declared, you can use a pointer to it in struct definitions, or as function parameters and/or return types.
-Here is a small example with the C part and the JS part.
+```{note}
+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.
+Thus, Koffi distinguishes two callback modes:
+- [Transient callbacks](#transient-callbacks) can only be called while the C function they are passed to is running, and are invalidated when it returns. If the C function calls the callback later, the behavior is undefined, though Koffi tries to detect such cases. If it does, an exception will be thrown, but this is no guaranteed. However, they are simple to use, and don't require any special handling.
+- [Registered callbacks](#registered-callbacks) can be called at any time, but they must be manually registered and unregistered. A limited number of registered callbacks can exist at the same time.
+You need to specify the correct [calling convention](#calling-conventions) on x86 platforms, or the behavior is undefined (Node will probably crash). Only *cdecl* and *stdcall* callbacks are supported.
+### Transient callbacks
+Use transient callbacks when the native C function only needs to call them while it runs (e.g. qsort, progress callback, `sqlite3_exec`). Here is a small example with the C part and the JS part.
 ```c
 #include <string.h>
@@ -204,10 +278,11 @@ int TransferToJS(const char *name, int age, int (*cb)(const char *str, int age))
 ```js
 const koffi = require('koffi');
+const lib = koffi.load('./callbacks.so'); // Fake path
 const TransferCallback = koffi.callback('int TransferCallback(const char *str, int age)');
-const TransferToJS = lib.func('int TransferToJS(const char *str, int age, TransferCallback cb)');
+const TransferToJS = lib.func('TransferToJS', 'int', ['str', 'int', koffi.pointer(TransferCallback)]);
 let ret = TransferToJS('Niels', 27, (str, age) => {
     console.log(str);
@@ -222,7 +297,56 @@ console.log(ret);
 //   42
 ```
-You need to specify the correct [calling convention](#calling-conventions) on x86 platforms, or the behavior is undefined (Node will probably crash). Only *cdecl* and *stdcall* callbacks are supported.
+### Registered callbacks
+Use registered callbacks when the function needs to be called at a later time (e.g. log handler, event handler, `fopencookie/funopen`). Call `koffi.register(func, type)` to register a callback function, with two arguments: the JS function, and the callback type.
+When you are done, call `koffi.unregister()` (with the value returned by `koffi.register()`) to release the slot. A maximum of 16 registered callbacks can exist at the same time. Failure to do so will leak the slot, and subsequent registrations may fail (with an exception) once all slots are used.
+The example below shows how to register and unregister delayed callbacks.
+```c
+static const char *(*g_cb1)(const char *name);
+static void (*g_cb2)(const char *str);
+void RegisterFunctions(const char *(*cb1)(const char *name), void (*cb2)(const char *str))
+{
+    g_cb1 = cb1;
+    g_cb2 = cb2;
+}
+void SayIt(const char *name)
+{
+    const char *str = g_cb1(name);
+    g_cb2(str);
+}
+```
+```js
+const koffi = require('koffi');
+const lib = koffi.load('./callbacks.so'); // Fake path
+const GetCallback = koffi.callback('const char *GetCallback(const char *name)');
+const PrintCallback = koffi.callback('void PrintCallback(const char *str)');
+const RegisterFunctions = lib.func('void RegisterFunctions(GetCallback *cb1, PrintCallback *cb2)');
+const SayIt = lib.func('void SayIt(const char *name)');
+let cb1 = koffi.register(name => 'Hello ' + name + '!', koffi.pointer(GetCallback));
+let cb2 = koffi.register(console.log, 'PrintCallback *');
+RegisterFunctions(cb1, cb2);
+SayIt('Kyoto'); // Prints Hello Kyoto!
+koffi.unregister(cb1);
+koffi.unregister(cb2);
+```
+### Handling of exceptions
+If an exception happens inside the JS callback, the C API will receive 0 or NULL (depending on the return value type).
+Handle the exception yourself (with try/catch) if you need to handle exceptions differently.
 ## Thread safety

package/doc/templates/badges.html ADDED Viewed

@@ -0,0 +1,5 @@
+<div style="text-align: center; margin-top: 2em;">
+    <a href="https://www.npmjs.com/package/koffi"><img src="https://img.shields.io/badge/NPM-{{version}}-brightgreen" alt="NPM"/></a>
+    <a href="https://github.com/Koromix/luigi/tree/master/koffi"><img src="https://img.shields.io/badge/GitHub-Koffi-ff6600" alt="GitHub"/></a>
+</div>