koffi - npm Package Compare versions

Comparing version 2.4.1 to 2.4.2

CHANGELOG.md

@@ -7,2 +7,12 @@ # Changelog
 
+#### Koffi 2.4.2
+
+**Main changes:**
+
+- Support calling variadic function pointers
+
+**Other changes:**
+
+- Add documentation for function pointers
+
 #### Koffi 2.4.1
@@ -12,4 +22,4 @@
 
-- 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`
@@ -16,0 +26,0 @@

doc/functions.md

@@ -1,2 +0,2 @@
-# Native functions
+# Function calls
 
@@ -92,3 +92,3 @@ ## Loading libraries
 
-## Function calls
+## Call types
 
@@ -141,6 +141,75 @@ ### Synchronous calls
 
-## 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.json

 {
     "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",
@@ -6,0 +6,0 @@ "keywords": [

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Native code

Supply chain risk

Contains native code (e.g., compiled binaries or shared libraries). Including native code can obscure malicious behavior.

Found 21 instances in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Native code

Supply chain risk

Contains native code (e.g., compiled binaries or shared libraries). Including native code can obscure malicious behavior.

Found 21 instances in 1 package

Improved metrics

Total package byte prevSize

67602554

increased by0.01%

No dependency changes