Permalink
Browse files

README++

  • Loading branch information...
1 parent 24ebf62 commit eaeba018d71cf05c43cc79a6a472d91f6f1f8255 @TooTallNate TooTallNate committed May 26, 2012
Showing with 26 additions and 40 deletions.
  1. +26 −40 README.md
View
@@ -8,7 +8,9 @@ It also simplifies the augmentation of node.js with C code as it takes care of h
**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
+
+Example
+-------
``` js
var ffi = require('ffi');
@@ -21,20 +23,24 @@ var current = ffi.Library(null, { 'atoi': [ 'int32', [ 'string' ] ] });
current.atoi('1234'); // 1234
```
-# REQUIREMENTS
+
+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.
+ * The current version is tested to run on node 0.6.x and 0.7.x.
-# NPM INSTALL
+
+Installation
+------------
``` bash
$ npm install ffi
```
-# SOURCE INSTALL / MANUAL COMPILATION
+Source Install / Manual Compilation
+-----------------------------------
To compile from source it's easiest to use
[`node-gyp`](https://github.com/TooTallNate/node-gyp):
@@ -51,45 +57,25 @@ $ 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
+
+Types
+-----
+
+The types that you specify in function declarations correspond to ref's types
+system. So see that 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.
-# Call Overhead
+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
+License
+-------
MIT License. See the `LICENSE` file.
-

0 comments on commit eaeba01

Please sign in to comment.