koffi 2.9.1 → 2.9.2

package/doc/{platforms.md → pages/platforms.md}

@@ -1,6 +1,4 @@
-# Requirements
-
-## Node.js
+# Node.js
 
 Koffi requires a recent [Node.js](https://nodejs.org/) version with [N-API](https://nodejs.org/api/n-api.html) version 8 support:
 
@@ -12,7 +10,7 @@ Koffi requires a recent [Node.js](https://nodejs.org/) version with [N-API](http
 
 Use [NVM](https://github.com/nvm-sh/nvm) to install more recent Node versions on older Linux distributions.
 
-## Supported platforms
+# Supported platforms
 
 The following combinations of OS and architectures __are officially supported and tested__ at the moment:
 

package/doc/{pointers.md → pages/pointers.md}

@@ -1,6 +1,4 @@
-# Data pointers
-
-## How pointers are used
+# 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:
 
@@ -9,9 +7,9 @@ In C, pointer arguments are used for differenty purposes. It is important to dis
 - **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
+# Pointer types
 
-### Struct pointers
+## Struct pointers
 
 The following Win32 example uses `GetCursorPos()` (with an output parameter) to retrieve and show the current cursor position.
 
@@ -37,7 +35,7 @@ if (!GetCursorPos(pos))
 console.log(pos);
 ```
 
-### Opaque pointers
+## Opaque pointers
 
 *New in Koffi 2.0*
 
@@ -51,7 +49,7 @@ const GetHandleInformation = lib.func('bool __stdcall GetHandleInformation(HANDL
 const CloseHandle = lib.func('bool __stdcall CloseHandle(HANDLE h)');
 ```
 
-### Pointer to primitive types
+## 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.
 
@@ -88,7 +86,7 @@ AddInt(sum, 6);
 console.log(sum[0]); // Prints 42
 ```
 
-### Dynamic arrays
+## 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).
 
@@ -130,9 +128,9 @@ 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](output.md).
+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](output).
 
-## Handling void pointers
+# Handling void pointers
 
 *New in Koffi 2.1*
 
@@ -195,7 +193,7 @@ let hdr = {};
 console.log('PNG header:', hdr);
 ```
 
-## Disposable types
+# Disposable types
 
 *New in Koffi 2.0*
 
@@ -230,7 +228,7 @@ let copy = strdup('Hello!');
 console.log(copy); // Prints Hello!
 ```
 
-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)`.
+When you declare functions with the [prototype-like syntax](functions#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
 // ES6 syntax: import koffi from 'koffi';
@@ -247,10 +245,9 @@ 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()`.
-```
+> [!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()`.
 
-## Unwrap pointers
+# Unwrap pointers
 
 You can use `koffi.address(ptr)` on a pointer to get the numeric value as a [BigInt object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt).

package/doc/{start.md → pages/start.md}

@@ -1,6 +1,4 @@
-# Get started
-
-## Install Koffi
+# Install Koffi
 
 You can install Koffi with npm:
 
@@ -18,14 +16,14 @@ const koffi = require('koffi');
 import koffi from 'koffi';
 ```
 
-## Simple examples
+# Simple examples
 
 Below you can find two 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.
 
-### For Linux
+## For Linux
 
 This is a small example for Linux systems, which uses `gettimeofday()`, `localtime_r()` and `printf()` to print the current time.
 
@@ -52,7 +50,7 @@ const tm = koffi.struct('tm', {
     tm_sec: 'int',
     tm_min: 'int',
     tm_hour: 'int',
-    tm_mday: 'int',
+    tmay: 'int',
     tm_mon: 'int',
     tm_year: 'int',
     tm_wday: 'int',
@@ -76,7 +74,7 @@ printf('Hello World!\n');
 printf('Local time: %02d:%02d:%02d\n', 'int', now.tm_hour, 'int', now.tm_min, 'int', now.tm_sec);
 ```
 
-### For Windows
+## For Windows
 
 This is a small example targeting the Win32 API, using `MessageBox()` to show a *Hello World!* message to the user.
 
@@ -103,18 +101,18 @@ const MessageBoxA = lib.func('__stdcall', 'MessageBoxA', 'int', ['void *', 'str'
 const MessageBoxW = lib.func('__stdcall', 'MessageBoxW', 'int', ['void *', 'str16', 'str16', 'uint']);
 
 let ret = MessageBoxA(null, 'Do you want another message box?', 'Koffi', MB_YESNO | MB_ICONQUESTION);
+
 if (ret == IDYES)
     MessageBoxW(null, 'Hello World!', 'Koffi', MB_ICONINFORMATION);
 ```
 
-## Bundling Koffi
+# Bundling Koffi
 
-Please read the [dedicated page](packaging.md) for information about bundling and packaging applications using Koffi.
+Please read the [dedicated page](packaging) for information about bundling and packaging applications using Koffi.
 
-## Build manually
+# Build manually
 
-Follow the [build instrutions](contribute.md#build-from-source) if you want to build the native Koffi code yourself.
+Follow the [build instrutions](contribute#build-from-source) if you want to build the native Koffi code yourself.
 
-```{note}
-This is only needed if you want to hack on Koffi. The official NPM package provide prebuilt binaries and you don't need to compile anything if you only want to use Koffi in Node.js.
-```
+> [!NOTE]
+> This is only needed if you want to hack on Koffi. The official NPM package provide prebuilt binaries and you don't need to compile anything if you only want to use Koffi in Node.js.

package/doc/{unions.md → pages/unions.md}

@@ -1,9 +1,7 @@
-# Union values
+# Union definition
 
 *New in Koffi 2.5*
 
-## Union definition
-
 You can declare unions with a syntax similar to structs, but with the `koffi.union()` function. This function takes two arguments: the first one is the name of the type, and the second one is an object containing the union member names and types. You can omit the first argument to declare an anonymous union.
 
 The following example illustrates how to declare the same union in C and in JS with Koffi:
@@ -22,9 +20,9 @@ const IntOrDouble = koffi.union('IntOrDouble', {
 });
 ```
 
-## Input unions
+# Input unions
 
-### Passing union values to C
+## Passing union values to C
 
 You can instantiate an union object with `koffi.Union(type)`. This will create a special object that contains at most one active member.
 
@@ -53,7 +51,7 @@ DoSomething('int', { i: 42 });
 DoSomething('string', { str: 'Hello!' });
 ```
 
-### Win32 example
+## Win32 example
 
 The following example uses the [SendInput](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-sendinput) Win32 API to emit the Win+D shortcut and hide windows (show the desktop).
 
@@ -138,7 +136,7 @@ function make_keyboard_event(vk, down) {
 }
 ```
 
-## Output unions
+# Output unions
 
 Unlike structs, Koffi does not know which union member is valid, and it cannot decode it automatically. You can however use special `koffi.Union` objects for output parameters, and decode the memory after the call.
 

package/doc/{variables.md → pages/variables.md}

@@ -1,6 +1,4 @@
-# Exported variables
-
-## Variable definitions
+# Variable definitions
 
 *New in Koffi 2.6*
 
@@ -21,7 +19,7 @@ You cannot directly manipulate these variables, use:
 - [koffi.decode()](#decode-to-js-values) to read their value
 - [koffi.encode()](#encode-to-c-memory) to change their valuèe
 
-## Decode to JS values
+# Decode to JS values
 
 *New in Koffi 2.2, changed in Koffi 2.3*
 
@@ -61,11 +59,10 @@ The example below will decode the symbol `my_string` defined above but only the
 console.log(koffi.decode(my_string, 'const char *', 3)) // Prints "foo"
 ```
 
-```{note}
-In Koffi 2.2 and earlier versions, the length argument is only used to decode strings and is ignored otherwise.
-```
+> [!NOTE]
+> In Koffi 2.2 and earlier versions, the length argument is only used to decode strings and is ignored otherwise.
 
-## Encode to C memory
+# Encode to C memory
 
 *New in Koffi 2.6*
 
@@ -101,6 +98,5 @@ When encoding strings (either directly or embedded in arrays or structs), the me
 
 There is also an optional ending `length` argument that you can use to encode an array. For example, here is how you can encode an array with 3 float values: `koffi.encode(symbol, 'float', [1, 2, 3], 3)`. This is equivalent to `koffi.encode(symbol, koffi.array('float', 3), [1, 2, 3])`.
 
-```{note}
-The length argument did not work correctly before Koffi 2.6.11.
-```
+> [!NOTE]
+> The length argument did not work correctly before Koffi 2.6.11.

package/doc/pages.ini

@@ -0,0 +1,88 @@
+[pages/index.md]
+Title = Koffi
+Menu = Overview
+Description = Koffi presentation and features
+Template = templates/page.html
+
+[pages/platforms.md]
+Title = Requirements | Koffi
+Menu = Documentation / Requirements
+Description = Supported systemd and architectures
+Template = templates/page.html
+
+[pages/start.md]
+Title = Get started | Koffi
+Menu = Documentation / Get started
+Description = Install and start using Koffi in your Node.js project
+Template = templates/page.html
+
+[pages/functions.md]
+Title = Function calls | Koffi
+Menu = Documentation / Function calls
+Description = Call native functions
+Template = templates/page.html
+
+[pages/input.md]
+Title = Input parameters | Koffi
+Menu = Documentation / Input parameters
+Template = templates/page.html
+
+[pages/pointers.md]
+Title = Data pointers | Koffi
+Menu = Documentation / Data pointers
+Template = templates/page.html
+
+[pages/output.md]
+Title = Output parameters | Koffi
+Menu = Documentation / Output parameters
+Template = templates/page.html
+
+[pages/unions.md]
+Title = Union values | Koffi
+Menu = Documentation / Union values
+Template = templates/page.html
+
+[pages/variables.md]
+Title = Exported variables | Koffi
+Menu = Documentation / Exported variables
+Template = templates/page.html
+
+[pages/callbacks.md]
+Title = Callbacks | Koffi
+Menu = Documentation / Javascript callbacks
+Template = templates/page.html
+
+[pages/misc.md]
+Title = Miscellaneous | Koffi
+Menu = Documentation / Miscellaneous
+Template = templates/page.html
+
+[pages/packaging.md]
+Title = Packaging | Koffi
+Menu = Documentation / Bundlers and Koffi
+Template = templates/page.html
+
+[pages/benchmarks.md]
+Title = Benchmarks | Koffi
+Menu = Benchmarks
+Description = Performance of Koffi compared to NAPI and node-ffi
+Template = templates/page.html
+
+[pages/contribute.md]
+Title = Contribute | Koffi
+Menu = Contribute
+Description = How to get, build and test Koffi code
+Template = templates/page.html
+
+[changelog]
+SourceFile = ../../src/koffi/CHANGELOG.md
+Title = Changelog | Koffi
+Menu = Changelog / Version history
+Description = List of Koffi versions
+Template = templates/page.html
+
+[pages/migration.md]
+Title = Migration | Koffi
+Menu = Changelog / Migration guide
+Description = Migration between major Koffi versions
+Template = templates/page.html

package/doc/static/koffi.css

@@ -0,0 +1,21 @@
+/* Copyright (C) 2024  Niels Martignène <niels.martignene@protonmail.com>
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU 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 General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see <https://www.gnu.org/licenses/>. */
+
+@import url('../flaat/flaat.css');
+@import url('../../../vendor/highlight.js/styles/base16/tomorrow.css');
+
+html {
+    --primary_color: #ec7400;
+}

package/doc/static/koffi.js

@@ -0,0 +1,21 @@
+// Copyright (C) 2024  Niels Martignène <niels.martignene@protonmail.com>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU 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 General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+import '../flaat/flaat.js';
+import * as hljs from '../../../vendor/highlight.js/highlight.js';
+
+window.addEventListener('load', e => {
+    hljs.highlightAll();
+});

package/doc/static/print.css

@@ -0,0 +1,22 @@
+/* Copyright (C) 2024  Niels Martignène <niels.martignene@protonmail.com>
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU 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 General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see <https://www.gnu.org/licenses/>. */
+
+@media print {
+    .schema { width: 90%; }
+
+    .columns { display: block; }
+    .columns > * { width: auto; }
+    .columns > * + * { margin-top: 3em; }
+}

package/doc/templates/page.html

@@ -0,0 +1,40 @@
+<!DOCTYPE html>
+<html lang="en" class="nojs">
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+
+        <title>{{ TITLE }}</title>
+        <meta name="author" content="Niels Martignène">
+        <meta name="description" content="{{ DESCRIPTION }}">
+        <link rel="icon" href="{{ ASSET favicon.png }}">
+
+        <meta name="theme-color" content="#6aa051">
+        <link rel="stylesheet" href="{{ ASSET static/site.min.css }}">
+
+        <script type="text/javascript" src="{{ ASSET static/site.min.js }}" async></script>
+    </head>
+
+    <body>
+        <div id="deploy"></div>
+
+        <nav id="top">
+            <menu>
+                <a id="logo" href="/"><img src="{{ ASSET favicon.png }}" alt="Logo Rekkord" /></a>
+
+{{ LINKS }}
+
+                <div style="flex: 1;"></div>
+
+                <li><a href="https://www.npmjs.com/package/koffi" style="border-bottom-color: transparent; margin-top: 8px;"><img src="https://img.shields.io/badge/NPM-2.9.2-brightgreen" alt="NPM"/></a></li>
+                <li><a href="https://github.com/Koromix/koffi" style="border-bottom-color: transparent; margin-top: 8px;"><img src="https://img.shields.io/badge/GitHub-Koffi-ff6600" alt="GitHub"/></a></li>
+            </menu>
+        </nav>
+
+        {{ TOC }}
+
+        <main>
+            {{ CONTENT }}
+        </main>
+    </body>
+</html>

package/index.js

@@ -363,8 +363,8 @@ var require_package = __commonJS({
   "../../bin/Koffi/package/src/koffi/package.json"(exports2, module2) {
     module2.exports = {
       name: "koffi",
-      version: "2.9.1",
-      stable: "2.9.1",
+      version: "2.9.2",
+      stable: "2.9.2",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",

package/indirect.js

@@ -363,8 +363,8 @@ var require_package = __commonJS({
   "../../bin/Koffi/package/src/koffi/package.json"(exports2, module2) {
     module2.exports = {
       name: "koffi",
-      version: "2.9.1",
-      stable: "2.9.1",
+      version: "2.9.2",
+      stable: "2.9.2",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",

package/package.json

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

package/src/koffi/src/call.cc

@@ -321,6 +321,7 @@ Size CallData::PushString16Value(Napi::Value value, const char16_t **out_str16)
     size_t len = 0;
     napi_status status;
 
+    mem->heap.ptr = AlignUp(mem->heap.ptr, 2);
     buf.ptr = (char16_t *)mem->heap.ptr;
     buf.len = std::max((Size)0, mem->heap.len - Kibibytes(32)) / 2;
 
@@ -426,6 +427,7 @@ Size CallData::PushString32Value(Napi::Value value, const char32_t **out_str32)
     if (buf16.len < 0) [[unlikely]]
         return -1;
 
+    mem->heap.ptr = AlignUp(mem->heap.ptr, 4);
     buf.ptr = (char32_t *)mem->heap.ptr;
     buf.len = std::max((Size)0, mem->heap.len - Kibibytes(32)) / 4;
 

package/doc/Makefile

@@ -1,20 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = dist
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

package/doc/changelog.md

@@ -1,5 +0,0 @@
----
-tocdepth: 3
----
-
-{{ "```{include} " ~ root ~ "/CHANGELOG.md" ~ "\n```" }}

package/doc/conf.py

@@ -1,118 +0,0 @@
-import json
-import os
-
-# -- Project information -----------------------------------------------------
-
-project = 'Koffi'
-copyright = '2022, Niels Martignène'
-author = 'Niels Martignène'
-
-root = None
-version = None
-revision = None
-stable = None
-
-names = ['../../src/koffi/package.json', '../package.json']
-
-for name in names:
-    filename = os.path.dirname(__file__) + '/' + name
-
-    if not os.path.exists(filename):
-        continue;
-
-    with open(filename) as f:
-        config = json.load(f)
-
-        root = os.path.dirname(name)
-        version = config['version']
-        revision = config['version']
-        stable = config['stable']
-
-    break
-
-if root is None:
-    raise FileNotFoundError('Cannot find Koffi package.json')
-
-# -- General configuration ---------------------------------------------------
-
-extensions = [
-    'myst_parser',
-    'sphinx.ext.autosectionlabel',
-    'sphinxext.rediraffe'
-]
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['templates']
-
-exclude_patterns = []
-
-# -- Options for HTML output -------------------------------------------------
-
-html_title = project
-
-html_theme = 'furo'
-
-html_static_path = ['static']
-
-html_theme_options = {
-    'light_css_variables': {
-        'font-stack': 'Open Sans',
-        'color-content-foreground': '#383838',
-        'color-brand-primary': '#383838',
-        'color-brand-content': '#e97713'
-    },
-    'dark_css_variables': {
-        'font-stack': 'Open Sans',
-        'color-content-foreground': '#ffffffdd',
-        'color-brand-primary': '#ffffffdd',
-        'color-brand-content': '#e97713'
-    }
-}
-
-html_link_suffix = ''
-
-html_css_files = [
-    'opensans/OpenSans.css',
-    'custom.css'
-]
-
-html_sidebars = {
-    "**": [
-        "logo.html",
-        "sidebar/search.html",
-        "sidebar/scroll-start.html",
-        "sidebar/navigation.html",
-        "sidebar/ethical-ads.html",
-        "badges.html",
-        "sidebar/scroll-end.html",
-        "sidebar/variant-selector.html"
-    ]
-}
-
-html_context = {
-    "root": root,
-    "stable": stable
-}
-
-# -- MyST parser options -------------------------------------------------
-
-myst_enable_extensions = [
-    'linkify',
-    'substitution'
-]
-
-myst_substitutions = html_context
-
-myst_heading_anchors = 3
-
-myst_linkify_fuzzy_links = False
-
-myst_number_code_blocks = ['c', 'js', 'sh', 'batch']
-
-# -- Redirections -------------------------------------------------
-
-rediraffe_redirects = {
-    "changes.md": "changelog.md",
-    "bundling.md": "packaging.md",
-    "parameters.md": "input.md"
-}