node-ffi v0.5.7
node-ffi
Node.js Foreign Function Interface
node-ffi
is a Node.js addon for loading and calling dynamic libraries using pure JavaScript. It can be used to create bindings to native libraries without writing any C++ code.
It also simplifies the augmentation of node.js with C code as it takes care of handling the translation of types across JavaScript and C, which can add reams of boilerplate code to your otherwise simple C. See the example/factorial
for an example of this use case.
WARNING: node-ffi assumes you know what you're doing. You can pretty easily create situations where you will segfault the interpreter and unless you've got C debugger skills, you probably won't know what's going on.
EXAMPLE
var ffi = require("node-ffi");
var libm = new ffi.Library("libm", { "ceil": [ "double", [ "double" ] ] });
libm.ceil(1.5); // 2
// You can also access just functions in the current process by passing a null
var current = new ffi.Library(null, { "atoi": [ "int32", [ "string" ] ] });
current.atoi("1234"); // 1234
REQUIREMENTS
- Linux, OS X, Windows, or Solaris.
libffi
comes bundled with node-ffi, it does not need to be installed on your system.- The current version is tested to run on node 0.6.x.
- If you need node 0.4.x support, use the
0.4
branch of node-ffi.
NPM INSTALL
$ npm install node-ffi
Most popular operating systems have a pre-compiled binary that comes along with node-ffi, so most of the time you will not need to compile anything! (Unless of course you want to, then see below).
SOURCE INSTALL / MANUAL COMPILATION
To compile from source it's easiest to use
node-gyp
:
$ npm install -g node-gyp
Now you can compile node-ffi
:
$ git clone git://github.com/rbranson/node-ffi.git
$ cd node-ffi
$ node-gyp configure build
TYPES
int8 Signed 8-bit Integer
uint8 Unsigned 8-bit Integer
int16 Signed 16-bit Integer
uint16 Unsigned 16-bit Integer
int32 Signed 32-bit Integer
uint32 Unsigned 32-bit Integer
int64 Signed 64-bit Integer
uint64 Unsigned 64-bit Integer
float Single Precision Floating Point Number (float)
double Double Precision Floating Point Number (double)
pointer Pointer Type
string Null-Terminated String (char *)
In addition to the basic types, there are type aliases for common C types.
byte unsigned char
char char
uchar unsigned char
short short
ushort unsigned short
int int
uint unsigned int
long long
ulong unsigned long
longlong long
ulonglong unsigned long long
size_t platform-dependent, usually pointer size
V8 and 64-bit Types
Internally, V8 stores integers that will fit into a 32-bit space in a 32-bit integer, and those that fall outside of this get put into double-precision floating point numbers. This is problematic because FP numbers are imprecise. To get around this, the methods in node-ffi that deal with 64-bit integers return strings and can accept strings as parameters.
Call Overhead
There is non-trivial overhead associated with FFI calls. Comparing a hard-coded binding version of strtoul()
to an FFI version of strtoul()
shows that the native hard-coded binding is 5x faster. So don't just use the C version of a function just because it's faster. There's a significant cost in FFI calls, so make them worth it.
LICENSE
MIT License. See the LICENSE
file.
11 years ago
11 years ago
12 years ago
12 years ago
12 years ago
12 years ago
12 years ago
12 years ago
12 years ago
13 years ago
13 years ago
13 years ago
13 years ago
13 years ago
13 years ago
13 years ago
13 years ago
13 years ago
13 years ago
13 years ago