== Interfacing with the Rubinius VM

Rubinius provides three different mechanisms for interfacing with the VM:
* Primitives
* Foregin Function Interface (FFI)
* Capi

=== Primitives

Primitives provide a means for Ruby code to drop-down to the virtual machine
level in order to manipulate the machine directly. Primitives provide the
ability to implement functionality on Ruby classes that is impractical or
impossible from pure Ruby, such as allocating memory for a new object.

Primitives are one-way; compile-time constructs, typically used to generate C
code that manipulates the state of the machine directly. In a sense, primitives
extend the instruction set of the virtual machine, but unlike the standard VM
byte codes, primitives are always executed as a method of an object, and are
defined and invoked from Ruby.

==== When to Use

Primitives should be used when the goal is to manipulate the Rubinius machine
only. If an external library function is involved, FFI should be used instead.

=== Foreign Function Interface (FFI)

FFI is a means for Ruby code to declare an external function that can then be
called like any other Ruby method. It uses GNU Lightning to generate native
machine code on-the-fly, in order to invoke an external library function at
run-time without any compilation. See {here}[http://rubini.us/pages/ffi] for
additional details on how to use FFI.

==== When to Use

FFI should be used whenever access to an external library is required from
Ruby.

=== Capi

Capi is the MRI-compatible C interface that allows external code to call
Ruby code running on Rubinius. It is provided so that external libraries
written to the MRI C-interface can work with Rubinius, with only a re-compile
required.

==== When to Use

Capi should be used when external code needs to interact with Ruby code.
Unlike the other two interfaces, Capi is an inbound interface to
Ruby/Rubinius.

