koffi 2.3.18 → 2.3.20

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ### Koffi 2.3
 
+#### Koffi 2.3.20
+
+**Main fixes:**
+
+- Support explicit library unloading with `lib.unload()`
+
+#### Koffi 2.3.19
+
+**Main fixes:**
+
+- Actually allow non-ambiguous [string] values for `void *` arguments
+
 #### Koffi 2.3.18
 
 **Main fixes:**

package/doc/functions.md

@@ -1,20 +1,32 @@
-# Function definitions
+# Library functions
 
-## Definition syntax
+## Loading libraries
 
 To declare functions, start by loading the shared library with `koffi.load(filename)`.
 
 ```js
 const koffi = require('koffi');
 const lib = koffi.load('/path/to/shared/library'); // File extension depends on platforms: .so, .dll, .dylib, etc.
+````
+
+This library will be automatically unloaded once all references to it (including all the functions that use it, as described below).
+
+Starting with *Koffi 2.3.20*, you can explicitly unload a library by calling `lib.unload()`. Any attempt to find or call a function from this library after unloading it will crash.
+
+```{note}
+On some platforms (such as with the [musl C library on Linux](https://wiki.musl-libc.org/functional-differences-from-glibc.html#Unloading-libraries)), shared libraries cannot be unloaded, so the library will remain loaded and memory mapped after the call to `lib.unload()`.
 ```
 
-You can use the returned object to load C functions from the library. To do so, you can use two syntaxes:
+## Function definitions
+
+### Definition syntax
+
+Use the object returned by `koffi.load()` to load C functions from the library. To do so, you can use two syntaxes:
 
 - The classic syntax, inspired by node-ffi
 - C-like prototypes
 
-### Classic syntax
+#### Classic syntax
 
 To declare a function, you need to specify its non-mangled name, its return type, and its parameters. Use an ellipsis as the last parameter for variadic functions.
 
@@ -25,7 +37,7 @@ const atoi = lib.func('atoi', 'int', ['str']);
 
 Koffi automatically tries mangled names for non-standard x86 calling conventions. See the section on [calling conventions](#calling-conventions) for more information on this subject.
 
-### C-like prototypes
+#### C-like prototypes
 
 If you prefer, you can declare functions using simple C-like prototype strings, as shown below:
 
@@ -36,7 +48,7 @@ const atoi = lib.func('int atoi(str)'); // The parameter name is not used by Kof
 
 You can use `()` or `(void)` for functions that take no argument.
 
-## Variadic functions
+### Variadic functions
 
 Variadic functions are declared with an ellipsis as the last argument.
 
@@ -51,7 +63,7 @@ printf('Integer %d, double %g, str %s', 'int', 6, 'double', 8.5, 'str', 'THE END
 
 On x86 platforms, only the Cdecl convention can be used for variadic functions.
 
-## Calling conventions
+### Calling conventions
 
 By default, calling a C function happens synchronously.
 

package/package.json

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

package/src/koffi/src/call.cc

@@ -981,19 +981,24 @@ bool CallData::PushPointer(Napi::Value value, const TypeInfo *type, int directio
             Size out_max_len = -1;
 
             if (value.IsArray()) {
-                if (RG_UNLIKELY(!type->ref.type->size)) {
-                    ThrowError<Napi::TypeError>(env, "Cannot pass %1 value to void *, use koffi.as()",
-                                                type->ref.type != instance->void_type ? "opaque" : "ambiguous");
-                    return false;
-                }
-
                 Napi::Array array = value.As<Napi::Array>();
                 Size len = PushIndirectString(array, type->ref.type, &ptr);
 
                 if (len >= 0) {
+                    if (RG_UNLIKELY(!type->ref.type->size && type->ref.type != instance->void_type)) {
+                        ThrowError<Napi::TypeError>(env, "Cannot pass [string] value to %1", type->name);
+                        return false;
+                    }
+
                     out_kind = (type->ref.type->size == 2) ? OutArgument::Kind::String16 : OutArgument::Kind::String;
                     out_max_len = len;
                 } else {
+                    if (RG_UNLIKELY(!type->ref.type->size)) {
+                        ThrowError<Napi::TypeError>(env, "Cannot pass %1 value to %2, use koffi.as()",
+                                                    type->ref.type != instance->void_type ? "opaque" : "ambiguous", type->name);
+                        return false;
+                    }
+
                     Size len = (Size)array.Length();
                     Size size = len * type->ref.type->size;
 
@@ -1026,8 +1031,8 @@ bool CallData::PushPointer(Napi::Value value, const TypeInfo *type, int directio
             } else if (RG_LIKELY(type->ref.type->primitive == PrimitiveKind::Record ||
                                  type->ref.type->primitive == PrimitiveKind::Union)) {
                 if (RG_UNLIKELY(!type->ref.type->size)) {
-                    ThrowError<Napi::TypeError>(env, "Cannot pass %1 value to void *, use koffi.as()",
-                                                type->ref.type != instance->void_type ? "opaque" : "ambiguous");
+                    ThrowError<Napi::TypeError>(env, "Cannot pass %1 value to %2, use koffi.as()",
+                                                type->ref.type != instance->void_type ? "opaque" : "ambiguous", type->name);
                     return false;
                 }
 

package/src/koffi/src/ffi.cc

@@ -1532,6 +1532,16 @@ static Napi::Value FindLibraryFunction(const Napi::CallbackInfo &info, CallConve
     return wrapper;
 }
 
+static Napi::Value UnloadLibrary(const Napi::CallbackInfo &info)
+{
+    Napi::Env env = info.Env();
+    LibraryHolder *lib = (LibraryHolder *)info.Data();
+
+    lib->Unload();
+
+    return env.Undefined();
+}
+
 static Napi::Value LoadSharedLibrary(const Napi::CallbackInfo &info)
 {
     Napi::Env env = info.Env();
@@ -1610,6 +1620,8 @@ static Napi::Value LoadSharedLibrary(const Napi::CallbackInfo &info)
 
 #undef ADD_CONVENTION
 
+    obj.Set("unload", Napi::Function::New(env, UnloadLibrary, "unload", (void *)lib->Ref()));
+
     return obj;
 }
 
@@ -1721,7 +1733,7 @@ static Napi::Value UnregisterCallback(const Napi::CallbackInfo &info)
     return env.Undefined();
 }
 
-LibraryHolder::~LibraryHolder()
+void LibraryHolder::Unload()
 {
 #ifdef _WIN32
     if (module && module != GetModuleHandle(nullptr)) {
@@ -1732,6 +1744,8 @@ LibraryHolder::~LibraryHolder()
         dlclose(module);
     }
 #endif
+
+    module = nullptr;
 }
 
 const LibraryHolder *LibraryHolder::Ref() const

package/src/koffi/src/ffi.hh

@@ -155,7 +155,9 @@ struct LibraryHolder {
     mutable std::atomic_int refcount { 1 };
 
     LibraryHolder(void *module) : module(module) {}
-    ~LibraryHolder();
+    ~LibraryHolder() { Unload(); }
+
+    void Unload();
 
     const LibraryHolder *Ref() const;
     void Unref() const;