== Rubinius <==> MRI

Rubinius is roughly equivalent to MRI (Matz's Ruby Implementation, the original
Ruby implementation) 1.8.6, but contains some additional useful functionality,
and also removes some less common and problematic behaviours. This document
provides a summary of both the additions and subtractions from MRI 1.8.6.

*Note:* This document is not a complete list! Rubinius is still incomplete, and
changing rapidly. If you find a difference and have confirmed it is
intentional, please help make this document more complete by updating it! You
can find the source text at doc/vm/rubinius_vs_mri.tx in your Rubinius
directory.

=== Rubinius Extensions to MRI

Rubinius extends Ruby in some very useful ways. Some of these additions are the
inclusion of commonly added methods  and libraries possible with any Ruby
implementation, while others are only possible on Rubinius due to an active
policy of making everything possible first-class, i.e. opening up the Ruby
implementation to programmatic reflection/introspection, and in some cases,
manipulation.

Following is a list of useful additions included in Rubinius as standard, but
which are possible in MRI and other Ruby implementations:

* Object#metaclass (shorthand for <tt>class << self</tt>)

Following is a list of additions provided by Rubinius that are not *directly*
portable to MRI:
* {Ruby Compiled (.rbc) files}[rbc_files.html]
* {Ruby Archives (.rba)}[http://blog.fallingsnow.net/2007/01/19/archiving-loading-now-in-trunk/]
* {FFI}[vm_interfaces.html]
* Tuple: This is a simple fixed size data structure, used internally by classes such as Array and Hash.
* {Concurrency}[concurrency.html]
  * {Task}[http://blog.fallingsnow.net/2007/04/05/task-class-in-svn/]
  * Thread
  * Actor
  * Channel
* Metaprogramming:
  [MetaClass]
    Object meta-classes are instances of +MetaClass+, which is a sub-class of
    +Class+.
* Rubinius Runtime Introspection:
  [Globals] Object containing a hash of all global variables.
  [CompiledMethod]
    A +CompiledMethod+ object is used to represent each compiled method object
    in Rubinius. It holds much of the details of a method implementation,
    including the local variables and literals used in the method, the
    +InstructionSequence+ containing the bytecode of the method implementation,
    etc.
  [MethodContext]
    Object created to store all information about a running method.
  [BlockContext]
    Object created to store all information about a running block.
  [BlockEnvironment]
    Object describing the environment a block was created in, used to create a
    BlockContext.
  [Backtrace]
    Backtraces contain stack frame objects and have a colorized
    #awesome_backtrace method.
  [InstructionSequence]
    The bytecode instructions for how to operform the operations of a
    CompiledMethod.
  [File#to_sexp, String#to_sexp]
    Converts the Ruby code in the file or string to an S-expression (sexp).

=== Rubinius Incompatibilities

Rubinius also removes some functionality present in MRI. Generally this is due
to the MRI behavior being rarely used and/or having a substantial negative
impact on performance.

Following is a list of known incompatibilities:
* Rubinius does not support freezing objects. +#freeze+ is defined so that code
  that uses it will run, but is essentially a no-op; +#frozen?+ always returns
  false.
* Multiple assignment returns *true* rather than an array of the rhs args, i.e.
  in MRI a,b = 1,2 returns [1,2], but this is almost never used. Rubinius
  returns *true* and avoids the penalty of creating an array that is not used.
* Multiple assignment evaluates the RHS in right-to-left order, rather than
  left-to-right. This will only be noticeable if expressions on the RHS are
  dependent on one another, which is rarely the case.

*Note:* This list is *not* final, and some of the current incompatibilities
listed above are likely to be resolved as the project progresses.

