koffi 2.4.1 → 2.4.2

package/CHANGELOG.md

@@ -4,12 +4,22 @@
 
 ### Koffi 2.4
 
+#### Koffi 2.4.2
+
+**Main changes:**
+
+- Support calling variadic function pointers
+
+**Other changes:**
+
+- Add documentation for function pointers
+
 #### Koffi 2.4.1
 
 **Main changes:**
 
-- Support decoding pointers to callable functions
-- Support calling function pointers with [koffi.call()]
+- Support [decoding function pointers](functions.md#decode-pointer-to-function) to callable functions
+- Support calling function pointers with [koffi.call()](functions.md#call-pointer-directly)
 - Deprecate `koffi.callback` in favor of `koffi.proto`
 
 **Other changes:**

package/doc/functions.md

@@ -1,4 +1,4 @@
-# Native functions
+# Function calls
 
 ## Loading libraries
 
@@ -89,7 +89,7 @@ const MessageBoxA_1 = lib.stdcall('MessageBoxA', 'int', ['void *', 'str', 'str',
 const MessageBoxA_2 = lib.func('int __stdcall MessageBoxA(void *hwnd, str text, str caption, uint type)');
 ```
 
-## Function calls
+## Call types
 
 ### Synchronous calls
 
@@ -137,8 +137,77 @@ You can easily convert this callback-style async function to a promise-based ver
 
 Variadic functions cannot be called asynchronously.
 
-## Thread safety
-
+```{note}
 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!
+```
+
+## Function pointers
+
+*New in Koffi 2.4*
+
+You can call a function pointer in two ways:
+
+- Directly call the function pointer with `koffi.call(ptr, type, ...)`
+- Decode the function pointer to an actual function with `koffi.decode(ptr, type)`
+
+The example below shows how to call an `int (*)(int, int)` C function pointer both ways, based on the following native C library:
+
+```c
+typedef int BinaryIntFunc(int a, int b);
+
+static int AddInt(int a, int b) { return a + b; }
+static int SubstractInt(int a, int b) { return a - b; }
+
+BinaryIntFunc *GetBinaryIntFunction(const char *type)
+{
+    if (!strcmp(type, "add")) {
+        return AddInt;
+    } else if (!strcmp(type, "substract")) {
+        return SubstractInt;
+    } else {
+        return NULL;
+    }
+}
+```
+
+### Call pointer directly
+
+Use `koffi.call(ptr, type, ...)` to call a function pointer. The first two arguments are the pointer itself and the type of the function you are trying to call (declared with `koffi.proto()` as shown below), and the remaining arguments are used for the call.
+
+```js
+// Declare function type
+const BinaryIntFunc = koffi.proto('int BinaryIntFunc(int a, int b)');
+
+const GetBinaryIntFunction = lib.func('BinaryIntFunc *GetBinaryIntFunction(const char *name)');
+
+const add_ptr = GetBinaryIntFunction('add');
+const substract_ptr = GetBinaryIntFunction('substract');
+
+let sum = koffi.call(add_ptr, BinaryIntFunc, 4, 5);
+let delta = koffi.call(substract_ptr, BinaryIntFunc, 100, 58);
+
+console.log(sum, delta); // Prints 9 and 42
+```
+
+### Decode pointer to function
+
+Use `koffi.decode(ptr, type)` to get back a JS function, which you can then use like any other Koffi function.
+
+This method also allows you to perform an [asynchronous call](#asynchronous-calls) with the async member of the decoded function.
+
+```js
+// Declare function type
+const BinaryIntFunc = koffi.proto('int BinaryIntFunc(int a, int b)');
+
+const GetBinaryIntFunction = lib.func('BinaryIntFunc *GetBinaryIntFunction(const char *name)');
+
+const add = koffi.decode(GetBinaryIntFunction('add'), BinaryIntFunc);
+const substract = koffi.decode(GetBinaryIntFunction('substract'), BinaryIntFunc);
+
+let sum = add(4, 5);
+let delta = substract(100, 58);
+
+console.log(sum, delta); // Prints 9 and 42
+```

package/package.json

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

package/src/koffi/src/ffi.cc

@@ -895,7 +895,7 @@ static bool ParseClassicFunction(Napi::Env env, Napi::String name, Napi::Value r
         if (!param.type)
             return false;
         if (!CanPassType(param.type, param.directions)) {
-            ThrowError<Napi::TypeError>(env, "Type %1 cannot be used as a parameter (maybe try %1 *)", param.type->name);
+            ThrowError<Napi::TypeError>(env, "Type %1 cannot be used as a parameter", param.type->name);
             return false;
         }
         if (func->parameters.len >= MaxParameters) {
@@ -942,11 +942,6 @@ static Napi::Value CreateFunctionType(const Napi::CallbackInfo &info)
         return env.Null();
     }
 
-    if (func->variadic) {
-        LogError("Variadic callbacks are not supported");
-        return env.Null();
-    }
-
     if (!AnalyseFunction(env, instance, func))
         return env.Null();
 
@@ -1310,7 +1305,7 @@ static Napi::Value TranslateVariadicCall(const FunctionInfo *func, void *native,
         if (RG_UNLIKELY(!param.type))
             return env.Null();
         if (RG_UNLIKELY(!CanPassType(param.type, param.directions))) {
-            ThrowError<Napi::TypeError>(env, "Type %1 cannot be used as a parameter (maybe try %1 *)", param.type->name);
+            ThrowError<Napi::TypeError>(env, "Type %1 cannot be used as a parameter", param.type->name);
             return env.Null();
         }
         if (RG_UNLIKELY(copy.parameters.len >= MaxParameters)) {
@@ -2084,9 +2079,9 @@ static Napi::Value CallPointerSync(const Napi::CallbackInfo &info)
     }
 
     const FunctionInfo *proto = type->ref.proto;
-    RG_ASSERT(!proto->variadic);
 
-    return TranslateNormalCall(proto, ptr, info);
+    return proto->variadic ? TranslateVariadicCall(proto, ptr, info)
+                           : TranslateNormalCall(proto, ptr, info);
 }
 
 extern "C" void RelayCallback(Size idx, uint8_t *own_sp, uint8_t *caller_sp, BackRegisters *out_reg)

package/src/koffi/src/parser.cc

@@ -75,7 +75,7 @@ bool PrototypeParser::Parse(const char *str, FunctionInfo *out_func)
             param.type = ParseType();
 
             if (!CanPassType(param.type, param.directions)) {
-                MarkError("Type %1 cannot be used as a parameter (maybe try %1 *)", param.type->name);
+                MarkError("Type %1 cannot be used as a parameter", param.type->name);
                 return false;
             }
             if (out_func->parameters.len >= MaxParameters) {

package/src/koffi/src/util.cc

@@ -371,6 +371,8 @@ bool CanPassType(const TypeInfo *type, int directions)
             return false;
         if (type->primitive == PrimitiveKind::Prototype)
             return false;
+        if (type->primitive == PrimitiveKind::Callback && type->ref.proto->variadic)
+            return false;
 
         return true;
     }
@@ -394,6 +396,8 @@ bool CanStoreType(const TypeInfo *type)
         return false;
     if (type->primitive == PrimitiveKind::Prototype)
         return false;
+    if (type->primitive == PrimitiveKind::Callback && type->ref.proto->variadic)
+        return false;
 
     return true;
 }