koffi 2.4.2 → 2.5.0-beta.2

package/doc/callbacks.md

@@ -20,7 +20,7 @@ const ExampleCallback = koffi.proto('ExampleCallback', 'void', ['int']);
 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.
+Once your callback type is declared, you can use a pointer to it in struct definitions, as function parameters and/or return types, or to call/decode function pointers.
 
 ```{note}
 Callbacks **have changed in version 2.0**.

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

@@ -137,7 +137,7 @@ You can easily convert this callback-style async function to a promise-based ver
 
 Variadic functions cannot be called asynchronously.
 
-```{note}
+```{warning}
 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

@@ -26,6 +26,7 @@ Table of contents
    functions
    types
    pointers
+   unions
    parameters
    callbacks
    misc

package/doc/parameters.md

@@ -9,6 +9,7 @@ By default, Koffi will only forward arguments from Javascript to C. However, man
 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)
+- [Unions](unions.md)
 - [Opaque types](types.md#opaque-types)
 - String buffers
 
@@ -212,7 +213,6 @@ if (filename == null)
 
 let hdr = {};
 {
-
     let fp = fopen(filename, 'rb');
     if (!fp)
         throw new Error(`Failed to open '${filename}'`);

package/doc/pointers.md

@@ -132,7 +132,7 @@ By default, just like for objects, array arguments are copied from JS to C but n
 
 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](parameters.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 special parameters.
 
 ## Unwrap pointers
 

package/doc/unions.md

@@ -0,0 +1,187 @@
+# Union values
+
+*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:
+
+```c
+typedef union IntOrDouble {
+    int64_t i;
+    double d;
+} IntOrDouble;
+```
+
+```js
+const IntOrDouble = koffi.union('IntOrDouble', {
+    i: 'int64_t',
+    d: 'double'
+});
+```
+
+## Input unions
+
+### 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.
+
+Once you have created an instance of your union, you can simply set the member with the dot operator as you would with a basic object. Then, simply pass your union value to the C function you wish.
+
+```js
+const U = koffi.union('U', { i: 'int', str: 'char *' });
+
+const DoSomething = lib.func('void DoSomething(const char *type, U u)');
+
+const u1 = new koffi.Union('U'); u1.i = 42;
+const u2 = new koffi.Union('U'); u2.str = 'Hello!';
+
+DoSomething('int', u1);
+DoSomething('string', u2);
+```
+
+For simplicity, Koffi also accepts object literals with one property (no more, no less) setting the corresponding union member. The example belows uses this to simplify the code shown above:
+
+```js
+const U = koffi.union('U', { i: 'int', str: 'char *' });
+
+const DoSomething = lib.func('void DoSomething(const char *type, U u)');
+
+DoSomething('int', { .i = 42 });
+DoSomething('string', { .str = 'Hello!' });
+```
+
+### 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).
+
+```js
+const koffi = require('koffi');
+
+// Win32 type and functions
+
+const user32 = koffi.load('user32.dll');
+
+const INPUT_MOUSE = 0;
+const INPUT_KEYBOARD = 1;
+const INPUT_HARDWARE = 2;
+
+const KEYEVENTF_KEYUP = 0x2;
+const KEYEVENTF_SCANCODE = 0x8;
+
+const VK_LWIN = 0x5B;
+const VK_D = 0x44;
+
+const MOUSEINPUT = koffi.struct('MOUSEINPUT', {
+    dx: 'long',
+    dy: 'long',
+    mouseData: 'uint32_t',
+    dwFlags: 'uint32_t',
+    time: 'uint32_t',
+    dwExtraInfo: 'uintptr_t'
+});
+const KEYBDINPUT = koffi.struct('KEYBDINPUT', {
+    wVk: 'uint16_t',
+    wScan: 'uint16_t',
+    dwFlags: 'uint32_t',
+    time: 'uint32_t',
+    dwExtraInfo: 'uintptr_t'
+});
+const HARDWAREINPUT = koffi.struct('HARDWAREINPUT', {
+    uMsg: 'uint32_t',
+    wParamL: 'uint16_t',
+    wParamH: 'uint16_t'
+});
+
+const INPUT = koffi.struct('INPUT', {
+    type: 'uint32_t',
+    u: koffi.union({
+        mi: MOUSEINPUT,
+        ki: KEYBDINPUT,
+        hi: HARDWAREINPUT
+    })
+});
+
+const SendInput = user32.func('unsigned int __stdcall SendInput(unsigned int cInputs, INPUT *pInputs, int cbSize');
+
+// Show/hide desktop with Win+D shortcut
+
+let events = [
+    make_keyboard_event(VK_WIN, true),
+    make_keyboard_event(VK_D, true),
+    make_keyboard_event(VK_D, false),
+    make_keyboard_event(VK_WIN, false)
+];
+
+SendInput(events.length, events, koffi.sizeof(INPUT));
+
+// Utility
+
+function make_keyboard_event(vk, down) {
+    let event = {
+        type: INPUT_KEYBOARD,
+        u: {
+            ki: {
+                wVk: vk,
+                wScan: 0,
+                dwFlags: down ? 0 : KEYEVENTF_KEYUP,
+                time: 0,
+                dwExtraInfo: 0
+            }
+        }
+    };
+
+    return event;
+}
+```
+
+## 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.
+
+To decode an output union pointer parameter, create a placeholder object with `new koffi.Union(type)` and pass the resulting object to the function.
+
+After the call, you can dereference the member value you want on this object and Koffi will decode it at this moment.
+
+The following example illustrates the use of `koffi.Union()` to decode output unions after the call.
+
+```c
+#include <stdint.h>
+
+typedef union IntOrDouble {
+    int64_t i;
+    double d;
+} IntOrDouble;
+
+void SetUnionInt(int64_t i, IntOrDouble *out)
+{
+    out->i = i;
+}
+
+void SetUnionDouble(double d, IntOrDouble *out)
+{
+    out->d = d;
+}
+```
+
+```js
+const IntOrDouble = koffi.union('IntOrDouble', {
+    i: 'int64_t',
+    d: 'double',
+    raw: koffi.array('uint8_t', 8)
+});
+
+const SetUnionInt = lib.func('void SetUnionInt(int64_t i, _Out_ IntOrDouble *out)');
+const SetUnionDouble = lib.func('void SetUnionDouble(double d, _Out_ IntOrDouble *out)');
+
+let u1 = new koffi.Union('IntOrDouble');
+let u2 = new koffi.Union('IntOrDouble');
+
+SetUnionInt(123, u1);
+SetUnionDouble(123, u2);
+
+console.log(u1.i, '---', u1.raw); // Prints 123 --- Uint8Array(8) [123, 0, 0, 0, 0, 0, 0, 0]
+console.log(u2.d, '---', u2.raw); // Prints 123 --- Uint8Array(8) [0, 0, 0, 0, 0, 0, 69, 64]
+```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "koffi",
-    "version": "2.4.2",
+    "version": "2.5.0-beta.2",
     "stable": "2.4.2",
     "description": "Fast and simple C FFI (foreign function interface) for Node.js",
     "keywords": [

package/src/core/libcc/libcc.cc

@@ -2856,15 +2856,6 @@ const char *GetWorkingDirectory()
     return buf;
 }
 
-#ifdef __OpenBSD__
-RG_INIT(ExePathOpenBSD)
-{
-    // This can depend on PATH, which could change during execution
-    // so we want to cache the result as soon as possible.
-    GetApplicationExecutable();
-}
-#endif
-
 const char *GetApplicationExecutable()
 {
 #if defined(_WIN32)
@@ -4068,26 +4059,6 @@ static void DefaultSignalHandler(int signal)
     }
 }
 
-RG_INIT(SetupDefaultHandlers)
-{
-    // Best effort
-    setpgid(0, 0);
-
-    SetSignalHandler(SIGINT, DefaultSignalHandler);
-    SetSignalHandler(SIGTERM, DefaultSignalHandler);
-    SetSignalHandler(SIGHUP, DefaultSignalHandler);
-    SetSignalHandler(SIGPIPE, [](int) {});
-}
-
-RG_EXIT(TerminateChildren)
-{
-    pid_t pid = getpid();
-    RG_ASSERT(pid > 1);
-
-    SetSignalHandler(SIGTERM, [](int) {});
-    kill(-pid, SIGTERM);
-}
-
 bool CreatePipe(int pfd[2])
 {
 #ifdef __APPLE__
@@ -4625,6 +4596,42 @@ bool NotifySystemd()
 }
 #endif
 
+void InitRG()
+{
+#ifdef _WIN32
+    // Use binary standard I/O
+    _setmode(_fileno(stdin), _O_BINARY);
+    _setmode(_fileno(stdout), _O_BINARY);
+    _setmode(_fileno(stderr), _O_BINARY);
+#else
+    // Best effort
+    setpgid(0, 0);
+
+    // Setup default signal handlers
+    SetSignalHandler(SIGINT, DefaultSignalHandler);
+    SetSignalHandler(SIGTERM, DefaultSignalHandler);
+    SetSignalHandler(SIGHUP, DefaultSignalHandler);
+    SetSignalHandler(SIGPIPE, [](int) {});
+
+    // Kill children on exit
+    atexit([]() {
+        if (interrupt_pfd[1] >= 0) {
+            pid_t pid = getpid();
+            RG_ASSERT(pid > 1);
+
+            SetSignalHandler(SIGTERM, [](int) {});
+            kill(-pid, SIGTERM);
+        }
+    });
+#endif
+
+#ifdef __OpenBSD__
+    // This can depend on PATH, which could change during execution
+    // so we want to cache the result as soon as possible.
+    GetApplicationExecutable();
+#endif
+}
+
 // ------------------------------------------------------------------------
 // Standard paths
 // ------------------------------------------------------------------------
@@ -4709,16 +4716,16 @@ const char *GetUserConfigPath(const char *name, Allocator *alloc)
     RG_ASSERT(!strchr(RG_PATH_SEPARATORS, name[0]));
 
     const char *xdg = getenv("XDG_CONFIG_HOME");
+    const char *home = getenv("HOME");
 
     if (xdg) {
         const char *path = Fmt(alloc, "%1%/%2", xdg, name).ptr;
         return path;
-    } else {
-        const char *home = getenv("HOME");
-        RG_CRITICAL(home, "Failed to get HOME environment variable: %1", strerror(errno));
-
+    } else if (home) {
         const char *path = Fmt(alloc, "%1%/.config/%2", home, name).ptr;
         return path;
+    } else {
+        return nullptr;
     }
 }
 
@@ -4727,20 +4734,20 @@ const char *GetUserCachePath(const char *name, Allocator *alloc)
     RG_ASSERT(!strchr(RG_PATH_SEPARATORS, name[0]));
 
     const char *xdg = getenv("XDG_CACHE_HOME");
+    const char *home = getenv("HOME");
 
     if (xdg) {
         const char *path = Fmt(alloc, "%1%/%2", xdg, name).ptr;
         return path;
-    } else {
-        const char *home = getenv("HOME");
-        RG_CRITICAL(home, "Failed to get HOME environment variable: %1", strerror(errno));
-
+    } else if (home) {
         const char *path = Fmt(alloc, "%1%/.cache/%2", home, name).ptr;
         return path;
+    } else {
+        return nullptr;
     }
 }
 
-static const char *GetSystemConfigPath(const char *name, Allocator *alloc)
+const char *GetSystemConfigPath(const char *name, Allocator *alloc)
 {
     RG_ASSERT(!strchr(RG_PATH_SEPARATORS, name[0]));
 
@@ -4792,6 +4799,9 @@ const char *FindConfigFile(const char *name, Allocator *alloc, LocalArray<const
     for (const auto &func: funcs) {
         const char *path = func(name, alloc);
 
+        if (!path)
+            continue;
+
         if (TestFile(path, FileType::File)) {
             filename = path;
         }
@@ -5129,8 +5139,9 @@ int OpenIPSocket(SocketType type, int port, SocketMode mode)
 
     int flags = 0;
     switch (mode) {
-        case SocketMode::Stream: { flags = SOCK_STREAM; } break;
-        case SocketMode::Messages: { flags = SOCK_DGRAM; } break;
+        case SocketMode::ConnectStream: { flags = SOCK_STREAM; } break;
+        case SocketMode::ConnectDatagrams: { RG_UNREACHABLE(); } break;
+        case SocketMode::FreeDatagrams: { flags = SOCK_DGRAM; } break;
     }
 
 #ifdef _WIN32
@@ -5199,8 +5210,9 @@ int OpenUnixSocket(const char *path, SocketMode mode)
 {
     int flags = 0;
     switch (mode) {
-        case SocketMode::Stream: { flags = SOCK_STREAM; } break;
-        case SocketMode::Messages: { flags = SOCK_SEQPACKET; } break;
+        case SocketMode::ConnectStream: { flags = SOCK_STREAM; } break;
+        case SocketMode::ConnectDatagrams: { flags = SOCK_SEQPACKET; } break;
+        case SocketMode::FreeDatagrams: { flags = SOCK_DGRAM; } break;
     }
 
 #if defined(_WIN32)
@@ -5252,8 +5264,9 @@ int ConnectToUnixSocket(const char *path, SocketMode mode)
 {
     int flags = 0;
     switch (mode) {
-        case SocketMode::Stream: { flags = SOCK_STREAM; } break;
-        case SocketMode::Messages: { flags = SOCK_SEQPACKET; } break;
+        case SocketMode::ConnectStream: { flags = SOCK_STREAM; } break;
+        case SocketMode::ConnectDatagrams: { flags = SOCK_SEQPACKET; } break;
+        case SocketMode::FreeDatagrams: { flags = SOCK_DGRAM; } break;
     }
 
 #if defined(_WIN32)
@@ -5867,15 +5880,6 @@ void Fiber::Toggle(int to, std::unique_lock<std::mutex> *lock)
 // Streams
 // ------------------------------------------------------------------------
 
-#ifdef _WIN32
-RG_INIT(BinaryStdIO)
-{
-    _setmode(_fileno(stdin), _O_BINARY);
-    _setmode(_fileno(stdout), _O_BINARY);
-    _setmode(_fileno(stderr), _O_BINARY);
-}
-#endif
-
 StreamReader stdin_st(stdin, "<stdin>");
 StreamWriter stdout_st(stdout, "<stdout>");
 StreamWriter stderr_st(stderr, "<stderr>");
@@ -6416,7 +6420,7 @@ bool StreamWriter::Open(const char *filename, unsigned int flags,
             dest.u.file.tmp_exclusive = true;
         }
 
-        dest.u.file.tmp_filename = CreateUniqueFile(directory, "", ".tmp", &str_alloc, &dest.u.file.fp);
+        dest.u.file.tmp_filename = CreateUniqueFile(directory, ".", ".tmp", &str_alloc, &dest.u.file.fp);
         if (!dest.u.file.tmp_filename)
             return false;
         dest.u.file.owned = true;

package/src/core/libcc/libcc.hh

@@ -2599,11 +2599,11 @@ public:
 
     ValueType *Set(const KeyType &key, const ValueType &value)
         { return &table.Set({ key, value })->value; }
-    ValueType *SetDefault(const KeyType &key)
+    Bucket *SetDefault(const KeyType &key)
     {
         Bucket *table_it = table.SetDefault(key);
         table_it->key = key;
-        return &table_it->value;
+        return table_it;
     }
 
     ValueType *TrySet(const KeyType &key, const ValueType &value, bool *out_inserted = nullptr)
@@ -2611,7 +2611,7 @@ public:
         Bucket *ptr = table.TrySet({ key, value }, out_inserted);
         return &ptr->value;
     }
-    ValueType *TrySetDefault(const KeyType &key, bool *out_inserted = nullptr)
+    Bucket *TrySetDefault(const KeyType &key, bool *out_inserted = nullptr)
     {
         bool inserted;
         Bucket *ptr = table.TrySetDefault(key, &inserted);
@@ -2623,7 +2623,7 @@ public:
         if (out_inserted) {
             *out_inserted = inserted;
         }
-        return &ptr->value;
+        return ptr;
     }
 
     void Remove(ValueType *it)
@@ -2632,6 +2632,12 @@ public:
             return;
         table.Remove((Bucket *)((uint8_t *)it - RG_OFFSET_OF(Bucket, value)));
     }
+    void Remove(Bucket *it)
+    {
+        if (!it)
+            return;
+        table.Remove(it);
+    }
     template <typename T = KeyType>
     void Remove(const KeyType &key) { Remove(Find(key)); }
 
@@ -3983,9 +3989,9 @@ bool ExecuteCommandLine(const char *cmd_line, FunctionRef<Span<const uint8_t>()>
                         FunctionRef<void(Span<uint8_t> buf)> out_func, int *out_code);
 bool ExecuteCommandLine(const char *cmd_line, Span<const uint8_t> in_buf, Size max_len,
                         HeapArray<uint8_t> *out_buf, int *out_code);
-static inline bool ExecuteCommandLine(const char *cmd_line, int *out_code) {
-    return ExecuteCommandLine(cmd_line, {}, {}, out_code);
-}
+
+static inline bool ExecuteCommandLine(const char *cmd_line, int *out_code)
+    { return ExecuteCommandLine(cmd_line, {}, {}, out_code); }
 static inline bool ExecuteCommandLine(const char *cmd_line, Span<const uint8_t> in_buf,
                                       FunctionRef<void(Span<uint8_t> buf)> out_func, int *out_code)
 {
@@ -4001,15 +4007,12 @@ static inline bool ExecuteCommandLine(const char *cmd_line, Span<const char> in_
                                       FunctionRef<void(Span<char> buf)> out_func, int *out_code)
 {
     const auto write = [&](Span<uint8_t> buf) { out_func(buf.As<char>()); };
-
     return ExecuteCommandLine(cmd_line, in_buf.As<const uint8_t>(), write, out_code);
 }
 static inline bool ExecuteCommandLine(const char *cmd_line, Span<const char> in_buf, Size max_len,
                                       HeapArray<char> *out_buf, int *out_code)
-{
-    return ExecuteCommandLine(cmd_line, in_buf.As<const uint8_t>(), max_len,
-                              (HeapArray<uint8_t> *)out_buf, out_code);
-}
+    { return ExecuteCommandLine(cmd_line, in_buf.As<const uint8_t>(), max_len,
+                                (HeapArray<uint8_t> *)out_buf, out_code); }
 
 void WaitDelay(int64_t delay);
 
@@ -4043,12 +4046,22 @@ bool NotifySystemd();
         })()
 #endif
 
+static inline int RunApp(int argc, char **argv)
+{
+    void InitRG();
+    int Main(int argc, char **argv);
+
+    InitRG();
+    return Main(argc, argv);
+}
+
 // ------------------------------------------------------------------------
 // Standard paths
 // ------------------------------------------------------------------------
 
-const char *GetUserConfigPath(const char *name, Allocator *alloc);
-const char *GetUserCachePath(const char *name, Allocator *alloc);
+const char *GetUserConfigPath(const char *name, Allocator *alloc); // Can return NULL
+const char *GetUserCachePath(const char *name, Allocator *alloc); // Can return NULL
+const char *GetSystemConfigPath(const char *name, Allocator *alloc);
 const char *GetTemporaryDirectory();
 
 const char *FindConfigFile(const char *name, Allocator *alloc, LocalArray<const char *, 4> *out_possibilities = nullptr);
@@ -4116,14 +4129,15 @@ static const char *const SocketTypeNames[] = {
 };
 
 enum class SocketMode {
-    Stream,
-    Messages
+    ConnectStream,
+    ConnectDatagrams,
+    FreeDatagrams
 };
 
-int OpenIPSocket(SocketType type, int port, SocketMode mode = SocketMode::Stream);
+int OpenIPSocket(SocketType type, int port, SocketMode mode = SocketMode::ConnectStream);
 
-int OpenUnixSocket(const char *path, SocketMode mode = SocketMode::Stream);
-int ConnectToUnixSocket(const char *path, SocketMode mode = SocketMode::Stream);
+int OpenUnixSocket(const char *path, SocketMode mode = SocketMode::ConnectStream);
+int ConnectToUnixSocket(const char *path, SocketMode mode = SocketMode::ConnectStream);
 
 void CloseSocket(int fd);
 

package/src/koffi/src/abi_x86.cc

@@ -75,11 +75,23 @@ bool AnalyseFunction(Napi::Env env, InstanceData *instance, FunctionInfo *func)
 #if defined(_WIN32) || defined(__FreeBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
     } else {
         func->ret.trivial = IsRegularSize(func->ret.type->size, 8);
+
+    #if defined(__FreeBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
+        if (func->ret.type->members.len == 1) {
+            const RecordMember &member = func->ret.type->members[0];
+
+            if (member.type->primitive == PrimitiveKind::Float32) {
+                func->ret.fast = 1;
+            } else if (member.type->primitive == PrimitiveKind::Float64) {
+                func->ret.fast = 2;
+            }
+        }
+    #endif
 #endif
     }
 #ifndef _WIN32
     if (fast && !func->ret.trivial) {
-        func->ret.fast = true;
+        func->ret.fast = 1;
         fast--;
     }
 #endif
@@ -87,7 +99,7 @@ bool AnalyseFunction(Napi::Env env, InstanceData *instance, FunctionInfo *func)
     Size params_size = 0;
     for (ParameterInfo &param: func->parameters) {
         if (fast && param.type->size <= 4) {
-            param.fast = true;
+            param.fast = 1;
             fast--;
         }
 
@@ -362,9 +374,24 @@ void CallData::Execute(const FunctionInfo *func, void *native)
         case PrimitiveKind::String:
         case PrimitiveKind::String16:
         case PrimitiveKind::Pointer:
-        case PrimitiveKind::Record:
-        case PrimitiveKind::Union:
         case PrimitiveKind::Callback: { result.u64 = PERFORM_CALL(G); } break;
+#if defined(__FreeBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
+        case PrimitiveKind::Record:
+        case PrimitiveKind::Union: {
+            if (!func->ret.fast) {
+                result.u64 = PERFORM_CALL(G);
+            } else if (func->ret.fast == 1) {
+                result.f = PERFORM_CALL(F);
+            } else if (func->ret.fast == 2) {
+                result.d = PERFORM_CALL(D);
+            } else {
+                RG_UNREACHABLE();
+            }
+        } break;
+#else
+        case PrimitiveKind::Record:
+        case PrimitiveKind::Union: { result.u64 = PERFORM_CALL(G); } break;
+#endif
         case PrimitiveKind::Array: { RG_UNREACHABLE(); } break;
         case PrimitiveKind::Float32: { result.f = PERFORM_CALL(F); } break;
         case PrimitiveKind::Float64: { result.d = PERFORM_CALL(D); } break;