koffi 2.2.3 → 2.2.4

package/ChangeLog.md

@@ -2,6 +2,16 @@
 
 ## History
 
+### Koffi 2.2.4
+
+**Main fixes:**
+
+- Fix memory leak on Windows (in Koffi 2.2.3) when running many async calls
+
+**Other changes:**
+
+- Reorganize documentation pages
+
 ### Koffi 2.2.3
 
 **Main fixes:**
@@ -37,7 +47,7 @@
 **New features:**
 
 - Add [koffi.decode()](callbacks.md#pointer-arguments) for callback pointer arguments
-- Support transparent [output string parameters](functions.md#output-parameters)
+- Support transparent [output string parameters](calls.md#output-parameters)
 - Add `koffi.offsetof()` utility function
 - Support optional *this* binding in `koffi.register()`
 
@@ -85,7 +95,7 @@
 
 **Main changes:**
 
-- Add [koffi.as()](functions.md#polymorphic-parameters) to support polymorphic APIs based on `void *` parameters
+- Add [koffi.as()](calls.md#polymorphic-parameters) to support polymorphic APIs based on `void *` parameters
 - Add [endian-sensitive integer types](types.md#endian-sensitive-types): `intX_le_t`, `intX_be_t`, `uintX_le_t`, `uintX_be_t`
 - Accept typed arrays for `void *` parameters
 - Introduce `koffi.opaque()` to replace `koffi.handle()` (which remains supported until Koffi 3.0)
@@ -109,7 +119,7 @@
 
 **Major new features:**
 
-- Add [disposable types](functions.md#heap-allocated-values) for automatic disposal of C values (such as heap-allocated strings)
+- Add [disposable types](calls.md#heap-allocated-values) for automatic disposal of C values (such as heap-allocated strings)
 - Add support for [registered callbacks](callbacks.md#registered-callbacks), that can be called after the initial FFI call
 - Support named pointer types
 - Support complex type specifications outside of prototype parser

package/doc/calls.md

@@ -0,0 +1,277 @@
+# Function calls
+
+## Call types
+
+### Synchronous calls
+
+Once a native function has been declared, you can simply call it as you would any other JS function.
+
+```js
+const atoi = lib.func('int atoi(const char *str)');
+
+let value = atoi('1257');
+console.log(value);
+```
+
+For [variadic functions](functions.md#variadic-functions), you msut specificy the type and the value for each additional argument.
+
+```js
+const printf = lib.func('printf', 'int', ['str', '...']);
+
+// The variadic arguments are: 6 (int), 8.5 (double), 'THE END' (const char *)
+printf('Integer %d, double %g, str %s', 'int', 6, 'double', 8.5, 'str', 'THE END');
+```
+
+### Asynchronous calls
+
+You can issue asynchronous calls by calling the function through its async member. In this case, you need to provide a callback function as the last argument, with `(err, res)` parameters.
+
+```js
+const koffi = require('koffi');
+const lib = koffi.load('libc.so.6');
+
+const atoi = lib.func('int atoi(const char *str)');
+
+atoi.async('1257', (err, res) => {
+    console.log('Result:', res);
+})
+console.log('Hello World!');
+
+// This program will print:
+//   Hello World!
+//   Result: 1257
+```
+
+These calls are executed by worker threads. It is **your responsibility to deal with data sharing issues** in the native code that may be caused by multi-threading.
+
+You can easily convert this callback-style async function to a promise-based version with `util.promisify()` from the Node.js standard library.
+
+Variadic functions cannot be called asynchronously.
+
+## 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 types](types.md#opaque-types)
+- String buffers
+
+In order to change an argument from input-only to output or input/output, use the following functions:
+
+- `koffi.out()` on a pointer, e.g. `koffi.out(koffi.pointer(timeval))` (where timeval is a struct type)
+- `koffi.inout()` for dual input/output parameters
+
+The same can be done when declaring a function with a C-like prototype string, with the MSDN-like type qualifiers:
+
+- `_Out_` for output parameters
+- `_Inout_` for dual input/output parameters
+
+### Struct example
+
+This example calls the POSIX function `gettimeofday()`, and uses the prototype-like syntax.
+
+```js
+const koffi = require('koffi');
+const lib = koffi.load('libc.so.6');
+
+const timeval = koffi.struct('timeval', {
+    tv_sec: 'unsigned int',
+    tv_usec: 'unsigned int'
+});
+const timezone = koffi.struct('timezone', {
+    tz_minuteswest: 'int',
+    tz_dsttime: 'int'
+});
+
+// The _Out_ qualifiers instruct Koffi to marshal out the values
+const gettimeofday = lib.func('int gettimeofday(_Out_ timeval *tv, _Out_ timezone *tz)');
+
+let tv = {};
+gettimeofday(tv, null);
+
+console.log(tv);
+```
+
+### 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('sqlite3.so');
+
+const sqlite3 = koffi.opaque('sqlite3');
+
+// Use koffi.out() on a double pointer to copy out (from C to JS) after the call
+const sqlite3_open_v2 = lib.func('sqlite3_open_v2', 'int', ['str', koffi.out(koffi.pointer(sqlite3, 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 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);
+```
+
+### String buffer example
+
+*New in Koffi 2.2*
+
+This example calls a C function to concatenate two strings to a pre-allocated string buffer. Since JS strings are immutable, you must pass an array with a single string instead.
+
+```c
+void ConcatToBuffer(const char *str1, const char *str2, char *out)
+{
+    size_t len = 0;
+
+    for (size_t i = 0; str1[i]; i++) {
+        out[len++] = str1[i];
+    }
+    for (size_t i = 0; str2[i]; i++) {
+        out[len++] = str2[i];
+    }
+
+    out[len] = 0;
+}
+```
+
+```js
+const ConcatToBuffer = lib.func('void ConcatToBuffer(const char *str1, const char *str2, _Out_ char *out)');
+
+let str1 = 'Hello ';
+let str2 = 'Friends!';
+
+// We need to reserve space for the output buffer! Including the NUL terminator
+// because ConcatToBuffer() expects so, but Koffi can convert back to a JS string
+// without it (if we reserve the right size).
+let out = ['\0'.repeat(str1.length + str2.length + 1)];
+
+ConcatToBuffer(str1, str2, out);
+
+console.log(out[0]);
+```
+
+## Polymorphic parameters
+
+*New in Koffi 2.1*
+
+Many C functions use `void *` 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.
+
+Koffi provides two features to deal with this:
+
+- Typed JS arrays can be used as values in place everywhere `void *` is expected. See [dynamic arrays](types.md#array-pointers-dynamic-arrays) for more information, for input or output.
+- You can use `koffi.as(value, type)` to tell Koffi what kind of type is actually expected.
+
+The example below shows the use of `koffi.as()` to read the header of a PNG file with `fread()`.
+
+```js
+const koffi = require('koffi');
+const lib = koffi.load('libc.so.6');
+
+const FILE = koffi.opaque('FILE');
+
+const PngHeader = koffi.pack('PngHeader', {
+    signature: koffi.array('uint8_t', 8),
+    ihdr: koffi.pack({
+        length: 'uint32_be_t',
+        chunk: koffi.array('char', 4),
+        width: 'uint32_be_t',
+        height: 'uint32_be_t',
+        depth: 'uint8_t',
+        color: 'uint8_t',
+        compression: 'uint8_t',
+        filter: 'uint8_t',
+        interlace: 'uint8_t',
+        crc: 'uint32_be_t'
+    })
+});
+
+const fopen = lib.func('FILE *fopen(const char *path, const char *mode)');
+const fclose = lib.func('int fclose(FILE *fp)');
+const fread = lib.func('size_t fread(_Out_ void *ptr, size_t size, size_t nmemb, FILE *fp)');
+
+let filename = process.argv[2];
+if (filename == null)
+    throw new Error('Usage: node png.js <image.png>');
+
+let hdr = {};
+{
+
+    let fp = fopen(filename, 'rb');
+    if (!fp)
+        throw new Error(`Failed to open '${filename}'`);
+
+    try {
+        let len = fread(koffi.as(hdr, 'PngHeader *'), 1, koffi.sizeof(PngHeader), fp);
+        if (len < koffi.sizeof(PngHeader))
+            throw new Error('Failed to read PNG header');
+    } finally {
+        fclose(fp);
+    }
+}
+
+console.log('PNG header:', hdr);
+```
+
+## Heap-allocated values
+
+*New in Koffi 2.0*
+
+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](functions.md#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()`.
+```
+
+## Thread safety
+
+Asynchronous functions run on worker threads. You need to deal with thread safety issues if you share data between threads.
+
+Callbacks must be called from the main thread, or more precisely from the same thread as the V8 intepreter. Calling a callback from another thread is undefined behavior, and will likely lead to a crash or a big mess. You've been warned!

package/doc/functions.md

@@ -1,6 +1,6 @@
-# Functions
+# Function definitions
 
-## Function definitions
+## Definition syntax
 
 To declare functions, start by loading the shared library with `koffi.load(filename)`.
 
@@ -36,9 +36,22 @@ const atoi = lib.func('int atoi(str)'); // The parameter name is not used by Kof
 
 You can use `()` or `(void)` for functions that take no argument.
 
-## Function calls
+## Variadic functions
 
-### Calling conventions
+Variadic functions are declared with an ellipsis as the last argument.
+
+In order to call a variadic function, you must provide two Javascript arguments for each additional C parameter, the first one is the expected type and the second one is the value.
+
+```js
+const printf = lib.func('printf', 'int', ['str', '...']);
+
+// The variadic arguments are: 6 (int), 8.5 (double), 'THE END' (const char *)
+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.
+
+## Calling conventions
 
 By default, calling a C function happens synchronously.
 
@@ -63,274 +76,3 @@ const lib = koffi.load('user32.dll');
 const MessageBoxA_1 = lib.stdcall('MessageBoxA', 'int', ['void *', 'str', 'str', 'uint']);
 const MessageBoxA_2 = lib.func('int __stdcall MessageBoxA(void *hwnd, str text, str caption, uint type)');
 ```
-
-### Asynchronous calls
-
-You can issue asynchronous calls by calling the function through its async member. In this case, you need to provide a callback function as the last argument, with `(err, res)` parameters.
-
-```js
-const koffi = require('koffi');
-const lib = koffi.load('libc.so.6');
-
-const atoi = lib.func('int atoi(const char *str)');
-
-atoi.async('1257', (err, res) => {
-    console.log('Result:', res);
-})
-console.log('Hello World!');
-
-// This program will print:
-//   Hello World!
-//   Result: 1257
-```
-
-These calls are executed by worker threads. It is **your responsibility to deal with data sharing issues** in the native code that may be caused by multi-threading.
-
-You can easily convert this callback-style async function to a promise-based version with `util.promisify()` from the Node.js standard library.
-
-Variadic functions cannot be called asynchronously.
-
-### Variadic functions
-
-Variadic functions are declared with an ellipsis as the last argument.
-
-In order to call a variadic function, you must provide two Javascript arguments for each additional C parameter, the first one is the expected type and the second one is the value.
-
-```js
-const printf = lib.func('printf', 'int', ['str', '...']);
-
-// The variadic arguments are: 6 (int), 8.5 (double), 'THE END' (const char *)
-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.
-
-## Special considerations
-
-### 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 types](types.md#opaque-types)
-- String buffers
-
-In order to change an argument from input-only to output or input/output, use the following functions:
-
-- `koffi.out()` on a pointer, e.g. `koffi.out(koffi.pointer(timeval))` (where timeval is a struct type)
-- `koffi.inout()` for dual input/output parameters
-
-The same can be done when declaring a function with a C-like prototype string, with the MSDN-like type qualifiers:
-
-- `_Out_` for output parameters
-- `_Inout_` for dual input/output parameters
-
-#### Struct example
-
-This example calls the POSIX function `gettimeofday()`, and uses the prototype-like syntax.
-
-```js
-const koffi = require('koffi');
-const lib = koffi.load('libc.so.6');
-
-const timeval = koffi.struct('timeval', {
-    tv_sec: 'unsigned int',
-    tv_usec: 'unsigned int'
-});
-const timezone = koffi.struct('timezone', {
-    tz_minuteswest: 'int',
-    tz_dsttime: 'int'
-});
-
-// The _Out_ qualifiers instruct Koffi to marshal out the values
-const gettimeofday = lib.func('int gettimeofday(_Out_ timeval *tv, _Out_ timezone *tz)');
-
-let tv = {};
-gettimeofday(tv, null);
-
-console.log(tv);
-```
-
-#### 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('sqlite3.so');
-
-const sqlite3 = koffi.opaque('sqlite3');
-
-// Use koffi.out() on a double pointer to copy out (from C to JS) after the call
-const sqlite3_open_v2 = lib.func('sqlite3_open_v2', 'int', ['str', koffi.out(koffi.pointer(sqlite3, 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 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);
-```
-
-#### String buffer example
-
-*New in Koffi 2.2*
-
-This example calls a C function to concatenate two strings to a pre-allocated string buffer. Since JS strings are immutable, you must pass an array with a single string instead.
-
-```c
-void ConcatToBuffer(const char *str1, const char *str2, char *out)
-{
-    size_t len = 0;
-
-    for (size_t i = 0; str1[i]; i++) {
-        out[len++] = str1[i];
-    }
-    for (size_t i = 0; str2[i]; i++) {
-        out[len++] = str2[i];
-    }
-
-    out[len] = 0;
-}
-```
-
-```js
-const ConcatToBuffer = lib.func('void ConcatToBuffer(const char *str1, const char *str2, _Out_ char *out)');
-
-let str1 = 'Hello ';
-let str2 = 'Friends!';
-
-// We need to reserve space for the output buffer! Including the NUL terminator
-// because ConcatToBuffer() expects so, but Koffi can convert back to a JS string
-// without it (if we reserve the right size).
-let out = ['\0'.repeat(str1.length + str2.length + 1)];
-
-ConcatToBuffer(str1, str2, out);
-
-console.log(out[0]);
-```
-
-### Polymorphic parameters
-
-*New in Koffi 2.1*
-
-Many C functions use `void *` 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.
-
-Koffi provides two features to deal with this:
-
-- Typed JS arrays can be used as values in place everywhere `void *` is expected. See [dynamic arrays](types.md#array-pointers-dynamic-arrays) for more information, for input or output.
-- You can use `koffi.as(value, type)` to tell Koffi what kind of type is actually expected.
-
-The example below shows the use of `koffi.as()` to read the header of a PNG file with `fread()`.
-
-```js
-const koffi = require('koffi');
-const lib = koffi.load('libc.so.6');
-
-const FILE = koffi.opaque('FILE');
-
-const PngHeader = koffi.pack('PngHeader', {
-    signature: koffi.array('uint8_t', 8),
-    ihdr: koffi.pack({
-        length: 'uint32_be_t',
-        chunk: koffi.array('char', 4),
-        width: 'uint32_be_t',
-        height: 'uint32_be_t',
-        depth: 'uint8_t',
-        color: 'uint8_t',
-        compression: 'uint8_t',
-        filter: 'uint8_t',
-        interlace: 'uint8_t',
-        crc: 'uint32_be_t'
-    })
-});
-
-const fopen = lib.func('FILE *fopen(const char *path, const char *mode)');
-const fclose = lib.func('int fclose(FILE *fp)');
-const fread = lib.func('size_t fread(_Out_ void *ptr, size_t size, size_t nmemb, FILE *fp)');
-
-let filename = process.argv[2];
-if (filename == null)
-    throw new Error('Usage: node png.js <image.png>');
-
-let hdr = {};
-{
-
-    let fp = fopen(filename, 'rb');
-    if (!fp)
-        throw new Error(`Failed to open '${filename}'`);
-
-    try {
-        let len = fread(koffi.as(hdr, 'PngHeader *'), 1, koffi.sizeof(PngHeader), fp);
-        if (len < koffi.sizeof(PngHeader))
-            throw new Error('Failed to read PNG header');
-    } finally {
-        fclose(fp);
-    }
-}
-
-console.log('PNG header:', hdr);
-```
-
-### Heap-allocated values
-
-*New in Koffi 2.0*
-
-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()`.
-```
-
-## Thread safety
-
-Asynchronous functions run on worker threads. You need to deal with thread safety issues if you share data between threads.
-
-Callbacks must be called from the main thread, or more precisely from the same thread as the V8 intepreter. Calling a callback from another thread is undefined behavior, and will likely lead to a crash or a big mess. You've been warned!

package/doc/index.rst

@@ -25,9 +25,11 @@ Table of contents
    platforms
    start
    types
+   pointers
    functions
+   calls
    callbacks
-   memory
+   misc
    benchmarks
    contribute
    changes

package/doc/misc.md

@@ -0,0 +1,97 @@
+# Miscellaneous
+
+## Types
+
+### Introspection
+
+*New in Koffi 2.0: `koffi.resolve()`, new in Koffi 2.2: `koffi.offsetof()`*
+
+```{note}
+The value returned by `introspect()` has **changed in version 2.0 and in version 2.2**.
+
+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.
+
+Starting in Koffi 2.2, each record member is exposed as an object containing the name, the type and the offset within the record.
+
+Consult the [migration guide](changes.md) for more information.
+```
+
+Use `koffi.introspect(type)` to get detailed information about a type: name, primitive, size, alignment, members (record types), reference type (array, pointer) and length (array).
+
+```js
+const FoobarType = koffi.struct('FoobarType', {
+    a: 'int',
+    b: 'char *',
+    c: 'double'
+});
+
+console.log(koffi.introspect(FoobarType));
+
+// Expected result on 64-bit machines:
+// {
+//     name: 'FoobarType',
+//     primitive: 'Record',
+//     size: 24,
+//     alignment: 8,
+//     members: {
+//         a: { name: 'a', type: [External: 4b28a60], offset: 0 },
+//         b: { name: 'b', type: [External: 4b292e0], offset: 8 },
+//         c: { name: 'c', type: [External: 4b29260], offset: 16 }
+//     }
+// }
+```
+
+Koffi also exposes a few more utility functions to get a subset of this information:
+
+- `koffi.sizeof(type)` to get the size of a type
+- `koffi.alignof(type)` to get the alignment of a type
+- `koffi.offsetof(type, member_name)` to get the offset of a record member
+- `koffi.resolve(type)` to get the resolved type object from a type string
+
+Just like before, you can refer to primitive types by their name or through `koffi.types`:
+
+```js
+// These two lines do the same:
+console.log(koffi.sizeof('long'));
+console.log(koffi.sizeof(koffi.types.long));
+```
+
+### Aliases
+
+*New in Koffi 2.0*
+
+You can alias a type with `koffi.alias(name, type)`. Aliased types are completely equivalent.
+
+## Settings
+
+### Memory usage
+
+For synchronous/normal calls, Koffi uses two preallocated memory blocks:
+
+- One to construct the C stack and assign registers, subsequently used by the platform-specific assembly code (1 MiB by default)
+- One to allocate strings and big objects/structs (2 MiB by default)
+
+Unless very big strings or objects (at least more than one page of memory) are used, Koffi does not directly allocate any extra memory during calls or callbacks. However, please note that the JS engine (V8) might.
+
+The size (in bytes) of these preallocated blocks can be changed. Use `koffi.config()` to get an object with the settings, and `koffi.config(obj)` to apply new settings.
+
+```js
+let config = koffi.config();
+console.log(config);
+```
+
+The same is true for asynchronous calls. When an asynchronous call is made, Koffi will allocate new blocks unless there is an unused (resident) set of blocks still available. Once the asynchronous call is finished, these blocks are freed if there are more than `resident_async_pools` sets of blocks left around.
+
+There cannot be more than `max_async_calls` running at the same time.
+
+### Default settings
+
+Setting              | Default | Description
+-------------------- | ------- | -----------------------------------------------
+sync_stack_size      | 1 MiB   | Stack size for synchronous calls
+sync_heap_size       | 2 MiB   | Heap size for synchronous calls
+async_stack_size     | 256 kiB | Stack size for asynchronous calls
+async_heap_size      | 512 kiB | Heap size for asynchronous calls
+resident_async_pools | 2       | Number of resident pools for asynchronous calls
+max_async_calls      | 64      | Maximum number of ongoing asynchronous calls
+max_type_size        | 64 MiB  | Maximum size of Koffi types (for arrays and structs)

package/doc/pointers.md

@@ -0,0 +1,135 @@
+# Data pointers
+
+## How pointers are used
+
+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.
+- **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.
+- **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.
+
+## Pointer types
+
+### 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);
+```
+
+### Opaque pointers
+
+*New in Koffi 2.0*
+
+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)');
+```
+
+### Pointer to primitive types
+
+In javascript, it is not possible to pass a primitive value by reference to another function. This means that you cannot call a function and expect it to modify the value of one of its number or string parameter.
+
+However, arrays and objects (among others) are reference type values. Assigning an array or an object from one variable to another does not invole any copy. Instead, as the following example illustrates, the new variable references the same array as the first:
+
+```js
+let list1 = [1, 2];
+let list2 = list1;
+
+list2[1] = 42;
+
+console.log(list1); // Prints [1, 42]
+```
+
+All of this means that C functions that are expected to modify their primitive output values (such as an `int *` parameter) cannot be used directly. However, thanks to Koffi's transparent array support, you can use Javascript arrays to approximate reference semantics with single-element arrays.
+
+Below, you can find an example of an addition function where the result is stored in an `int *` input/output parameter and how to use this function from Koffi.
+
+```c
+void AddInt(int *dest, int add)
+{
+    *dest += add;
+}
+```
+
+You can simply pass a single-element array as the first argument:
+
+```js
+const AddInt = lib.func('void AddInt(_Inout_ int *dest, int add)');
+
+let sum = [36];
+AddInt(sum, 6);
+
+console.log(sum[0]); // Prints 42
+```
+
+### Array pointers (dynamic arrays)
+
+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).
+
+Koffi can translate JS arrays and TypedArrays to pointer arguments. However, because C does not have a proper notion of dynamically-sized arrays (fat pointers), you need to provide the length or the sentinel value yourself depending on the API.
+
+Here is a simple example of a C function taking a NULL-terminated list of strings as input, to calculate the total length of all strings.
+
+```c
+// Build with: clang -fPIC -o length.so -shared length.c -Wall -O2
+
+#include <stdlib.h>
+#include <stdint.h>
+#include <string.h>
+
+int64_t ComputeTotalLength(const char **strings)
+{
+    int64_t total = 0;
+
+    for (const char **ptr = strings; *ptr; ptr++) {
+        const char *str = *ptr;
+        total += strlen(str);
+    }
+
+    return total;
+}
+```
+
+```js
+const koffi = require('koffi');
+const lib = koffi.load('./length.so');
+
+const ComputeTotalLength = lib.func('int64_t ComputeTotalLength(const char **strings)');
+
+let strings = ['Get', 'Total', 'Length', null];
+let total = ComputeTotalLength(strings);
+
+console.log(total); // Prints 14
+```
+
+By default, just like for objects, array arguments are copied from JS to C but not vice-versa. You can however change the direction as documented in the section on [output parameters](calls.md#output-parameters).
+
+## Disposable types
+
+Disposable types allow you to register a function that will automatically called after each C to JS conversion performed by Koffi. This can be used to avoid leaking heap-allocated strings, for example.
+
+Read the documentation for [disposable types](calls.md#heap-allocated-values) on the page about function calls.

package/doc/types.md

@@ -142,14 +142,14 @@ const Function2 = lib.func('Function', A, [A]);
 
 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 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).
+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](calls.md#output-parameters) (with a double pointer).
 
 ```{note}
 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).
+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](calls.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.
 
@@ -330,90 +330,6 @@ 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.
-- **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.
-- **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.
-
-### 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
-
-*New in Koffi 2.0*
-
-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)');
-```
-
-### Pointers to primitive types
-
-In javascript, it is not possible to pass a primitive value by reference to another function. This means that you cannot call a function and expect it to modify the value of one of its number or string parameter.
-
-However, arrays and objects (among others) are reference type values. Assigning an array or an object from one variable to another does not invole any copy. Instead, as the following example illustrates, the new variable references the same array as the first:
-
-```js
-let list1 = [1, 2];
-let list2 = list1;
-
-list2[1] = 42;
-
-console.log(list1); // Prints [1, 42]
-```
-
-All of this means that C functions that are expected to modify their primitive output values (such as an `int *` parameter) cannot be used directly. However, thanks to Koffi's transparent array support, you can use Javascript arrays to approximate reference semantics with single-element arrays.
-
-Below, you can find an example of an addition function where the result is stored in an `int *` input/output parameter and how to use this function from Koffi.
-
-```c
-void AddInt(int *dest, int add)
-{
-    *dest += add;
-}
-```
-
-You can simply pass a single-element array as the first argument:
-
-```js
-const AddInt = lib.func('void AddInt(_Inout_ int *dest, int add)');
-
-let sum = [36];
-AddInt(sum, 6);
-
-console.log(sum[0]); // Prints 42
-```
-
 ## Array types
 
 ### Fixed-size C arrays
@@ -459,110 +375,4 @@ The reverse case is also true, Koffi can convert a C fixed-size buffer to a JS s
 
 ### Array pointers (dynamic arrays)
 
-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).
-
-Koffi can translate JS arrays and TypedArrays to pointer arguments. However, because C does not have a proper notion of dynamically-sized arrays (fat pointers), you need to provide the length or the sentinel value yourself depending on the API.
-
-Here is a simple example of a C function taking a NULL-terminated list of strings as input, to calculate the total length of all strings.
-
-```c
-// Build with: clang -fPIC -o length.so -shared length.c -Wall -O2
-
-#include <stdlib.h>
-#include <stdint.h>
-#include <string.h>
-
-int64_t ComputeTotalLength(const char **strings)
-{
-    int64_t total = 0;
-
-    for (const char **ptr = strings; *ptr; ptr++) {
-        const char *str = *ptr;
-        total += strlen(str);
-    }
-
-    return total;
-}
-```
-
-```js
-const koffi = require('koffi');
-const lib = koffi.load('./length.so');
-
-const ComputeTotalLength = lib.func('int64_t ComputeTotalLength(const char **strings)');
-
-let strings = ['Get', 'Total', 'Length', null];
-let total = ComputeTotalLength(strings);
-
-console.log(total); // Prints 14
-```
-
-By default, just like for objects, array arguments are copied from JS to C but not vice-versa. You can however change the direction as documented in the section on [output parameters](functions.md#output-parameters).
-
-## Disposable types
-
-Disposable types allow you to register a function that will automatically called after each C to JS conversion performed by Koffi. This can be used to avoid leaking heap-allocated strings, for example.
-
-Read the documentation for [disposable types](functions.md#heap-allocated-values) on the page about function calls.
-
-## Utility functions
-
-### Type introspection
-
-*New in Koffi 2.0: `koffi.resolve()`, new in Koffi 2.2: `koffi.offsetof()`*
-
-```{note}
-The value returned by `introspect()` has **changed in version 2.0 and in version 2.2**.
-
-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.
-
-Starting in Koffi 2.2, each record member is exposed as an object containing the name, the type and the offset within the record.
-
-Consult the [migration guide](changes.md) for more information.
-```
-
-Use `koffi.introspect(type)` to get detailed information about a type: name, primitive, size, alignment, members (record types), reference type (array, pointer) and length (array).
-
-```js
-const FoobarType = koffi.struct('FoobarType', {
-    a: 'int',
-    b: 'char *',
-    c: 'double'
-});
-
-console.log(koffi.introspect(FoobarType));
-
-// Expected result on 64-bit machines:
-// {
-//     name: 'FoobarType',
-//     primitive: 'Record',
-//     size: 24,
-//     alignment: 8,
-//     members: {
-//         a: { name: 'a', type: [External: 4b28a60], offset: 0 },
-//         b: { name: 'b', type: [External: 4b292e0], offset: 8 },
-//         c: { name: 'c', type: [External: 4b29260], offset: 16 }
-//     }
-// }
-```
-
-Koffi also exposes a few more utility functions to get a subset of this information:
-
-- `koffi.sizeof(type)` to get the size of a type
-- `koffi.alignof(type)` to get the alignment of a type
-- `koffi.offsetof(type, member_name)` to get the offset of a record member
-- `koffi.resolve(type)` to get the resolved type object from a type string
-
-Just like before, you can refer to primitive types by their name or through `koffi.types`:
-
-```js
-// These two lines do the same:
-console.log(koffi.sizeof('long'));
-console.log(koffi.sizeof(koffi.types.long));
-```
-
-### Type aliases
-
-*New in Koffi 2.0*
-
-You can alias a type with `koffi.alias(name, type)`. Aliased types are completely equivalent.
+In C, dynamically-sized arrays are usually passed around as pointers. Read more about [array pointers](pointers.md#array-pointers-dynamic-arrays) in the relevant section.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "koffi",
-    "version": "2.2.3",
-    "stable": "2.2.3",
+    "version": "2.2.4",
+    "stable": "2.2.4",
     "description": "Fast and simple C FFI (foreign function interface) for Node.js",
     "keywords": [
         "foreign",

package/src/koffi/src/ffi.cc

@@ -1723,8 +1723,8 @@ void FunctionInfo::Unref() const
 InstanceMemory::~InstanceMemory()
 {
 #ifdef _WIN32
-    if (fiber) {
-        DeleteFiber(fiber);
+    if (stack.ptr) {
+        VirtualFree(stack.ptr, 0, MEM_RELEASE);
     }
     if (heap.ptr) {
         VirtualFree(heap.ptr, 0, MEM_RELEASE);

package/src/koffi/src/ffi.hh

@@ -232,10 +232,6 @@ struct InstanceMemory {
 
     int16_t depth;
     bool temporary;
-
-#ifdef _WIN32
-    void *fiber;
-#endif
 };
 
 struct InstanceData {

package/doc/memory.md

@@ -1,33 +0,0 @@
-# Memory usage
-
-## How it works
-
-For synchronous/normal calls, Koffi uses two preallocated memory blocks:
-
-- One to construct the C stack and assign registers, subsequently used by the platform-specific assembly code (1 MiB by default)
-- One to allocate strings and big objects/structs (2 MiB by default)
-
-Unless very big strings or objects (at least more than one page of memory) are used, Koffi does not directly allocate any extra memory during calls or callbacks. However, please note that the JS engine (V8) might.
-
-The size (in bytes) of these preallocated blocks can be changed. Use `koffi.config()` to get an object with the settings, and `koffi.config(obj)` to apply new settings.
-
-```js
-let config = koffi.config();
-console.log(config);
-```
-
-The same is true for asynchronous calls. When an asynchronous call is made, Koffi will allocate new blocks unless there is an unused (resident) set of blocks still available. Once the asynchronous call is finished, these blocks are freed if there are more than `resident_async_pools` sets of blocks left around.
-
-There cannot be more than `max_async_calls` running at the same time.
-
-## Default settings
-
-Setting              | Default | Description
--------------------- | ------- | -----------------------------------------------
-sync_stack_size      | 1 MiB   | Stack size for synchronous calls
-sync_heap_size       | 2 MiB   | Heap size for synchronous calls
-async_stack_size     | 256 kiB | Stack size for asynchronous calls
-async_heap_size      | 512 kiB | Heap size for asynchronous calls
-resident_async_pools | 2       | Number of resident pools for asynchronous calls
-max_async_calls      | 64      | Maximum number of ongoing asynchronous calls
-max_type_size        | 64 MiB  | Maximum size of Koffi types (for arrays and structs)