Need help with node-ffi?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

node-ffi
3.6K Stars 403 Forks MIT License 838 Commits 221 Opened issues

Description

Node.js Foreign Function Interface

Services available

!
?

Need anything else?

Contributors list

No Data

node-ffi

Node.js Foreign Function Interface

Build Status Build Status

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('ffi');

var libm = 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 = ffi.Library(null, { 'atoi': [ 'int', [ 'string' ] ] }); current.atoi('1234'); // 1234

For a more detailed introduction, see the node-ffi tutorial page.

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 v0.6, v0.8, v0.9 and v0.10.

Installation

Make sure you've installed all the necessary build tools for your platform, then invoke:

$ npm install ffi

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/node-ffi/node-ffi.git
$ cd node-ffi
$ node-gyp rebuild

Types

The types that you specify in function declarations correspond to ref's types system. So see its docs for a reference if you are unfamiliar.

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 (FP) 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 orders of magnitude 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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.