@lakutata/ffi 0.0.0-stage → 3.1.5

package/dist/esm/lib/library/NativeCallback.js

@@ -0,0 +1,59 @@
+import koffi from 'koffi';
+/**
+ * A JS function a library can call at any time (a persistent callback), made by `callback()` of a library: give its
+ * `pointer` to the library, and release it when the library no longer calls it. The callbacks of a library are released
+ * when it is closed; a process has at most 8192 of them at a time.
+ *
+ * When it is called from another thread of the library, it runs in the JS thread once the event loop gets to it. An
+ * exception it throws goes to the error handler of its library (the `error` event of a component), and the library gets
+ * zero (or a null pointer) as its result.
+ * @example
+ * ```typescript
+ * import {loadNativeLibrary, type NativeCallback} from '@lakutata/ffi'
+ *
+ * const vendor = loadNativeLibrary('vendor', 'typedef void (*vendor_log)(int level, const char *message);')
+ * const setLogger = vendor.func<(logger: bigint | null) => void>('void vendor_set_logger(vendor_log logger)')
+ * const logger: NativeCallback = vendor.callback('vendor_log', (level: number, message: string): void => console.log(level, message))
+ * setLogger(logger.pointer)
+ * //Once the library no longer calls it
+ * setLogger(null)
+ * logger.release()
+ * ```
+ */
+export class NativeCallback {
+    #pointer;
+    #onRelease;
+    #released = false;
+    /**
+     * A registered callback (made by `callback()` of a library, not by this constructor).
+     * @param pointer Its pointer.
+     * @param onRelease Called once it is released.
+     */
+    constructor(pointer, onRelease) {
+        this.#pointer = pointer;
+        this.#onRelease = onRelease;
+    }
+    /**
+     * The pointer to give to the library: the address of a C function calling the JS function.
+     */
+    get pointer() {
+        return this.#pointer;
+    }
+    /**
+     * Whether it is released: the library must not call it any more.
+     */
+    get released() {
+        return this.#released;
+    }
+    /**
+     * Release it: its pointer is no longer valid, its slot is free for another callback. Releasing it again does
+     * nothing.
+     */
+    release() {
+        if (this.#released)
+            return;
+        this.#released = true;
+        koffi.unregister(this.#pointer);
+        this.#onRelease(this);
+    }
+}

package/dist/esm/lib/library/NativeLibraryHandle.js

@@ -0,0 +1,532 @@
+import koffi from 'koffi';
+import { NativeDeclarationException } from '../../exceptions/NativeDeclarationException.js';
+import { NativeLibraryClosedException } from '../../exceptions/NativeLibraryClosedException.js';
+import { bindFunction, convertedCallback } from '../backend/Functions.js';
+import { layoutOf } from '../declarations/Layout.js';
+import { DeclarationParser } from '../declarations/Parser.js';
+import { CURRENT_PLATFORM } from '../declarations/Platform.js';
+import { typeText } from '../declarations/Types.js';
+import { allocateNative, checkedPointer, freeNative, nativeErrno, nativeWindowsError, readNative, TypeNames, TYPES, typeSize, writeNative } from '../Runtime.js';
+import { NativeThreads } from '../thread/NativeThreads.js';
+import { NativeCallback } from './NativeCallback.js';
+import { loadLibrary } from './Resolve.js';
+/**
+ * The declarations of a library, shared by the libraries loaded with the same declarations: read once, their C types and
+ * their prototypes made once (koffi never frees a type)
+ */
+class LibraryModel {
+    #prototypes;
+    /**
+     * Read the declarations.
+     * @param declarations The C declarations.
+     */
+    constructor(declarations) {
+        this.parser = new DeclarationParser(CURRENT_PLATFORM);
+        this.names = new TypeNames(this.parser);
+        this.#prototypes = new Map();
+        if (declarations)
+            this.parser.parse(declarations);
+    }
+    /**
+     * A prototype, read once.
+     * @param text The prototype.
+     */
+    prototype(text) {
+        let declaration = this.#prototypes.get(text);
+        if (!declaration) {
+            declaration = this.parser.prototype(text);
+            this.#prototypes.set(text, declaration);
+        }
+        return declaration;
+    }
+}
+const models = new Map();
+/**
+ * The model of declarations, the same for the same text
+ * @param declarations
+ */
+function modelOf(declarations) {
+    let model = models.get(declarations);
+    if (!model) {
+        model = new LibraryModel(declarations);
+        models.set(declarations, model);
+    }
+    return model;
+}
+/**
+ * The value a callback returns to the library when it throws: zero, false, a null pointer
+ * @param type
+ */
+function zeroOf(type) {
+    switch (type.kind) {
+        case 'primitive':
+            if (type.name === 'void')
+                return undefined;
+            if (type.name === 'bool')
+                return false;
+            return 0;
+        case 'enum':
+            return 0;
+        case 'pointer':
+            return null;
+        default:
+            return {};
+    }
+}
+/**
+ * A native library loaded with its declarations, without the container (scripts, tests): its functions, variables and
+ * callbacks, and the native memory read and written with its types. Made by {@link loadNativeLibrary}; a
+ * `NativeLibrary` component holds one.
+ * @example
+ * ```typescript
+ * import {loadNativeLibrary, type NativeLibraryHandle} from '@lakutata/ffi'
+ *
+ * const libc: NativeLibraryHandle = loadNativeLibrary('c', 'typedef struct { int quot; int rem; } div_t;')
+ * const div = libc.func<(numerator: number, denominator: number) => {quot: number, rem: number}>('div_t div(int numerator, int denominator)')
+ * console.log(div(17, 5))
+ * await libc.close()
+ * ```
+ */
+export class NativeLibraryHandle {
+    #library;
+    #file;
+    #model;
+    #parser;
+    #names;
+    #options;
+    #functions = new Map();
+    #callbacks = new Set();
+    #allocations = new Set();
+    #frees = new Map();
+    #calls;
+    #threads;
+    //The errno and the last error of Windows of the thread after the last asynchronous call completed in the threads
+    #threadErrno;
+    #threadWindowsError;
+    #pending = 0;
+    #drained = [];
+    #closed = false;
+    /**
+     * Load a library (see {@link loadNativeLibrary}).
+     * @param names Its file names: one, or one by platform; `c` for the C library.
+     * @param declarations Its C declarations: the types, functions and variables its functions use.
+     * @param options Where it is found, how it is closed.
+     */
+    constructor(names, declarations = '', options = {}) {
+        this.#options = options;
+        this.#model = modelOf(declarations);
+        this.#parser = this.#model.parser;
+        this.#names = this.#model.names;
+        const { library, file } = loadLibrary(names, options);
+        this.#library = library;
+        this.#file = file;
+        if (options.threads !== undefined && (!Number.isInteger(options.threads) || options.threads < 0))
+            throw new NativeDeclarationException(`The threads of a library are a number of threads (${options.threads})`);
+        if (options.threads)
+            this.#threads = new NativeThreads(file, declarations, options.threads, options.crt);
+        this.#calls = {
+            start: () => {
+                if (this.#closed)
+                    throw new NativeLibraryClosedException(`The library ${this.#file} is closed`);
+                this.#pending++;
+            },
+            end: () => {
+                if (--this.#pending > 0)
+                    return;
+                const drained = this.#drained;
+                this.#drained = [];
+                for (const resolve of drained)
+                    resolve();
+            }
+        };
+    }
+    /**
+     * The file the library was loaded from.
+     */
+    get file() {
+        return this.#file;
+    }
+    /**
+     * Whether it is closed.
+     */
+    get closed() {
+        return this.#closed;
+    }
+    /**
+     * The asynchronous calls running.
+     */
+    get pending() {
+        return this.#pending;
+    }
+    /**
+     * The worker threads of the library (0: the asynchronous calls run in the thread pool of the runtime).
+     */
+    get threads() {
+        return this.#threads?.count ?? 0;
+    }
+    /**
+     * Settled once the threads of the library have loaded it (at once without threads): rejected with the error of a
+     * thread that could not. The asynchronous calls wait for them anyway.
+     */
+    get ready() {
+        return this.#threads?.ready ?? Promise.resolve();
+    }
+    /**
+     * The constants of its declarations: the values of the enumerations, of the static constants and of the macros whose
+     * value is an integer.
+     */
+    get constants() {
+        return Object.fromEntries(this.#parser.declarations.constants);
+    }
+    /**
+     * Add C declarations to the ones of the library (and of the libraries loaded with the same declarations, which share
+     * them).
+     * @param text The declarations.
+     */
+    declare(text) {
+        this.#parser.parse(text);
+        this.#threads?.declare(text);
+    }
+    /**
+     * A function of the library, from its prototype: the function of koffi itself when nothing has to be converted.
+     * @param prototype Its C prototype, with the types of the declarations: `int sqlite3_open(const char *filename,
+     * _Out_ sqlite3 **db)`.
+     * @param options Whether it is asynchronous, how its strings are freed, how its 64-bit integers are given.
+     * @returns The function.
+     */
+    func(prototype, options = {}) {
+        this.#open();
+        const key = `${prototype}\u0000${JSON.stringify(options)}`;
+        let bound = this.#functions.get(key);
+        if (!bound) {
+            bound = this.#bind(this.#model.prototype(prototype), options, prototype, false);
+            this.#functions.set(key, bound);
+        }
+        return bound;
+    }
+    /**
+     * A function of the declarations, by its name.
+     * @param name Its name.
+     * @param options Whether it is asynchronous, how its strings are freed, how its 64-bit integers are given.
+     * @returns The function.
+     */
+    function(name, options = {}) {
+        this.#open();
+        const declaration = this.#parser.declarations.functions.get(name);
+        if (!declaration)
+            throw new NativeDeclarationException(`The function ${name} is not declared`);
+        const key = `\u0001${name}\u0000${JSON.stringify(options)}`;
+        let bound = this.#functions.get(key);
+        if (!bound) {
+            bound = this.#bind(declaration, options, name, true);
+            this.#functions.set(key, bound);
+        }
+        return bound;
+    }
+    /**
+     * A variable the library exports: declared in the declarations (`extern const char sqlite3_version[];`), or by the
+     * declaration given.
+     * @param declaration Its name, or its declaration.
+     * @returns Its address, and the functions reading and writing its value.
+     */
+    variable(declaration) {
+        this.#open();
+        let name = declaration.trim();
+        if (!/^[A-Za-z_]\w*$/.test(name)) {
+            const before = new Set(this.#parser.declarations.variables.keys());
+            this.#parser.parse(/;\s*$/.test(name) ? name : `${name};`);
+            name = [...this.#parser.declarations.variables.keys()].find((variable) => !before.has(variable)) ?? name.match(/(\w+)\s*(\[[^\]]*\])?\s*;?\s*$/)?.[1] ?? name;
+        }
+        const variable = this.#parser.declarations.variables.get(name);
+        if (!variable)
+            throw new NativeDeclarationException(`The variable ${name} is not declared`);
+        let address;
+        try {
+            address = this.#library.symbol(variable.symbol);
+        }
+        catch (error) {
+            throw new NativeDeclarationException(`The variable ${name} is not in the library (${variable.symbol}): ${error.message}`);
+        }
+        const type = variable.type;
+        const unknownLength = type.kind === 'array' && type.length === 0;
+        const converter = TYPES.converter(type);
+        return {
+            address: address,
+            get: () => {
+                this.#open();
+                if (unknownLength) {
+                    const element = type.of;
+                    return (element.kind === 'primitive' && element.name === 'char' ? koffi.decode.string(address) : address);
+                }
+                const value = koffi.decode(address, TYPES.type(type));
+                return (converter?.fromNative ? converter.fromNative(value) : value);
+            },
+            set: (value) => {
+                this.#open();
+                if (variable.constant)
+                    throw new NativeDeclarationException(`The variable ${name} is const`);
+                if (unknownLength)
+                    throw new NativeDeclarationException(`The array ${name} has no length: write its elements through its address`);
+                koffi.encode(address, TYPES.type(type), converter?.toNative ? converter.toNative(value) : value);
+            }
+        };
+    }
+    /**
+     * A persistent callback: a JS function the library can call at any time, released by `release()` or when the
+     * library is closed.
+     * @param type Its type: the name of a pointer-to-function type of the declarations (`vendor_log`), or its prototype
+     * (`void vendor_log(int level, const char *message)`).
+     * @param callback The JS function.
+     * @returns The callback, whose `pointer` is given to the library.
+     */
+    callback(type, callback) {
+        this.#open();
+        let prototype;
+        if (type.includes('(')) {
+            prototype = this.#parser.prototype(type).type;
+        }
+        else {
+            const named = this.#names.type(type);
+            const target = named.kind === 'pointer' ? named.to : named;
+            if (target.kind !== 'function')
+                throw new NativeDeclarationException(`The type ${type} is not a function type (${typeText(named)})`);
+            prototype = target;
+        }
+        const onError = this.#options.onCallbackError ?? ((error) => console.error('A callback of a native library threw:', error));
+        const zero = zeroOf(prototype.result);
+        const safe = (...args) => {
+            try {
+                return callback(...args);
+            }
+            catch (error) {
+                onError(error);
+                return zero;
+            }
+        };
+        const pointer = koffi.register(convertedCallback(prototype, TYPES, safe), koffi.pointer(TYPES.prototype(prototype)));
+        const registered = new NativeCallback(pointer, (released) => this.#callbacks.delete(released));
+        this.#callbacks.add(registered);
+        return registered;
+    }
+    /**
+     * Read native memory, as a type of the declarations: a value, or an array of values.
+     * @param pointer The address.
+     * @param type The type: `int`, `struct timeval`, `char *` (a string).
+     * @param count The number of values, for an array.
+     * @returns The value, or the array.
+     */
+    read(pointer, type, count) {
+        this.#open();
+        return readNative(this.#names, pointer, type, count);
+    }
+    /**
+     * Write a value to native memory, as a type of the declarations.
+     * @param pointer The address.
+     * @param type The type.
+     * @param value The value.
+     */
+    write(pointer, type, value) {
+        this.#open();
+        writeNative(this.#names, pointer, type, value);
+    }
+    /**
+     * The size of a type of the declarations, in bytes.
+     * @param type The type.
+     */
+    sizeOf(type) {
+        return typeSize(this.#names, type);
+    }
+    /**
+     * The offset of a member of a struct of the declarations, in bytes.
+     * @param type The struct.
+     * @param member The member.
+     */
+    offsetOf(type, member) {
+        const record = this.#names.type(type);
+        if (record.kind !== 'struct' && record.kind !== 'union')
+            throw new NativeDeclarationException(`${type} is not a struct or a union`);
+        const placed = layoutOf(record, CURRENT_PLATFORM).members.find((candidate) => candidate.member.name === member);
+        if (!placed)
+            throw new NativeDeclarationException(`${type} has no member ${member}`);
+        return placed.offset;
+    }
+    /**
+     * Allocate native memory for values of a type of the declarations: memory that does not move, which the library can
+     * keep; freed by `free()`, or when the library is closed.
+     * @param type The type.
+     * @param count The number of values.
+     * @returns Its address.
+     */
+    alloc(type, count = 1) {
+        this.#open();
+        const pointer = allocateNative(this.#names, type, count);
+        this.#allocations.add(pointer);
+        return pointer;
+    }
+    /**
+     * Free memory allocated by `alloc()`.
+     * @param pointer Its address.
+     */
+    free(pointer) {
+        const address = checkedPointer(pointer, 'free');
+        this.#allocations.delete(address);
+        freeNative(address);
+    }
+    /**
+     * The errno of the last call of this thread (on Windows, the one of the C library given by the `crt` option); with
+     * threads, the one of the thread of the last asynchronous call completed (reliable with one thread, or when the
+     * asynchronous calls are awaited one at a time).
+     */
+    errno() {
+        return this.#threadErrno ?? nativeErrno(this.#options.crt);
+    }
+    /**
+     * The last error of the Windows API (GetLastError) after the last call of this thread; with threads, the one of the
+     * thread of the last asynchronous call completed; undefined on the other systems.
+     */
+    windowsError() {
+        return this.#threadWindowsError ?? nativeWindowsError();
+    }
+    /**
+     * The asynchronous calls running, once they have all returned.
+     * @param timeout How long to wait at most, in milliseconds.
+     * @returns Whether they have all returned.
+     */
+    drain(timeout = Infinity) {
+        if (!this.#pending)
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            const timer = Number.isFinite(timeout) ? setTimeout(() => resolve(false), timeout) : undefined;
+            this.#drained.push(() => {
+                if (timer)
+                    clearTimeout(timer);
+                resolve(true);
+            });
+        });
+    }
+    /**
+     * Close the library: new asynchronous calls are refused, the running ones awaited (a worker thread stopped during
+     * one crashes Bun), the callbacks released, the memory of `alloc()` freed, the library unloaded (unless kept
+     * loaded; musl never unloads). Its functions must not be called any more: a function of an unloaded library ends
+     * the process. When calls still run after the timeout, the ones in the thread pool go on, the ones in the threads
+     * of the library are rejected (their threads end once they return), and the library, its callbacks and its memory
+     * are left as they are: a call returning into an unloaded library, or calling a released callback, would end the
+     * process.
+     * @param timeout How long to wait for the asynchronous calls, in milliseconds.
+     */
+    async close(timeout = 10000) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        //Decided before the threads close: they reject the calls still running, which then no longer count
+        const drained = await this.drain(timeout);
+        await this.#threads?.close();
+        this.#functions.clear();
+        if (!drained)
+            return;
+        for (const callback of [...this.#callbacks])
+            callback.release();
+        for (const pointer of this.#allocations)
+            freeNative(pointer);
+        this.#allocations.clear();
+        if (!this.#options.keepLoaded)
+            this.#library.unload();
+    }
+    /**
+     * Throws once the library is closed
+     */
+    #open() {
+        if (this.#closed)
+            throw new NativeLibraryClosedException(`The library ${this.#file} is closed`);
+    }
+    /**
+     * A function bound, with its options; an asynchronous function of a library with threads, called in them
+     * @param declaration
+     * @param options
+     * @param text its prototype, or the name of the declared function
+     * @param named
+     */
+    #bind(declaration, options, text, named) {
+        if (options.async && this.#threads)
+            return this.#threaded(this.#threads, { declaration: text, named: named, options: { free: options.free, int64: options.int64 }, type: declaration });
+        return bindFunction(this.#library, declaration, TYPES, (text) => this.#names.koffi(text), {
+            async: options.async,
+            int64: options.int64,
+            calls: this.#calls,
+            ...options.free ? { free: this.#freeFunction(options.free) } : {}
+        });
+    }
+    /**
+     * An asynchronous function called in the threads of the library, counted as its other asynchronous calls
+     * @param threads
+     * @param fn
+     */
+    #threaded(threads, fn) {
+        threads.bind(fn);
+        return (...args) => {
+            try {
+                this.#calls.start();
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+            return threads.call(fn, args).then((result) => {
+                this.#threadErrno = result.errno;
+                this.#threadWindowsError = result.windowsError;
+                this.#calls.end();
+                return result.value;
+            }, (error) => {
+                this.#calls.end();
+                throw error;
+            });
+        };
+    }
+    /**
+     * The function freeing the strings of a function: one of the library, or free() of the C library
+     * @param free
+     */
+    #freeFunction(free) {
+        if (free === true)
+            return (pointer) => koffi.free(pointer);
+        let found = this.#frees.get(free);
+        if (!found) {
+            try {
+                found = this.#library.func(free, 'void', ['void *']);
+            }
+            catch (error) {
+                throw new NativeDeclarationException(`The function ${free} freeing the strings is not in the library: ${error.message}`);
+            }
+            this.#frees.set(free, found);
+        }
+        return found;
+    }
+}
+/**
+ * Load a native library with its C declarations, without the container (scripts, tests); in an application, declare a
+ * `NativeLibrary` component instead. The library is looked for in the directories of `search`, then where the system
+ * looks for libraries.
+ * @param names Its file names: one (`sqlite3`, completed as the platform names libraries), one by platform
+ * (`{darwin: 'libsqlite3.dylib', linux: 'libsqlite3.so.0', win32: 'winsqlite3.dll'}`), or `c` for the C library.
+ * @param declarations Its C declarations: the types its functions use, its functions, its variables, its constants.
+ * @param options Where it is found, how it is closed.
+ * @returns The library.
+ * @throws {NativeLibraryNotFoundException} When it cannot be loaded (the message lists what was tried).
+ * @throws {NativeDeclarationException} When the declarations cannot be read.
+ * @example
+ * ```typescript
+ * import {loadNativeLibrary, type Out, type Pointer} from '@lakutata/ffi'
+ *
+ * const sqlite = loadNativeLibrary({darwin: 'libsqlite3.dylib', linux: 'libsqlite3.so.0', win32: 'winsqlite3.dll'}, `
+ *     typedef struct sqlite3 sqlite3;
+ *     #define SQLITE_OK 0
+ * `)
+ * const open = sqlite.func<(filename: string, db: Out<Pointer>) => number>('int sqlite3_open(const char *filename, _Out_ sqlite3 **db)')
+ * const close = sqlite.func<(db: Pointer) => number>('int sqlite3_close(sqlite3 *db)')
+ * const db: Out<Pointer> = [null]
+ * if (open(':memory:', db) === Number(sqlite.constants.SQLITE_OK)) close(db[0]!)
+ * await sqlite.close()
+ * ```
+ */
+export function loadNativeLibrary(names, declarations = '', options = {}) {
+    return new NativeLibraryHandle(names, declarations, options);
+}