Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Implement ffi in Node.js by Rust and NAPI

License

NotificationsYou must be signed in to change notification settings

zhangyuang/node-ffi-rs

Repository files navigation

A module written in Rust and N-API provides interface (FFI) features for Node.js

githubActions

Description

ffi-rs is a high-performance module with small binary size written in Rust and N-API that provides FFI (Foreign Function Interface) features for Node.js. It allows developers to call functions written in other languages such as C++, C, and Rust directly from JavaScript without writing any C++ code.

This module aims to provide similar functionality to the node-ffi module but with a completely rewritten underlying codebase. The node-ffi module has been unmaintained for several years and is no longer usable, so ffi-rs was developed to fill that void.

Features

  • High performance ✨
  • Small binary size
  • Better type hints 🧐
  • Simpler data description and API interface 💗
  • Support more different data types betweenNode.js andC 😊
  • Support modifying data in place 🥸
  • Provide many ways to handle pointer type directly 🐮
  • Support running ffi taskin a new thread 🤩️
  • Support outputerrno info 🤔️
  • No need to useref to handle pointer 🤫

Benchmark

$ node bench/bench.jsRunning"ffi" suite...Progress: 100%  ffi-napi:    2 028 ops/s, ±4.87%| slowest, 99.24% slower  ffi-rs:    318 467 ops/s, ±0.17%| fastestFinished 2 cases!  Fastest: ffi-rs  Slowest: ffi-napi

How to sponsor me

There are two ways to sponsor me both Alipay and WeChat

Eth address: 0x87a2575a5d4dbD5f965e3e3a3d20641BC9a5d192

Changelog

SeeCHANGELOG.md

Ecosystem

abstract-socket-rs

Install

$ npm i ffi-rs

Supported Types

Currently, ffi-rs only supports these types of parameters and return values. However, support for more types may be added in the future based on actual usage scenarios.

Basic Types

Reference Types

C++ Class

If you want to call a C++ function whose argument type is a class, you can use thepointer type. Seetutorial

Supported Platforms

Note: You need to make sure that the compilation environment of the dynamic library is the same as the installation and runtime environment of theffi-rs call.

  • darwin-x64
  • darwin-arm64
  • linux-x64-gnu
  • linux-x64-musl
  • win32-x64-msvc
  • win32-ia32-msvc
  • win32-arm64-msvc
  • linux-arm64-gnu
  • linux-arm64-musl
  • linux-arm-gnueabihf
  • android-arm64

Usage

Viewtests/index.ts for the latest usage

Here is an example of how to use ffi-rs:

For the following C++ code, we compile this file into a dynamic library

Write Foreign Function Code

Note: The return value type of a function must be of type C

#include<cstdio>#include<cstring>#include<iostream>#include<string>extern"C"intsum(int a,int b) {return a + b; }extern"C"doubledoubleSum(double a,double b) {return a + b; }extern"C"constchar *concatenateStrings(constchar *str1,constchar *str2) {  std::string result =std::string(str1) +std::string(str2);char *cstr =newchar[result.length() +1];strcpy(cstr, result.c_str());return cstr;}extern"C"voidnoRet() {printf("%s","hello world"); }extern"C"boolreturn_opposite(bool input) {return !input; }

Compile C Code into a Dynamic Library

$ g++ -dynamiclib -o libsum.so cpp/sum.cpp# macOS$ g++ -shared -o libsum.so cpp/sum.cpp# Linux$ g++ -shared -o sum.dll cpp/sum.cpp# Windows

Call Dynamic Library Using ffi-rs

Then you can useffi-rs to invoke the dynamic library file that contains functions.

Initialization

It's suggested to develop with TypeScript to get type hints

const{    equal}=require('assert')const{    load,    DataType,    open,    close,    arrayConstructor,    define}=require('ffi-rs')consta=1constb=100constdynamicLib=platform==='win32' ?'./sum.dll' :"./libsum.so"// First open dynamic library with key for close// It only needs to be opened once.open({library:'libsum',// keypath:dynamicLib// path})constr=load({library:"libsum",// path to the dynamic library filefuncName:'sum',// the name of the function to callretType:DataType.I32,// the return value typeparamsType:[DataType.I32,DataType.I32],// the parameter typesparamsValue:[a,b]// the actual parameter values// freeResultMemory: true, // whether or not need to free the result of return value memory automatically, default is false})equal(r,a+b)// Release library memory when you're not using it.close('libsum')// Use define function to define a function signatureconstres=define({sum:{library:"libsum",retType:DataType.I32,paramsType:[DataType.I32,DataType.I32],},atoi:{library:"libnative",retType:DataType.I32,paramsType:[DataType.String],}})equal(res.sum([1,2]),3)equal(res.atoi(["1000"]),1000)

Load Main Program Handle

You can also pass an empty path string in theopen function likeffi-napi to get the main program handle. Refer todlopen

open({library:"libnative",path:"",});// In Darwin/Linux, you can call the atoi function which is included in the basic C libraryequal(load({library:"libnative",funcName:"atoi",retType:DataType.I32,paramsType:[DataType.String],paramsValue:["1000"],}),1000,);

Basic Types

number|string|boolean|double|void are basic types

constc="foo"constd=c.repeat(200)equal(c+d,load({library:'libsum',funcName:'concatenateStrings',retType:DataType.String,paramsType:[DataType.String,DataType.String],paramsValue:[c,d]}))equal(undefined,load({library:'libsum',funcName:'noRet',retType:DataType.Void,paramsType:[],paramsValue:[]}))equal(1.1+2.2,load({library:'libsum',funcName:'doubleSum',retType:DataType.Double,paramsType:[DataType.Double,DataType.Double],paramsValue:[1.1,2.2]}))constbool_val=trueequal(!bool_val,load({library:'libsum',funcName:'return_opposite',retType:DataType.Boolean,paramsType:[DataType.Boolean],paramsValue:[bool_val],}))

Buffer

In the latest version,ffi-rs supports modifying data in place.

The sample code is as follows

externintmodifyData(char*buffer) {// modify buffer data in place}
constarr=Buffer.alloc(200)// create bufferconstres=load({library:"libsum",funcName:"modifyData",retType:DataType.I32,paramsType:[DataType.U8Array],paramsValue:[arr]})console.log(arr)// buffer data can be updated

Array

When usingarray asretType , you should usearrayConstructor to specify the array type with a legal length which is important.

If the length is incorrect, the program may exit abnormally

extern"C"int *createArrayi32(constint *arr,int size) {int *vec = (int *)malloc((size) *sizeof(int));for (int i =0; i < size; i++) {    vec[i] = arr[i];  }return vec;}extern"C"double *createArrayDouble(constdouble *arr,int size) {double *vec = (double *)malloc((size) *sizeof(double));for (int i =0; i < size; i++) {    vec[i] = arr[i];  }return vec;}extern"C"char **createArrayString(char **arr,int size) {char **vec = (char **)malloc((size) *sizeof(char *));for (int i =0; i < size; i++) {    vec[i] = arr[i];  }return vec;}
letbigArr=newArray(100).fill(100)deepStrictEqual(bigArr,load({library:'libsum',funcName:'createArrayi32',retType:arrayConstructor({type:DataType.I32Array,length:bigArr.length}),paramsType:[DataType.I32Array,DataType.I32],paramsValue:[bigArr,bigArr.length],}))letbigDoubleArr=newArray(5).fill(1.1)deepStrictEqual(bigDoubleArr,load({library:'libsum',funcName:'createArrayDouble',retType:arrayConstructor({type:DataType.DoubleArray,length:bigDoubleArr.length}),paramsType:[DataType.DoubleArray,DataType.I32],paramsValue:[bigDoubleArr,bigDoubleArr.length],}))letstringArr=[c,c.repeat(20)]deepStrictEqual(stringArr,load({library:'libsum',funcName:'createArrayString',retType:arrayConstructor({type:DataType.StringArray,length:stringArr.length}),paramsType:[DataType.StringArray,DataType.I32],paramsValue:[stringArr,stringArr.length],}))

Pointer

These functions are used to handle pointer types inffi-rs . We useDataType.External to pass pointers betweenNode.js andC .

Create Pointer

UsecreatePointer to create a pointer for specific type in the code as follows:

extern"C"voidreceiveNumPointer(constint*num)// use the rust type expression the pointer type is *const i32constpointer:JsExternal[]=createPointer({paramsType:[DataType.I32],paramsValue:[100],})load({library:"libsum",funcName:"receiveNumPointer",paramsType:[DataType.External],paramsValue:pointer,retType:DataType.Void,})

unwrapPointer

UsecreatePointer to create a data type which store in heap will receive a double pointer means a pointer to a pointer.So we need to useunwrapPointer to get the inner pointer when call foreign function.

extern"C"voidreceiveStringPointer(constchar*str)// because of string is a pointer, so the pointer is a double pointer means a pointer to a string pointer// use the rust type expression pointer type is *mut *const charconstpointer:JsExternal[]=createPointer({paramsType:[DataType.String],paramsValue:["hello"],})load({library:"libsum",funcName:"receiveStringPointer",paramsType:[DataType.External],paramsValue:unwrapPointer(pointer),// use the unwrapPointer to get the inner *mut *const char pointer, which points to a *const char valueretType:DataType.Void,})

restorePointer

If you want to restore the pointer to the original value, you can use therestorePointer function. Corresponds tocreatePointer ,it can receive the result ofcreatePointer and return the original pointer directly withoutwrapPointer orunwrapPointer .

constpointer:JsExternal[]=createPointer({paramsType:[DataType.String],paramsValue:["hello"],})conststr=restorePointer({retType:[DataType.String],paramsValue:pointer,})equal(str,"hello")

wrapPointer

UsewrapPointer when you want to restore the foreign function return value.

extern"C"constchar*returnStringPointer(){char*str=newchar[6];strcpy(str,"hello");returnstr;}// the stringPointer type is *const char, we need to convert it to *mut *const char before call restorePointerconststringPointer=load({library:"libsum",funcName:"returnStringPointer",retType:DataType.External,paramsType:[DataType.String],paramsValue:["hello"],})constwrapStringPointer=wrapPointer([stringPointer])conststr=restorePointer({retType:[DataType.String],paramsValue:wrapStringPointer,})equal(str,"hello")

freePointer

UsefreePointer to free the pointer when it is no longer in use.

consti32Ptr=createPointer({paramsType:[DataType.I32],paramsValue:[100]})consti32Data=restorePointer({paramsValue:i32PtrretType:[DataType.I32],})freePointer({paramsType:[DataType.I32],paramsValue:i32Ptr,pointerType:PointerType.RsPointer})extern"C"constchar*returnStringPointer(){char*str=newchar[6];strcpy(str,"hello");returnstr;}conststringPointer=load({library:"libsum",funcName:"returnStringPointer",retType:DataType.External,paramsType:[DataType.String],paramsValue:["hello"],})freePointer({paramsType:[DataType.External],paramsValue:[stringPointer],pointerType:PointerType.CPointer// will use libc::free to free the memory})

Struct

To create a C struct or get a C struct as a return type, you need to define the types of the parameters strictly in the order in which the fields of the C structure are defined.

ffi-rs provides a C struct namedPerson with many types of fields insum.cpp

The example call method about how to call a foreign function to create aPerson struct or usePerson struct as a return value ishere

Use array in struct

There are two types of arrays in C language likeint* array andint array[100] that have some different usages.

The first typeint* array is a pointer type storing the first address of the array.

The second typeint array[100] is a fixed-length array and each element in the array has a continuous address.

If you use an array as a function parameter, this usually passes an array pointer regardless of which type you define. But if the array type is defined in a struct, the two types of array definitions will cause different sizes and alignments of the struct.

So,ffi-rs needs to distinguish between the two types.

By default,ffi-rs uses dynamic arrays to calculate struct. If you confirm there is a static array, you can define it in this way:

typedefstructPerson {//...uint8_tstaticBytes[16];//...}Person;// use arrayConstructor and set ffiTypeTag field to DataType.StackArraystaticBytes:arrayConstructor({type:DataType.U8Array,length:parent.staticBytes.length,ffiTypeTag:FFITypeTag.StackArray}),

Function

ffi-rs supports passing JS function pointers to C functions, like this:

typedefconstvoid (*FunctionPointer)(int a,bool b,char *c,double d,char **e,int *f, Person *g);extern"C"voidcallFunction(FunctionPointer func) {printf("callFunction\n");for (int i =0; i <2; i++) {int a =100;bool b =false;double d =100.11;char *c = (char *)malloc(14 *sizeof(char));strcpy(c,"Hello, World!");char **stringArray = (char **)malloc(sizeof(char *) *2);    stringArray[0] =strdup("Hello");    stringArray[1] =strdup("world");int *i32Array = (int *)malloc(sizeof(int) *3);    i32Array[0] =101;    i32Array[1] =202;    i32Array[2] =303;    Person *p =createPerson();func(a, b, c, d, stringArray, i32Array, p);  }}

Corresponding to the code above, you can useffi-rs like this:

consttestFunction=()=>{constfunc=(a,b,c,d,e,f,g)=>{equal(a,100);equal(b,false);equal(c,"Hello, World!");equal(d,"100.11");deepStrictEqual(e,["Hello","world"]);deepStrictEqual(f,[101,202,303]);deepStrictEqual(g,person);logGreen("test function succeed");// free function memory when it is not in usefreePointer({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})if(!process.env.MEMORY){close("libsum");}};// suggest using createPointer to create a function pointer for manual memory managementconstfuncExternal=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),});}

The function parameters support all types in the example above.

Attention: since the vast majority of scenarios developers pass JS functions to C as callbacks,ffi-rs will createthreadsafe_function from JS functions which means the JS function will be called asynchronously, and the Node.js process will not exit automatically.

C++

We'll provide more examples from real-world scenarios. If you have any ideas, please submit an issue.

Class type

In C++ scenarios, we can useDataType.External to get a class type pointer.

In the code below, we use C types to wrap C++ types such as convertingchar * tostd::string and returning a class pointer:

MyClass *createMyClass(std::string name,int age) {returnnewMyClass(name, age);}extern"C" MyClass *createMyClassFromC(constchar *name,int age) {returncreateMyClass(std::string(name), age);}extern"C"voidprintMyClass(MyClass *instance) { instance->print(); }

And then, it can be called by the following code:

constclassPointer=load({library:"libsum",funcName:"createMyClassFromC",retType:DataType.External,paramsType:[DataType.String,DataType.I32],paramsValue:["classString",26],});load({library:"libsum",funcName:"printMyClass",retType:DataType.External,paramsType:[DataType.External,],paramsValue:[classPointer],})freePointer({paramsType:[DataType.External],paramsValue:[classPointer],pointerType:PointerType.CPointer})

errno

By default,ffi-rs will not outputerrno info. Developers can get it by passingerrno: true when calling the open method like:

load({library:'libnative',funcName:'setsockopt',retType:DataType.I32,paramsType:[DataType.I32,DataType.I32,DataType.I32,DataType.External,DataType.I32],paramsValue:[socket._handle.fd,level,option,pointer[0],4],errno:true// set errno as true})// The above code will return an object including three fields: errnoCode, errnoMessage, and the foreign function return value// { errnoCode: 22, errnoMessage: 'Invalid argument (os error 22)', value: -1 }

Memory Management

It's important to free the memory allocations during a single ffi call to prevent memory leaks.

What kinds of data memory are allocated in this?

  • Call parameters in the Rust environment which are allocated in the heap likeString
  • Return value which in the C environment which are allocated in the heap likechar*

By default,ffi-rs will free call parameters memory which are allocated in Rust.

But it will not free the return value from the C side since some C dynamic libraries will manage their memory automatically (when ffi-rs >= 1.0.79)

There are two ways to preventffi-rs from releasing memory:

  • SetfreeResultMemory: false when callingload method, the default value is false

If you set freeResultMemory to false,ffi-rs will not release the return result memory which was allocated in the C environment

  • UseDataType.External as paramsType or retType

If developers useDataType.External as paramsType or retType, please usefreePointer to release the memory of the pointer when this memory is no longer in use. reftest.ts

runInNewThread

ffi-rs supports running ffi tasks in a new thread without blocking the main thread, which is useful for CPU-intensive tasks.

To use this feature, you can pass therunInNewThread option to the load method:

consttestRunInNewThread=async()=>{// will return a promise but the task will run in a new threadload({library:"libsum",funcName:"sum",retType:DataType.I32,paramsType:[DataType.I32,DataType.I32],paramsValue:[1,2],runInNewThread:true,}).then(res=>{equal(res,3)})}

About

Implement ffi in Node.js by Rust and NAPI

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published
[8]ページ先頭
©2009-2025 Movatter.jp