koffi 1.2.4 → 1.3.0-rc.1

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

@@ -0,0 +1,224 @@
+# Function calls
+
+## Function definitions
+
+To declare functions, start by loading the shared library with `koffi.load()`.
+
+```js
+const koffi = require('koffi');
+const lib = koffi.load('/path/to/shared/library'); // File extension depends on platforms: .so, .dll, .dylib, etc.
+```
+
+You can use the returned object to load C functions from the library. Koffi supports two syntaxes:
+
+- Classic syntax, inspired by node-ffi
+- C-like prototypes
+
+### Classic syntax
+
+To declare a function, you need to specify its non-mangled name, its return type, and its parameters. Use an ellipsis as the last parameter for variadic functions.
+
+```js
+const printf = lib.func('printf', 'int', ['string', '...']);
+const atoi = lib.func('atoi', 'int', ['string']);
+```
+
+Koffi automatically tries mangled names for non-standard x86 calling conventions. See the section [on standard calls](#synchronous-calls) for more information on this subject.
+
+### C-like prototypes
+
+You can declare functions using simple C-like prototype strings, as shown below:
+
+```js
+const printf = lib.func('int printf(const char *fmt, ...)');
+const atoi = lib.func('int atoi(string)'); // The parameter name is not used by Koffi, and optional
+```
+
+## Synchronous calls
+
+By default, calling a C function happens synchronously.
+
+Most architectures only support one procedure call standard per process. The 32-bit x86 platform is an exception to this, and Koffi support several standards:
+
+ Convention   | Classic form                  | Prototype form | Description
+------------- | ----------------------------- | -------------- | -------------------------------------------------------------------
+ **Cdecl**    | `koffi.cdecl` or `koffi.func` | _(default)_    | This is the default convention, and the only one on other platforms
+ **Stdcall**  | `koffi.stdcall`               | __stdcall      | This convention is used extensively within the Win32 API
+ **Fastcall** | `koffi.fastcall`              | __fastcall     | Rarely used, uses ECX and EDX for first two parameters
+ **Thiscall** | `koffi.thiscall`              | __thiscall     | Rarely used, uses ECX for first parameter
+
+You can safely use these on non-x86 platforms, they are simply ignored.
+
+Below you can find a small example showing how to use a non-default calling convention:
+
+```js
+const koffi = require('koffi');
+const lib = koffi.load('user32.dll');
+
+// The following two declarations are equivalent, and use Stdcall
+const MessageBoxA_1 = lib.stdcall('MessageBoxA', 'int', ['void *', 'string', 'string', 'uint']);
+const MessageBoxA_2 = lib.func('int __stdcall MessageBoxA(void *hwnd, string text, string 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!", and then "Result: 1257"
+```
+
+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', ['string', '...']);
+
+// The variadic arguments are: 6 (int), 8.5 (double), 'THE END' (const char *)
+printf('Integer %d, double %g, string %s', 'int', 6, 'double', 8.5, 'string', 'THE END');
+```
+
+On x86 platforms, only the Cdecl convention can be used for variadic functions.
+
+## 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 simplicy, and because Javascript only has value semantics for primitive types, Koffi can marshal out (or in/out) two types of parameters:
+
+- [Structs](types.md#struct-types) (to/from JS objects)
+- [Opaque handles](types.md#opaque-handles)
+
+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 handle example
+
+This example opens an in-memory SQLite database, and uses the node-ffi-style function declaration syntax.
+
+```js
+const koffi = require('koffi');
+const lib = koffi.load('sqlite.so');
+
+const sqlite3_db = koffi.handle('sqlite3_db');
+
+// Use koffi.out() on a pointer to copy out (from C to JS) after the call
+const sqlite3_open_v2 = lib.func('sqlite3_open_v2', 'int', ['string', koffi.out(koffi.pointer(sqlite3_db)), 'int', 'string']);
+
+const SQLITE_OPEN_READWRITE = 0x2;
+const SQLITE_OPEN_CREATE = 0x4;
+
+let db = {};
+if (sqlite3_open_v2(':memory:', db, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, null) != 0)
+    throw new Error('Failed to open database');
+sqlite3_close_v2(db);
+```
+
+## Javascript callbacks
+
+### Using callbacks
+
+In order to pass a JS function to a C function expecting a callback, you must first create a callback type with the expected return type and parameters. The syntax is similar to the one used to load functions from a shared library.
+
+```js
+const koffi = require('koffi');
+
+// With the classic syntax, this callback expects an integer and returns nothing
+const ExampleCallback = koffi.callback('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)');
+```
+
+Once your callback type is declared, you can use them in struct definitions, or as function parameter and/or return type.
+
+Here is a small example with the C part and the JS part.
+
+```c
+#include <string.h>
+
+int TransferToJS(const char *name, int age, int (*cb)(const char *str, int age))
+{
+    char buf[64];
+    snprintf(buf, sizeof(buf), "Hello %s!", str);
+    return cb(buf, age);
+}
+```
+
+```js
+const koffi = require('koffi');
+
+const TransferCallback = koffi.callback('int TransferCallback(const char *str, int age)');
+
+const TransferToJS = lib.func('int TransferToJS(const char *str, int age, TransferCallback cb)');
+
+let ret = TransferToJS('Niels', 27, (str, age) => {
+    console.log(str);
+    console.log('Your age is:', age);
+    return 42;
+});
+console.log(ret);
+
+// This example prints:
+//   Hello Niels!
+//   Your age is: 27
+//   42
+```
+
+On x86 platforms, only Cdecl and Stdcall callbacks are supported.
+
+### Thread safety
+
+The callback must be called from the main thread, or more precisely from the same thread as the V8 intepreter.
+
+Calling the callback from another thread is undefined behavior, and will likely lead to a mess.

package/doc/dist/html/_sources/index.rst.txt

@@ -0,0 +1,33 @@
+Koffi
+=====
+
+Overview
+--------
+
+Koffi is a **fast and easy-to-use C FFI module for Node.js**, featuring:
+
+* Low-overhead and fast performance (see :ref:`Benchmarks`)
+* Support for primitive and aggregate data types (structs and fixed-size arrays), both by reference (pointer) and by value
+* Javascript functions can be used as C callbacks (since 1.2.0)
+* Well-tested code base for :ref:`popular OS/architecture combinations<Supported platforms>`
+
+Table of contents
+-----------------
+
+.. toctree::
+   :maxdepth: 2
+
+   platforms
+   start
+   types
+   functions
+   memory
+   benchmarks
+   contribute
+
+License
+-------
+
+This program is free software: you can redistribute it and/or modify it under the terms of the **GNU Affero General Public License** as published by the Free Software Foundation, either **version 3 of the License**, or (at your option) any later version.
+
+Find more information here: https://www.gnu.org/licenses/

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

@@ -0,0 +1,29 @@
+# Memory usage
+
+## How it works
+
+For synchronous/normal calls, Koffi uses two preallocated memory blocks:
+
+- One to construct to assign the C stack, 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, no extra allocation ever happens during calls or callbacks.
+
+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.
+
+## 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     | 512 kiB | Stack size for asynchronous calls
+async_heap_size      | 1 MiB   | Heap size for asynchronous calls
+resident_async_pools | 2       | Number of resident pools for asynchronous calls

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

@@ -0,0 +1,17 @@
+# Supported platforms
+
+The following combinations of OS and architectures __are officially supported and tested__ at the moment:
+
+ISA / OS           | Windows     | Linux    | macOS       | FreeBSD     | OpenBSD
+------------------ | ----------- | -------- | ----------- | ----------- | --------
+x86 (IA32) [^1]    | ✅ Yes      | ✅ Yes   | ⬜️ *N/A*    | ✅ Yes      | ✅ Yes
+x86_64 (AMD64)     | ✅ Yes      | ✅ Yes   | ✅ Yes      | ✅ Yes      | ✅ Yes
+ARM32 LE [^2]      | ⬜️ *N/A*    | ✅ Yes   | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
+ARM64 (AArch64) LE | ✅ Yes      | ✅ Yes   | ✅ Yes      | ✅ Yes      | 🟨 Probably
+RISC-V 64 [^3]     | ⬜️ *N/A*    | ✅ Yes   | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
+
+For all fully supported platforms (green check marks), a prebuilt binary is included in the NPM package which means you can install Koffi without a C++ compiler.
+
+[^1]: The following call conventions are supported for forward calls: cdecl, stdcall, MS fastcall, thiscall. Only cdecl and stdcall can be used for C to JS callbacks.
+[^2]: The prebuilt binary uses the hard float ABI and expects a VFP coprocessor. Build from source to use Koffi with a different ABI (softfp, soft).
+[^3]: The prebuilt binary uses the LP64D (double-precision float) ABI. The LP64 ABI is supported in theory if you build Koffi from source (untested), the LP64F ABI is not supported.

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

@@ -0,0 +1,89 @@
+# Quick start
+
+You can install Koffi with npm:
+
+```sh
+npm install koffi
+```
+
+Once you have installed Koffi, you can start by loading it this way:
+
+```js
+const koffi = require('koffi');
+```
+
+Below you can find three examples:
+
+* The first one runs on Linux. The functions are declared with the C-like prototype language.
+* The second one runs on Windows, and uses the node-ffi like syntax to declare functions.
+
+## Small Linux example
+
+This is a small example for Linux systems, which uses `gettimeofday()` and `printf()` to print the current time and the timezone.
+
+It illustrates the use of output parameters.
+
+```js
+const koffi = require('koffi');
+
+// Load the shared library
+const lib = koffi.load('libc.so.6');
+
+// Declare struct types
+const timeval = koffi.struct('timeval', {
+    tv_sec: 'unsigned int',
+    tv_usec: 'unsigned int'
+});
+const timezone = koffi.struct('timezone', {
+    tz_minuteswest: 'int',
+    tz_dsttime: 'int'
+});
+const time_t = koffi.struct('time_t', { value: 'int64_t' });
+const tm = koffi.struct('tm', {
+    tm_sec: 'int',
+    tm_min: 'int',
+    tm_hour: 'int',
+    tm_mday: 'int',
+    tm_mon: 'int',
+    tm_year: 'int',
+    tm_wday: 'int',
+    tm_yday: 'int',
+    tm_isdst: 'int'
+});
+
+// Find functions
+const gettimeofday = lib.func('int gettimeofday(_Out_ timeval *tv, _Out_ timezone *tz)');
+const localtime_r = lib.func('tm *localtime_r(const time_t *timeval, _Out_ tm *result)');
+const printf = lib.func('int printf(const char *format, ...)');
+
+// Get local time
+let tv = {};
+let now = {};
+gettimeofday(tv, null);
+localtime_r({ value: tv.tv_sec }, now);
+
+// And format it with printf (variadic function)
+printf('Hello World!\n');
+printf('Local time: %02d:%02d:%02d\n', 'int', now.tm_hour, 'int', now.tm_min, 'int', now.tm_sec);
+```
+
+## Small Windows example
+
+This is a small example targeting the Win32 API, using `MessageBox()` to show a Hello message to the user.
+
+It illustrates the use of the x86 stdcall calling convention.
+
+```js
+const koffi = require('koffi');
+
+// Load the shared library
+const lib = koffi.load('user32.dll');
+
+// Declare constants
+const MB_ICONINFORMATION = 0x40;
+
+// Find functions
+const MessageBoxA = lib.stdcall('MessageBoxA', 'int', ['void *', 'string', 'string', 'uint']);
+
+MessageBoxA(null, 'Hello', 'Foobar', MB_ICONINFORMATION);
+```