koffi 2.2.3 → 2.2.5

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/static/custom.css

@@ -1,14 +1,14 @@
 /* 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
+   it under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
 
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-   GNU Affero General Public License for more details.
+   GNU Lesser General Public License for more details.
 
-   You should have received a copy of the GNU Affero General Public License
+   You should have received a copy of the GNU Lesser General Public License
    along with this program. If not, see https://www.gnu.org/licenses/. */
 
 aside.footnote {

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.5",
+    "stable": "2.2.5",
     "description": "Fast and simple C FFI (foreign function interface) for Node.js",
     "keywords": [
         "foreign",
@@ -23,9 +23,9 @@
         "install": "cnoke --prebuild -d src/koffi",
         "test": "node src/koffi/qemu/qemu.js test"
     },
-    "license": "AGPL-3.0",
+    "license": "LGPL-3.0",
     "dependencies": {
-        "cnoke": "^3.2.1"
+        "cnoke": "^3.2.2"
     },
     "devDependencies": {
         "chalk": "^4.1.2",