koffi 2.2.2-beta.6 → 2.2.2

package/ChangeLog.md

@@ -2,6 +2,20 @@
 
 ## History
 
+### Koffi 2.2.2
+
+**Main fixes:**
+
+- Support transparent [asynchronous callbacks](callbacks.md#asynchronous-callbacks)
+- Expand from a maximum of 16+16 to 1024 callbacks running in parallel
+
+**Other fixes:**
+
+- Fix bundler support by removing shebang from index.js
+- Fix bugs when loading Koffi multiples times in same process (context aware module)
+- Check N-API version when module is loaded
+- Optimize callback unregistration
+
 ### Koffi 2.2.1
 
 **Main fixes:**

package/doc/callbacks.md

@@ -172,9 +172,16 @@ console.log(array); // Prints ['123', 'bar', 'foo', 'foobar']
 
 *New in Koffi 2.2.2*
 
-In Koffi, [asynchronous native calls](functions.md#asynchronous-calls) happen on a secondary thread. However, JS execution is inherently single-threaded, callbacks must run on the main thread.
+JS execution is inherently single-threaded, so JS callbacks must run on the main thread. There are two ways you may want to call a callback function from another thread:
 
-Koffi deals with this by running the JS callback function in the Node.js event loop. This means the callback cannot run while the engine is busy running synchronous code.
+- Call the callback from an asynchronous FFI call (e.g. `waitpid.async`)
+- Inside a synchronous FFI call, pass the callback to another thread
+
+In both cases, Koffi will queue the call back to JS to run on the main thread, as soon as the JS event loop has a chance to run (for example when you await a promise).
+
+```{warning}
+Be careful, you can easily get into a deadlock situation if you call a callback from a secondary thread and your main thread never lets the JS event loop run (for example, if the main thread waits for the secondary thread to finish something itself).
+```
 
 ## Handling of exceptions
 

package/package.json

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

package/src/koffi/src/call.cc

@@ -81,6 +81,9 @@ CallData::~CallData()
 void CallData::RelaySafe(Size idx, uint8_t *own_sp, uint8_t *caller_sp, BackRegisters *out_reg)
 {
     if (std::this_thread::get_id() != instance->main_thread_id) {
+        // JS/V8 is single-threaded, and runs on main_thread_id. Forward the call
+        // to the JS event loop.
+
         RelayContext ctx;
 
         ctx.call = this;

package/src/koffi/src/ffi.cc

@@ -1065,9 +1065,6 @@ static Napi::Value TranslateNormalCall(const Napi::CallbackInfo &info)
     InstanceMemory *mem = instance->memories[0];
     CallData call(env, instance, mem);
 
-    RG_DEFER_C(prev_call = exec_call) { exec_call = prev_call; };
-    exec_call = &call;
-
     if (!RG_UNLIKELY(call.Prepare(func, info)))
         return env.Null();
 
@@ -1113,7 +1110,7 @@ static Napi::Value TranslateVariadicCall(const Napi::CallbackInfo &info)
     for (Size i = func.parameters.len; i < (Size)info.Length(); i += 2) {
         ParameterInfo param = {};
 
-        param.type = ResolveType(info[i], &param.directions);
+        param.type = ResolveType(info[(uint32_t)i], &param.directions);
 
         if (RG_UNLIKELY(!param.type))
             return env.Null();
@@ -1893,6 +1890,9 @@ extern "C" void RelayCallback(Size idx, uint8_t *own_sp, uint8_t *caller_sp, Bac
     if (RG_LIKELY(exec_call)) {
         exec_call->RelaySafe(idx, own_sp, caller_sp, out_reg);
     } else {
+        // This happens if the callback pointer is called from a different thread
+        // than the one that runs the FFI call (sync or async).
+
         TrampolineInfo *trampoline = &shared.trampolines[idx];
 
         Napi::Env env = trampoline->func.Env();