koffi 2.3.21-beta.4 → 2.4.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Version history
 
+### Koffi 2.4
+
+#### Koffi 2.4.1
+
+**Main changes:**
+
+- Support decoding pointers to callable functions
+- Support calling function pointers with [koffi.call()]
+- Deprecate `koffi.callback` in favor of `koffi.proto`
+
+**Other changes:**
+
+- Increase maximum number of callbacks to 8192
+- Build Koffi with static CRT on Windows
+- Reorganize Koffi data conversion documentation
+- Add deprecated `koffi.handle` to TS file
+
 ### Koffi 2.3
 
 #### Koffi 2.3.20
@@ -133,7 +150,7 @@
 
 **Main changes:**
 
-- Fix type parser issues (such as ignoring some [disposable qualifiers](calls.md#heap-allocated-values))
+- Fix type parser issues (such as ignoring some [disposable qualifiers](parameters.md#heap-allocated-values))
 - Fix crash when using disposable types in output parameters
 - Add basic [koffi.stats()](misc.md#usage-statistics) interface
 
@@ -155,7 +172,7 @@
 **Main changes:**
 
 - Allow buffers (TypedArray or ArrayBuffer) values for input and/or output pointer arguments (for polymorphic arguments)
-- Support opaque buffers (TypedArray or ArrayBuffer) values in `koffi.decode()` to [decode output buffers](calls.md#output-buffers)
+- Support opaque buffers (TypedArray or ArrayBuffer) values in `koffi.decode()` to [decode output buffers](parameters.md#output-buffers)
 - Decode non-string types as arrays when an [explicit length is passed to koffi.decode()](callbacks.md#decoding-pointer-arguments)
 
 **Other changes:**
@@ -220,7 +237,7 @@
 **New features:**
 
 - Add [koffi.decode()](callbacks.md#decoding-pointer-arguments) for callback pointer arguments
-- Support transparent [output string parameters](calls.md#output-parameters)
+- Support transparent [output string parameters](parameters.md#output-parameters)
 - Add `koffi.offsetof()` utility function
 - Support optional *this* binding in `koffi.register()`
 
@@ -270,7 +287,7 @@
 
 **Main changes:**
 
-- Add [koffi.as()](calls.md#polymorphic-parameters) to support polymorphic APIs based on `void *` parameters
+- Add [koffi.as()](parameters.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)
@@ -296,7 +313,7 @@
 
 **Major new features:**
 
-- Add [disposable types](calls.md#heap-allocated-values) for automatic disposal of C values (such as heap-allocated strings)
+- Add [disposable types](parameters.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/callbacks.md

@@ -1,5 +1,11 @@
 # Callbacks
 
+*Changed in Koffi 2.4*
+
+```{note}
+The function `koffi.proto()` was introduced in Koffi 2.4, it was called `koffi.callback()` in earlier versions.
+```
+
 ## Callback types
 
 In order to pass a JS function to a C function expecting a callback, you must first create a callback type with the expected return type and parameters. The syntax is similar to the one used to load functions from a shared library.
@@ -8,10 +14,10 @@ In order to pass a JS function to a C function expecting a callback, you must fi
 const koffi = require('koffi');
 
 // With the classic syntax, this callback expects an integer and returns nothing
-const ExampleCallback = koffi.callback('ExampleCallback', 'void', ['int']);
+const ExampleCallback = koffi.proto('ExampleCallback', 'void', ['int']);
 
 // With the prototype parser, this callback expects a double and float, and returns the sum as a double
-const AddDoubleFloat = koffi.callback('double AddDoubleFloat(double d, float f)');
+const AddDoubleFloat = koffi.proto('double AddDoubleFloat(double d, float f)');
 ```
 
 Once your callback type is declared, you can use a pointer to it in struct definitions, or as function parameters and/or return types.
@@ -56,7 +62,7 @@ int TransferToJS(const char *name, int age, int (*cb)(const char *str, int age))
 const koffi = require('koffi');
 const lib = koffi.load('./callbacks.so'); // Fake path
 
-const TransferCallback = koffi.callback('int TransferCallback(const char *str, int age)');
+const TransferCallback = koffi.proto('int TransferCallback(const char *str, int age)');
 
 const TransferToJS = lib.func('TransferToJS', 'int', ['str', 'int', koffi.pointer(TransferCallback)]);
 
@@ -104,8 +110,8 @@ void SayIt(const char *name)
 const koffi = require('koffi');
 const lib = koffi.load('./callbacks.so'); // Fake path
 
-const GetCallback = koffi.callback('const char *GetCallback(const char *name)');
-const PrintCallback = koffi.callback('void PrintCallback(const char *str)');
+const GetCallback = koffi.proto('const char *GetCallback(const char *name)');
+const PrintCallback = koffi.proto('void PrintCallback(const char *str)');
 
 const RegisterFunctions = lib.func('void RegisterFunctions(GetCallback *cb1, PrintCallback *cb2)');
 const SayIt = lib.func('void SayIt(const char *name)');
@@ -155,7 +161,7 @@ The following example sorts an array of strings (in-place) with `qsort()`:
 const koffi = require('koffi');
 const lib = koffi.load('libc.so.6');
 
-const SortCallback = koffi.callback('int SortCallback(const void *first, const void *second)');
+const SortCallback = koffi.proto('int SortCallback(const void *first, const void *second)');
 const qsort = lib.func('void qsort(_Inout_ void *array, size_t count, size_t size, SortCallback *cb)');
 
 let array = ['foo', 'bar', '123', 'foobar'];

package/doc/conf.py

@@ -65,7 +65,7 @@ html_theme_options = {
     }
 }
 
-html_link_suffix = ''
+# html_link_suffix = ''
 
 html_css_files = ['custom.css']
 

package/doc/functions.md

@@ -1,4 +1,4 @@
-# Library functions
+# Native functions
 
 ## Loading libraries
 
@@ -88,3 +88,57 @@ 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)');
 ```
+
+## Function calls
+
+### 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.
+
+## 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

@@ -23,10 +23,10 @@ Table of contents
 
    platforms
    start
+   functions
    types
    pointers
-   functions
-   calls
+   parameters
    callbacks
    misc
    benchmarks

package/doc/migration.md

@@ -32,7 +32,7 @@ The two versions below illustrate the API difference between Koffi 1.x and Koffi
 ```js
 // Koffi 1.x
 
-const TransferCallback = koffi.callback('int TransferCallback(const char *str, int age)');
+const TransferCallback = koffi.proto('int TransferCallback(const char *str, int age)');
 
 const TransferToJS = lib.func('TransferToJS', 'int', ['str', 'int', TransferCallback]);
 // Equivalent to: const TransferToJS = lib.func('int TransferToJS(str s, int x, TransferCallback cb)');
@@ -48,7 +48,7 @@ console.log(ret);
 ```js
 // Koffi 2.x
 
-const TransferCallback = koffi.callback('int TransferCallback(const char *str, int age)');
+const TransferCallback = koffi.proto('int TransferCallback(const char *str, int age)');
 
 const TransferToJS = lib.func('TransferToJS', 'int', ['str', 'int', koffi.pointer(TransferCallback)]);
 // Equivalent to: const TransferToJS = lib.func('int TransferToJS(str s, int x, TransferCallback *cb)');
@@ -63,6 +63,10 @@ console.log(ret);
 
 Koffi 1.x only supported [transient callbacks](callbacks.md#callbacks), you must use Koffi 2.x for registered callbacks.
 
+```{note}
+The function `koffi.proto()` was introduced in Koffi 2.4, it was called `koffi.callback()` in earlier versions.
+```
+
 ### Opaque types
 
 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.

package/doc/{calls.md → parameters.md}

@@ -1,57 +1,11 @@
-# Function calls
+# Special parameters
 
-## Call types
+## Direction
 
-### 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.
+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.
 
 ## 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)
@@ -348,7 +302,7 @@ 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)`.
+When you declare functions with the [prototype-like syntax](functions.md#definition-syntax), 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');
@@ -366,9 +320,3 @@ 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/pointers.md

@@ -126,13 +126,13 @@ 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).
+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](parameters.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.
+Read the documentation for [disposable types](parameters.md#heap-allocated-values) on the page about function calls.
 
 ## Unwrap pointers
 

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](calls.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](parameters.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](calls.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](parameters.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.
 

package/package.json

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