koffi 2.0.1 → 2.1.0-beta.1

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

@@ -6,7 +6,7 @@ While the C standard allows for variation in the size of most integer types, Kof
 
 JS type           | C type             | Bytes | Signedness | Note
 ----------------- | ------------------ | ----- | ---------- | ---------------------------
-Null              | void               | 0     |            | Only valid as a return type
+Undefined         | void               | 0     |            | Only valid as a return type
 Number (integer)  | int8               | 1     | Signed     |
 Number (integer)  | int8_t             | 1     | Signed     |
 Number (integer)  | uint8              | 1     | Unsigned   |
@@ -69,6 +69,8 @@ let struct2 = koffi.struct({ dummy: koffi.types.long });
 
 ## Struct types
 
+### Struct definition
+
 Koffi converts JS objects to C structs, and vice-versa.
 
 Unlike function declarations, as of now there is only one way to create a struct type, with the `koffi.struct()` 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.
@@ -109,56 +111,44 @@ const Function1 = lib.func('A Function(A value)');
 const Function2 = lib.func('Function', A, [A]);
 ```
 
-## Pointer types
+Koffi automatically follows the platform C ABI regarding alignment and padding. However, you can override these rules if needed with:
 
-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:
-
-- **Struct pointers**: 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).
-- **Opaque handles**: the library does not expose the contents of the structs, and only provides you with a pointer to it (e.g. `FILE *`). 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.
-- **Arrays**: 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.
-- **Pointers to primitive types**: This is more rare, and generally used for output or input/output arguments. The Win32 API has a lot of these.
-
-### Struct pointers
-
-The following Win32 example uses `GetCursorPos()` (with an output parameter) to retrieve and show the current cursor position.
+- Pack all members without padding with `koffi.pack()` (instead of `koffi.struct()`)
+- Change alignment of a specific member as shown below
 
 ```js
-const koffi = require('koffi');
-const lib = koffi.load('kernel32.dll');
-
-// Type declarations
-const POINT = koffi.struct('POINT', {
-    x: 'long',
-    y: 'long'
+// This struct is 3 bytes long
+const PackedStruct = koffi.pack('PackedStruct', {
+    a: 'int8_t',
+    b: 'int16_t'
 });
 
-// Functions declarations
-const GetCursorPos = lib.func('int __stdcall GetCursorPos(_Out_ POINT *pos)');
-
-// Get and show cursor position
-let pos = {};
-if (!GetCursorPos(pos))
-    throw new Error('Failed to get cursor position');
-console.log(pos);
+// This one is 18 bytes long, the second member has an alignment requirement of 16 bytes
+const BigStruct = koffi.struct('BigStruct', {
+    a: 'int8_t',
+    b: [16, 'int16_t']
+})
 ```
 
-### Opaque handles
+### Opaque types
 
-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 `FILE *` pointer. You can open and close files with `fopen()` and `fclose()`, and manipule the handle with other functions such as `fread()` or `ftell()`.
+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 `FILE *` pointer. You can open and close files with `fopen()` and `fclose()`, and manipule the opaque pointer with other functions such as `fread()` or `ftell()`.
 
-In Koffi, you can manage this with opaque handles. Declare the handle type with `koffi.handle(name)`, and use a pointer to this type either as a return type or some kind of [output parameter](functions.md#output-parameters) (with a double pointer).
+In Koffi, you can manage this with opaque types. Declare the opaque type with `koffi.opaque(name)`, and use a pointer to this type either as a return type or some kind of [output parameter](functions.md#output-parameters) (with a double pointer).
 
 ```{note}
-Opaque handles **have changed in version 2.0**.
+Opaque types **have changed in version 2.0, and again in version 2.1**.
 
 In Koffi 1.x, opaque handles were defined in a way that made them usable directly as parameter and return types, obscuring the underlying pointer.
 
 Now, you must use them through a pointer, and use an array for output parameters. This is shown in the example below (look for the call to `ConcatNewOut` in the JS part), and is described in the section on [output parameters](functions.md#output-parameters).
 
+In addition to this, you should use `koffi.opaque()` (introduced in Koffi 2.1) instead of `koffi.handle()` which is deprecated, and will be removed eventually in Koffi 3.0.
+
 Consult the [migration guide](changes.md) for more information.
 ```
 
-The full example below implements an iterative string builder (concatenator) in C, and uses it from Javascript to output a mix of Hello World and FizzBuzz. The builder is hidden behind an opaque handle, and is created and destroyed using a pair of C functions: `ConcatNew` (or `ConcatNewOut`) and `ConcatFree`.
+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: `ConcatNew` (or `ConcatNewOut`) and `ConcatFree`.
 
 ```c
 // Build with: clang -fPIC -o handles.so -shared handles.c -Wall -O2
@@ -283,7 +273,7 @@ const char *ConcatBuild(Concat *c)
 const koffi = require('koffi');
 const lib = koffi.load('./handles.so');
 
-const Concat = koffi.handle('Concat');
+const Concat = koffi.opaque('Concat');
 const ConcatNewOut = lib.func('bool ConcatNewOut(_Out_ Concat **out)');
 const ConcatNew = lib.func('Concat *ConcatNew()');
 const ConcatFree = lib.func('void ConcatFree(Concat *c)');
@@ -332,6 +322,51 @@ try {
 }
 ```
 
+## Pointer types
+
+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:
+
+- **Struct pointers**: 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).
+- **Opaque pointers**: the library does not expose the contents of the structs, and only provides you with a pointer to it (e.g. `FILE *`). 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.
+- **Arrays**: 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.
+- **Pointers to primitive types**: This is more rare, and generally used for output or input/output arguments. The Win32 API has a lot of these.
+
+### Struct pointers
+
+The following Win32 example uses `GetCursorPos()` (with an output parameter) to retrieve and show the current cursor position.
+
+```js
+const koffi = require('koffi');
+const lib = koffi.load('kernel32.dll');
+
+// Type declarations
+const POINT = koffi.struct('POINT', {
+    x: 'long',
+    y: 'long'
+});
+
+// Functions declarations
+const GetCursorPos = lib.func('int __stdcall GetCursorPos(_Out_ POINT *pos)');
+
+// Get and show cursor position
+let pos = {};
+if (!GetCursorPos(pos))
+    throw new Error('Failed to get cursor position');
+console.log(pos);
+```
+
+### Named pointer types
+
+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 **named pointer type** to an opaque type, like so:
+
+```js
+const HANDLE = koffi.pointer('HANDLE', koffi.opaque());
+
+// And now you get to use it this way:
+const GetHandleInformation = lib.func('bool __stdcall GetHandleInformation(HANDLE h, _Out_ uint32_t *flags)');
+const CloseHandle = lib.func('bool __stdcall CloseHandle(HANDLE h)');
+```
+
 ### Array pointers
 
 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).
@@ -380,7 +415,7 @@ Here is an example based on the Win32 API, listing files in the current director
 const koffi = require('koffi');
 const lib = koffi.load('kernel32.dll');
 
-const HANDLE = koffi.pointer('HANDLE', koffi.handle());
+const HANDLE = koffi.pointer('HANDLE', koffi.opaque());
 const FILETIME = koffi.struct('FILETIME', {
     dwLowDateTime: 'uint',
     dwHighDateTime: 'uint'

package/doc/dist/html/benchmarks.html

@@ -174,8 +174,8 @@
 
 </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>
-    <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>
 

package/doc/dist/html/changes.html

@@ -174,8 +174,8 @@
 
 </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>
-    <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>
 
@@ -211,6 +211,13 @@
 <h1>Changelog<a class="headerlink" href="#changelog" title="Permalink to this heading">#</a></h1>
 <section id="history">
 <h2>History<a class="headerlink" href="#history" title="Permalink to this heading">#</a></h2>
+<section id="koffi-2-0-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 +428,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 +478,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 +495,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 +527,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 +618,7 @@
             <ul>
 <li><a class="reference internal" href="#">Changelog</a><ul>
 <li><a class="reference internal" href="#history">History</a><ul>
+<li><a class="reference internal" href="#koffi-2-0-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 +641,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,8 +174,8 @@
 
 </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>
-    <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>
 

package/doc/dist/html/functions.html

@@ -174,8 +174,8 @@
 
 </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>
-    <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>
 
@@ -333,7 +333,7 @@
 <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 +370,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>
@@ -398,7 +398,7 @@
 <section id="heap-allocated-values">
 <h3>Heap-allocated values<a class="headerlink" href="#heap-allocated-values" title="Permalink to this heading">#</a></h3>
 <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>
@@ -623,7 +623,7 @@
 <li><a class="reference internal" href="#c-to-js-conversion-gotchas">C to JS conversion gotchas</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="#heap-allocated-values">Heap-allocated values</a></li>

package/doc/dist/html/genindex.html

@@ -172,8 +172,8 @@
 
 </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>
-    <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>
 

package/doc/dist/html/index.html

@@ -174,8 +174,8 @@
 
 </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>
-    <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>
 
@@ -208,7 +208,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.0.1<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>
@@ -335,7 +335,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.0.1</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,8 +174,8 @@
 
 </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>
-    <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>
 

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.0.1" href="index" />
 
     <meta name="generator" content="sphinx-5.0.1, furo 2022.06.04.1"/>
         <title>Requirements - Koffi</title>
@@ -174,8 +174,8 @@
 
 </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>
-    <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>
 

package/doc/dist/html/search.html

@@ -171,8 +171,8 @@
 
 </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>
-    <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>