koffi 2.0.1 → 2.1.0-beta.3

package/doc/dist/html/changes.html

@@ -174,10 +174,9 @@
 
 </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.O.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>
-    <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>
+</div></div>
 
       </div>
       
@@ -211,6 +210,31 @@
 <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-1-0-in-beta">
+<h3>Koffi 2.1.0 (in beta)<a class="headerlink" href="#koffi-2-1-0-in-beta" title="Permalink to this heading">#</a></h3>
+<p><strong>Main changes:</strong></p>
+<ul class="simple">
+<li><p>Add <a class="reference internal" href="functions#polymorphic-parameters"><span class="std std-doc">koffi.as()</span></a> to support polymorphic APIs based on <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> parameters</p></li>
+<li><p>Add <a class="reference internal" href="types#endian-sensitive-types"><span class="std std-doc">endian-sensitive integer types</span></a>: <code class="docutils literal notranslate"><span class="pre">intX_le_t</span></code>, <code class="docutils literal notranslate"><span class="pre">intX_be_t</span></code></p></li>
+<li><p>Accept typed arrays for <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> parameters</p></li>
+<li><p>Introduce <code class="docutils literal notranslate"><span class="pre">koffi.opaque()</span></code> to replace <code class="docutils literal notranslate"><span class="pre">koffi.handle()</span></code> (which remains supported until Koffi 3.0)</p></li>
+</ul>
+<p><strong>Other changes:</strong></p>
+<ul class="simple">
+<li><p>Improve global performance with inlining and unity builds</p></li>
+<li><p>Add <code class="docutils literal notranslate"><span class="pre">size_t</span></code> primitive type</p></li>
+<li><p>Support member-specific alignement value in structs</p></li>
+<li><p>Detect impossible parameters and return types (such as non-pointer opaque types)</p></li>
+<li><p>Various documentation fixes and improvements</p></li>
+</ul>
+</section>
+<section id="koffi-2-0-1">
+<h3>Koffi 2.0.1<a class="headerlink" href="#koffi-2-0-1" title="Permalink to this heading">#</a></h3>
+<p><strong>Main changes:</strong></p>
+<ul class="simple">
+<li><p>Return <code class="docutils literal notranslate"><span class="pre">undefined</span></code> (instead of null) for <code class="docutils literal notranslate"><span class="pre">void</span></code> functions</p></li>
+</ul>
+</section>
 <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>
@@ -421,7 +445,7 @@
 <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>Opaque types</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">koffi.introspect()</span></code></p></li>
 </ul>
 <section id="callback-types">
@@ -471,10 +495,11 @@
 </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>
+<section id="opaque-types">
+<h4>Opaque types<a class="headerlink" href="#opaque-types" 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, in Koffi 2.0, you must use them through a pointer, and use an array for output parameters.</p>
+<p>In addition to that, <code class="docutils literal notranslate"><span class="pre">koffi.handle()</span></code> has been deprecated in Koffi 2.1 and replaced with <code class="docutils literal notranslate"><span class="pre">koffi.opaque()</span></code>. They work the same but new code should use <code class="docutils literal notranslate"><span class="pre">koffi.opaque()</span></code>, the former one will eventually be removed in Koffi 3.0.</p>
+<p>For functions that return opaque pointers 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>
@@ -487,16 +512,17 @@
 <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>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="c1">// Koffi 2.1</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>
+<span class="linenos"> 3</span><span class="c1">// If you use Koffi 2.0: const FILE = koffi.handle(&#39;FILE&#39;);</span>
+<span class="linenos"> 4</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">opaque</span><span class="p">(</span><span class="s1">&#39;FILE&#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;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"> 6</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"> 7</span>
+<span class="linenos"> 8</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"> 9</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">10</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">11</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>
@@ -518,24 +544,25 @@
 <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>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="c1">// Koffi 2.1</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>
+<span class="linenos"> 3</span><span class="c1">// If you use Koffi 2.0: const sqlite3 = koffi.handle(&#39;sqlite3&#39;);</span>
+<span class="linenos"> 4</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">opaque</span><span class="p">(</span><span class="s1">&#39;sqlite3&#39;</span><span class="p">);</span>
+<span class="linenos"> 5</span>
+<span class="linenos"> 6</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"> 7</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"> 8</span>
+<span class="linenos"> 9</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">10</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">11</span>
+<span class="linenos">12</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">13</span>
+<span class="linenos">14</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">15</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">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 open database&#39;</span><span class="p">);</span>
+<span class="linenos">17</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">18</span>
+<span class="linenos">19</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>
@@ -608,6 +635,8 @@
             <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-1-0-in-beta">Koffi 2.1.0 (in beta)</a></li>
+<li><a class="reference internal" href="#koffi-2-0-1">Koffi 2.0.1</a></li>
 <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>
@@ -630,7 +659,7 @@
 <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="#opaque-types">Opaque types</a></li>
 <li><a class="reference internal" href="#koffi-introspect">koffi.introspect()</a></li>
 </ul>
 </li>

package/doc/dist/html/contribute.html

@@ -174,10 +174,9 @@
 
 </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.O.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>
-    <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>
+</div></div>
 
       </div>
       

package/doc/dist/html/functions.html

@@ -174,10 +174,9 @@
 
 </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.O.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>
-    <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>
+</div></div>
 
       </div>
       
@@ -325,15 +324,15 @@
 <p>On x86 platforms, only the Cdecl convention can be used for variadic functions.</p>
 </section>
 </section>
-<section id="c-to-js-conversion-gotchas">
-<h2>C to JS conversion gotchas<a class="headerlink" href="#c-to-js-conversion-gotchas" title="Permalink to this heading">#</a></h2>
+<section id="special-considerations">
+<h2>Special considerations<a class="headerlink" href="#special-considerations" title="Permalink to this heading">#</a></h2>
 <section id="output-parameters">
 <h3>Output parameters<a class="headerlink" href="#output-parameters" title="Permalink to this heading">#</a></h3>
 <p>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.</p>
 <p>For simplicity, and because Javascript only has value semantics for primitive types, Koffi can marshal out (or in/out) two types of parameters:</p>
 <ul class="simple">
 <li><p><a class="reference internal" href="types#struct-types"><span class="std std-doc">Structs</span></a> (to/from JS objects)</p></li>
-<li><p><a class="reference internal" href="types#opaque-handles"><span class="std std-doc">Opaque handles</span></a></p></li>
+<li><p><a class="reference internal" href="types#opaque-types"><span class="std std-doc">Opaque types</span></a></p></li>
 </ul>
 <p>In order to change an argument from input-only to output or input/output, use the following functions:</p>
 <ul class="simple">
@@ -370,13 +369,13 @@
 </pre></div>
 </div>
 </section>
-<section id="opaque-handle-example">
-<h4>Opaque handle example<a class="headerlink" href="#opaque-handle-example" title="Permalink to this heading">#</a></h4>
+<section id="opaque-type-example">
+<h4>Opaque type example<a class="headerlink" href="#opaque-type-example" title="Permalink to this heading">#</a></h4>
 <p>This example opens an in-memory SQLite database, and uses the node-ffi-style function declaration syntax.</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;sqlite3.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">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="kd">const</span> <span class="nx">sqlite3</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;sqlite3&#39;</span><span class="p">);</span>
 <span class="linenos"> 5</span>
 <span class="linenos"> 6</span><span class="c1">// Use koffi.out() on a double pointer to copy out (from C to JS) after the call</span>
 <span class="linenos"> 7</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;sqlite3_open_v2&#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="nx">koffi</span><span class="p">.</span><span class="nx">out</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">sqlite3</span><span class="p">,</span> <span class="mf">2</span><span class="p">)),</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="s1">&#39;str&#39;</span><span class="p">]);</span>
@@ -395,10 +394,70 @@
 </div>
 </section>
 </section>
+<section id="polymorphic-parameters">
+<h3>Polymorphic parameters<a class="headerlink" href="#polymorphic-parameters" title="Permalink to this heading">#</a></h3>
+<p><em>New in Koffi 2.1</em></p>
+<p>Many C functions use <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> parameters in order to pass polymorphic objects and arrays, meaning that the data format changes can change depending on one other argument, or on some kind of struct tag member.</p>
+<p>Koffi provides two features to deal with this:</p>
+<ul class="simple">
+<li><p>Typed JS arrays can be used as values in place everywhere <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> is expected. See <a class="reference internal" href="types#array-pointers-dynamic-arrays"><span class="std std-doc">dynamic arrays</span></a> for more information, for input or output.</p></li>
+<li><p>You can use <code class="docutils literal notranslate"><span class="pre">koffi.as(value,</span> <span class="pre">type)</span></code> to tell Koffi what kind of type is actually expected.</p></li>
+</ul>
+<p>The example below shows the use of <code class="docutils literal notranslate"><span class="pre">koffi.as()</span></code> to read the header of a PNG file with <code class="docutils literal notranslate"><span class="pre">fread()</span></code>.</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;libc.so.6&#39;</span><span class="p">);</span>
+<span class="linenos"> 3</span>
+<span class="linenos"> 4</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">opaque</span><span class="p">(</span><span class="s1">&#39;FILE&#39;</span><span class="p">);</span>
+<span class="linenos"> 5</span>
+<span class="linenos"> 6</span><span class="kd">const</span> <span class="nx">PngHeader</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;PngHeader&#39;</span><span class="p">,</span> <span class="p">{</span>
+<span class="linenos"> 7</span>    <span class="nx">signature</span><span class="o">:</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">array</span><span class="p">(</span><span class="s1">&#39;uint8_t&#39;</span><span class="p">,</span> <span class="mf">8</span><span class="p">),</span>
+<span class="linenos"> 8</span>    <span class="nx">ihdr</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="linenos"> 9</span>        <span class="nx">length</span><span class="o">:</span> <span class="s1">&#39;uint32_be_t&#39;</span><span class="p">,</span>
+<span class="linenos">10</span>        <span class="nx">chunk</span><span class="o">:</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">array</span><span class="p">(</span><span class="s1">&#39;char&#39;</span><span class="p">,</span> <span class="mf">4</span><span class="p">),</span>
+<span class="linenos">11</span>        <span class="nx">width</span><span class="o">:</span> <span class="s1">&#39;uint32_be_t&#39;</span><span class="p">,</span>
+<span class="linenos">12</span>        <span class="nx">height</span><span class="o">:</span> <span class="s1">&#39;uint32_be_t&#39;</span><span class="p">,</span>
+<span class="linenos">13</span>        <span class="nx">depth</span><span class="o">:</span> <span class="s1">&#39;uint8_t&#39;</span><span class="p">,</span>
+<span class="linenos">14</span>        <span class="nx">color</span><span class="o">:</span> <span class="s1">&#39;uint8_t&#39;</span><span class="p">,</span>
+<span class="linenos">15</span>        <span class="nx">compression</span><span class="o">:</span> <span class="s1">&#39;uint8_t&#39;</span><span class="p">,</span>
+<span class="linenos">16</span>        <span class="nx">filter</span><span class="o">:</span> <span class="s1">&#39;uint8_t&#39;</span><span class="p">,</span>
+<span class="linenos">17</span>        <span class="nx">interlace</span><span class="o">:</span> <span class="s1">&#39;uint8_t&#39;</span><span class="p">,</span>
+<span class="linenos">18</span>        <span class="nx">crc</span><span class="o">:</span> <span class="s1">&#39;uint32_be_t&#39;</span>
+<span class="linenos">19</span>    <span class="p">})</span>
+<span class="linenos">20</span><span class="p">});</span>
+<span class="linenos">21</span>
+<span class="linenos">22</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;FILE *fopen(const char *path, const char *mode)&#39;</span><span class="p">);</span>
+<span class="linenos">23</span><span class="kd">const</span> <span class="nx">fclose</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 fclose(FILE *fp)&#39;</span><span class="p">);</span>
+<span class="linenos">24</span><span class="kd">const</span> <span class="nx">fread</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;size_t fread(_Out_ void *ptr, size_t size, size_t nmemb, FILE *fp)&#39;</span><span class="p">);</span>
+<span class="linenos">25</span>
+<span class="linenos">26</span><span class="kd">let</span> <span class="nx">filename</span> <span class="o">=</span> <span class="nx">process</span><span class="p">.</span><span class="nx">argv</span><span class="p">[</span><span class="mf">2</span><span class="p">];</span>
+<span class="linenos">27</span><span class="k">if</span> <span class="p">(</span><span class="nx">filename</span> <span class="o">==</span> <span class="kc">null</span><span class="p">)</span>
+<span class="linenos">28</span>    <span class="k">throw</span> <span class="ow">new</span> <span class="ne">Error</span><span class="p">(</span><span class="s1">&#39;Usage: node png.js &lt;image.png&gt;&#39;</span><span class="p">);</span>
+<span class="linenos">29</span>
+<span class="linenos">30</span><span class="kd">let</span> <span class="nx">hdr</span> <span class="o">=</span> <span class="p">{};</span>
+<span class="linenos">31</span><span class="p">{</span>
+<span class="linenos">32</span>
+<span class="linenos">33</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="nx">filename</span><span class="p">,</span> <span class="s1">&#39;rb&#39;</span><span class="p">);</span>
+<span class="linenos">34</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">35</span>        <span class="k">throw</span> <span class="ow">new</span> <span class="ne">Error</span><span class="p">(</span><span class="sb">`Failed to open &#39;</span><span class="si">${</span><span class="nx">filename</span><span class="si">}</span><span class="sb">&#39;`</span><span class="p">);</span>
+<span class="linenos">36</span>
+<span class="linenos">37</span>    <span class="k">try</span> <span class="p">{</span>
+<span class="linenos">38</span>        <span class="kd">let</span> <span class="nx">len</span> <span class="o">=</span> <span class="nx">fread</span><span class="p">(</span><span class="nx">koffi</span><span class="p">.</span><span class="kr">as</span><span class="p">(</span><span class="nx">hdr</span><span class="p">,</span> <span class="s1">&#39;PngHeader *&#39;</span><span class="p">),</span> <span class="mf">1</span><span class="p">,</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">sizeof</span><span class="p">(</span><span class="nx">PngHeader</span><span class="p">),</span> <span class="nx">fp</span><span class="p">);</span>
+<span class="linenos">39</span>        <span class="k">if</span> <span class="p">(</span><span class="nx">len</span> <span class="o">&lt;</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">sizeof</span><span class="p">(</span><span class="nx">PngHeader</span><span class="p">))</span>
+<span class="linenos">40</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 read PNG header&#39;</span><span class="p">);</span>
+<span class="linenos">41</span>    <span class="p">}</span> <span class="k">finally</span> <span class="p">{</span>
+<span class="linenos">42</span>        <span class="nx">fclose</span><span class="p">(</span><span class="nx">fp</span><span class="p">);</span>
+<span class="linenos">43</span>    <span class="p">}</span>
+<span class="linenos">44</span><span class="p">}</span>
+<span class="linenos">45</span>
+<span class="linenos">46</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">&#39;PNG header:&#39;</span><span class="p">,</span> <span class="nx">hdr</span><span class="p">);</span>
+</pre></div>
+</div>
+</section>
 <section id="heap-allocated-values">
 <h3>Heap-allocated values<a class="headerlink" href="#heap-allocated-values" title="Permalink to this heading">#</a></h3>
+<p><em>New in Koffi 2.0</em></p>
 <p>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.</p>
-<p>For opaque handles, such as FILE, this does not matter because you will explicitly call <code class="docutils literal notranslate"><span class="pre">fclose()</span></code> 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.</p>
+<p>For opaque types, such as FILE, this does not matter because you will explicitly call <code class="docutils literal notranslate"><span class="pre">fclose()</span></code> 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.</p>
 <p>To avoid this, you can instruct Koffi to call a function on the original pointer once the conversion is done, by creating a <strong>disposable type</strong> with <code class="docutils literal notranslate"><span class="pre">koffi.dispose(name,</span> <span class="pre">type,</span> <span class="pre">func)</span></code>. This creates a type derived from another type, the only difference being that <em>func</em> gets called with the original pointer once the value has been converted and is not needed anymore.</p>
 <p>The <em>name</em> can be omitted to create an anonymous disposable type. If <em>func</em> is omitted or is null, Koffi will use <code class="docutils literal notranslate"><span class="pre">koffi.free(ptr)</span></code> (which calls the standard C library <em>free</em> function under the hood).</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">AnonHeapStr</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">disposable</span><span class="p">(</span><span class="s1">&#39;str&#39;</span><span class="p">);</span> <span class="c1">// Anonymous type (cannot be used in function prototypes)</span>
@@ -499,6 +558,7 @@
 </section>
 <section id="registered-callbacks">
 <h3>Registered callbacks<a class="headerlink" href="#registered-callbacks" title="Permalink to this heading">#</a></h3>
+<p><em>New in Koffi 2.0</em></p>
 <p>Use registered callbacks when the function needs to be called at a later time (e.g. log handler, event handler, <code class="docutils literal notranslate"><span class="pre">fopencookie/funopen</span></code>). Call <code class="docutils literal notranslate"><span class="pre">koffi.register(func,</span> <span class="pre">type)</span></code> to register a callback function, with two arguments: the JS function, and the callback type.</p>
 <p>When you are done, call <code class="docutils literal notranslate"><span class="pre">koffi.unregister()</span></code> (with the value returned by <code class="docutils literal notranslate"><span class="pre">koffi.register()</span></code>) 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.</p>
 <p>The example below shows how to register and unregister delayed callbacks.</p>
@@ -620,12 +680,13 @@
 <li><a class="reference internal" href="#variadic-functions">Variadic functions</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#c-to-js-conversion-gotchas">C to JS conversion gotchas</a><ul>
+<li><a class="reference internal" href="#special-considerations">Special considerations</a><ul>
 <li><a class="reference internal" href="#output-parameters">Output parameters</a><ul>
 <li><a class="reference internal" href="#struct-example">Struct example</a></li>
-<li><a class="reference internal" href="#opaque-handle-example">Opaque handle example</a></li>
+<li><a class="reference internal" href="#opaque-type-example">Opaque type example</a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#polymorphic-parameters">Polymorphic parameters</a></li>
 <li><a class="reference internal" href="#heap-allocated-values">Heap-allocated values</a></li>
 </ul>
 </li>

package/doc/dist/html/genindex.html

@@ -172,10 +172,9 @@
 
 </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.O.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>
-    <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>
+</div></div>
 
       </div>
       

package/doc/dist/html/index.html

@@ -174,10 +174,9 @@
 
 </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.O.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>
-    <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>
+</div></div>
 
       </div>
       
@@ -208,7 +207,7 @@
         </div>
         <article role="main">
           <section id="koffi-version">
-<h1>Koffi 2.0.0<a class="headerlink" href="#koffi-version" title="Permalink to this heading">#</a></h1>
+<h1>Koffi 2.1.0-beta.2<a class="headerlink" href="#koffi-version" title="Permalink to this heading">#</a></h1>
 <section id="overview">
 <h2>Overview<a class="headerlink" href="#overview" title="Permalink to this heading">#</a></h2>
 <p>Koffi is a <strong>fast and easy-to-use C FFI module for Node.js</strong>, featuring:</p>
@@ -240,7 +239,7 @@
 <li class="toctree-l2"><a class="reference internal" href="types#primitive-types">Primitive types</a></li>
 <li class="toctree-l2"><a class="reference internal" href="types#struct-types">Struct types</a></li>
 <li class="toctree-l2"><a class="reference internal" href="types#pointer-types">Pointer types</a></li>
-<li class="toctree-l2"><a class="reference internal" href="types#fixed-size-c-arrays">Fixed-size C arrays</a></li>
+<li class="toctree-l2"><a class="reference internal" href="types#array-types">Array types</a></li>
 <li class="toctree-l2"><a class="reference internal" href="types#disposable-types">Disposable types</a></li>
 <li class="toctree-l2"><a class="reference internal" href="types#utility-functions">Utility functions</a></li>
 </ul>
@@ -248,7 +247,7 @@
 <li class="toctree-l1"><a class="reference internal" href="functions">Functions</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="functions#function-definitions">Function definitions</a></li>
 <li class="toctree-l2"><a class="reference internal" href="functions#function-calls">Function calls</a></li>
-<li class="toctree-l2"><a class="reference internal" href="functions#c-to-js-conversion-gotchas">C to JS conversion gotchas</a></li>
+<li class="toctree-l2"><a class="reference internal" href="functions#special-considerations">Special considerations</a></li>
 <li class="toctree-l2"><a class="reference internal" href="functions#javascript-callbacks">Javascript callbacks</a></li>
 <li class="toctree-l2"><a class="reference internal" href="functions#thread-safety">Thread safety</a></li>
 </ul>
@@ -335,7 +334,7 @@
         <div class="toc-tree-container">
           <div class="toc-tree">
             <ul>
-<li><a class="reference internal" href="#">Koffi 2.0.0</a><ul>
+<li><a class="reference internal" href="#">Koffi 2.1.0-beta.2</a><ul>
 <li><a class="reference internal" href="#overview">Overview</a></li>
 <li><a class="reference internal" href="#table-of-contents">Table of contents</a></li>
 <li><a class="reference internal" href="#license">License</a></li>

package/doc/dist/html/memory.html

@@ -174,10 +174,9 @@
 
 </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.O.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>
-    <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>
+</div></div>
 
       </div>
       

package/doc/dist/html/platforms.html

@@ -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="Quick start" href="start" /><link rel="prev" title="Koffi 2.0.0" href="index" />
+<link rel="index" title="Index" href="genindex" /><link rel="search" title="Search" href="search" /><link rel="next" title="Quick start" href="start" /><link rel="prev" title="Koffi 2.1.0-beta.2" href="index" />
 
     <meta name="generator" content="sphinx-5.0.1, furo 2022.06.04.1"/>
         <title>Requirements - Koffi</title>
@@ -174,10 +174,9 @@
 
 </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.O.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>
-    <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>
+</div></div>
 
       </div>
       

package/doc/dist/html/search.html

@@ -171,10 +171,9 @@
 
 </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.O.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>
-    <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>
+</div></div>
 
       </div>