ffi-rs

Use DataType.External to pass pointers between Node.js and C.

• createPointer: Creates a pointer for a specific type (e.g., *const i32).
• unwrapPointer: Used when you have a pointer to a pointer (e.g., *mut *const char) and need to extract the inner pointer to pass to a function.
• restorePointer: Converts a pointer back into its original JavaScript value (e.g., converting a char* back to a string).
• wrapPointer: Used to wrap a pointer returned from a foreign function so it can be processed by restorePointer.
• freePointer: Manually frees memory associated with a pointer. You must specify the pointerType (e.g., PointerType.RsPointer or PointerType.CPointer).

const { createPointer, unwrapPointer, restorePointer, freePointer, DataType, PointerType } = require('ffi-rs');

// 1. Create a pointer
const pointer = createPointer({
    paramsType: [DataType.I32],
    paramsValue: [100],
});

// 2. Use unwrapPointer for double pointers (pointer to pointer)
load({
    library: "libsum",
    funcName: "receiveStringPointer",
    paramsType: [DataType.External],
    paramsValue: unwrapPointer(pointer),
    retType: DataType.Void,
});

// 3. Free the pointer when done
freePointer({
    paramsType: [DataType.I32],
    paramsValue: pointer,
    pointerType: PointerType.RsPointer
});

To pass or receive raw pointers between Node.js and C, use DataType.External. This wraps the pointer in a way that is compatible with both environments.

Key functions for pointer manipulation:

• createPointer: Wraps data into a pointer (e.g., creating a *mut i32 from a number).
• restorePointer: Recovers data from a pointer returned by a C function.
• wrapPointer: Creates a multi-level pointer (e.g., turning *mut c_char into *mut *mut c_char).
• unwrapPointer: Extracts the inner pointer from a multi-level pointer.
• freePointer: Manually releases memory for pointers using DataType.External (required if freeResultMemory: false was used or when handling External types).

const { load, DataType, createPointer, unwrapPointer } = require('ffi-rs');

// 1. Getting a pointer from C
const ptr = load({
    library: 'libsum',
    funcName: 'concatenateStrings',
    retType: DataType.External,
    paramsType: [DataType.String, DataType.String],
    paramsValue: ['a', 'b'],
});

// 2. Passing a pointer to C
const string = load({
    library: 'libsum',
    funcName: 'getStringFromPtr',
    retType: DataType.String,
    paramsType: [DataType.External],
    paramsValue: [ptr],
});

To interact with C++ classes, wrap the C++ types in C-compatible functions (e.g., a factory function that returns a pointer). In ffi-rs, treat these class pointers as DataType.External.

When using DataType.External, you are responsible for manual memory management. Use freePointer to release the memory when the pointer is no longer needed.

// 1. Get a pointer to the C++ instance
const classPointer = load({
    library: "libsum",
    funcName: "createMyClassFromC",
    retType: DataType.External,
    paramsType: [DataType.String, DataType.I32],
    paramsValue: ["classString", 26],
});

// 2. Use the pointer in other functions
load({
    library: "libsum",
    funcName: "printMyClass",
    retType: DataType.External,
    paramsType: [DataType.External],
    paramsValue: [classPointer],
});

// 3. Manually free the memory
freePointer({
    paramsType: [DataType.External],
    paramsValue: [classPointer],
    pointerType: PointerType.CPointer
});

You can pass JavaScript functions to C functions as callbacks. ffi-rs creates a threadsafe_function from the JS function, meaning the JS function will be called asynchronously and the Node.js process will not automatically exit.

To manage memory correctly for these callbacks, it is recommended to use createPointer to create the function pointer for manual memory management, and use freePointer to release the function memory when it is no longer needed.

const testFunction = () => {
    const func = (a, b, c, d, e, f, g) => {
        // ... callback logic ...
        
        // Release function memory when no longer in use
        freePointer({
            paramsType: [
                funcConstructor({
                    paramsType: [
                        DataType.I32,
                        DataType.Boolean,
                        DataType.String,
                        DataType.Double,
                        arrayConstructor({ type: DataType.StringArray, length: 2 }),
                        arrayConstructor({ type: DataType.I32Array, length: 3 }),
                        personType,
                    ],
                    retType: DataType.Void,
                })
            ],
            paramsValue: funcExternal
        })
    };

    // Recommended: use createPointer for manual memory management
    const funcExternal = createPointer({
        paramsType: [
            funcConstructor({
                paramsType: [
                    DataType.I32,
                    DataType.Boolean,
                    DataType.String,
                    DataType.Double,
                    arrayConstructor({ type: DataType.StringArray, length: 2 }),
                    arrayConstructor({ type: DataType.I32Array, length: 3 }),
                    personType,
                ],
                retType: DataType.Void,
            })
        ],
        paramsValue: [func]
    });

    load({
        library: "libsum",
        funcName: "callFunction",
        retType: DataType.Void,
        paramsType: [DataType.External],
        paramsValue: unwrapPointer(funcExternal),
    });
}