Permalink
Browse files

README++

  • Loading branch information...
1 parent 6596913 commit 0b04218fe767cca5d2a8b1b74ab034140be45d68 @TooTallNate TooTallNate committed Jun 27, 2012
Showing with 22 additions and 4 deletions.
  1. +22 −4 README.md
View
@@ -2,6 +2,9 @@ node-ffi
========
### Node.js Foreign Function Interface [![Build Status](https://secure.travis-ci.org/rbranson/node-ffi.png)](http://travis-ci.org/rbranson/node-ffi)
+#### Attention node-ffi users! v1.0 has been released! See the [API changes
+page][v1apichanges].
+
`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.
@@ -27,13 +30,15 @@ var current = ffi.Library(null, {
current.atoi('1234'); // 1234
```
+For a more detailed introduction, see the [node-ffi tutorial page][tutorial].
+
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.x and v0.7.x.
+ * The current version is tested to run on node v0.6, v0.7, and v0.8.
Installation
@@ -70,20 +75,33 @@ Types
-----
The types that you specify in function declarations correspond to ref's types
-system. So [see that](https://github.com/TooTallNate/ref#built-in-types) for a reference if you are unfamiliar.
+system. So [see its docs][ref-types] 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 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.
+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.
+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.
+
+[v1apichanges]: https://github.com/rbranson/node-ffi/wiki/API-changes-from-v0.x-to-v1.x
+[tutorial]: https://github.com/rbranson/node-ffi/wiki/Node-FFI-Tutorial
+[ref-types]: https://github.com/TooTallNate/ref#built-in-types

0 comments on commit 0b04218

Please sign in to comment.