nanffi v0.0.2
Native Abstractions for Node.js
nanffi 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.
WARNING: nanffi 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
const nanffi = require('nanffi');
const libm = nanffi.ffi('libm');
libm.ceil(1.5); // 2
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 nanffi
Usage example
Source Install / Manual Compilation
To compile from source it's easiest to use node-gyp
:
npm install -g node-gyp
Now you can compile nanffi:
npm run configure
npm run build-gyp
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 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.