A CompiledMethod represents the compiled source code for a Ruby method (or top-level script, i.e. Ruby code that is not part of a method body). As such, a CompiledMethod contains:
- an InstructionSequence instance containing the compiled bytecode for the method source
- the number and names of any local variables used in the method
- a reference to the static (i.e. lexical) scope of the method
- the path to the source .rb file from which the code was compiled
- a mapping from bytecode instruction addresses to the corresponding source line in the .rb file from which the code was compiled
- a table of exception handlers, identifying the bytecode ranges that are surrounded by a rescue clause, plus the address of the handler code for that code block
A CompiledMethod is the main executable unit in a Rubinius program. It is the output created by the Rubinius compiler that is then passed to Shotgun for execution and/or persisted to disk. CompiledMethod instances can be obtained from any method definition using the #compiled_method accessor on a Method or UnboundMethod object.
CompiledMethod objects may also be nested; i.e. a CompiledMethod can contain other CompiledMethod object references in its literals tuple.
FFI is Rubinius’s Foreign Function Interface, a simple DSL provided by Rubinius that allows Ruby code to define methods that are backed by native code in external libraries. An example of a Rubinius function that uses FFI is the getcwd function from Platform::POSIX, which is defined as follows:
attach_function 'getcwd', [:string, :size_t], :string
The literals tuple in a CompiledMethod is used to store objects that are used as arguments to opcodes, but which cannot be represented directly in the bytecode as an integer. Examples of objects that might be found in the literals tuple are:
- String (“foo”), Symbol (:bar) and Regexp (/baz/) constants
- Floats and Bignums
- Constants, Classes, and Modules
- CompiledMethod and SendSite objects
MatzRuby and MRI are terms often used to identify the original C Ruby interpreter written by Yukihiro “Matz” Matsumoto. Since there is no offical Ruby spec, MatzRuby is the benchmark used to judge a Ruby implementation’s compatibility with Ruby the language.
Primitives are used in Rubinius to implement a Ruby method by dropping down to C code. They are used for methods that cannot practically be implemented directly in Ruby, such as for the basic math operators, for methods that need to interact with the OS, or for methods where performance is paramount.
Methods that are implemented as primitives must include the statement Ruby.primitive :primitive_name as the first statement in the method body. Primitive methods may optionally also contain Ruby code following the primitive call; this code will be executed if the primitive fails for any reason. This can be useful for a number of reasons:
- Error reporting can make use of Ruby constructs and semantics
- The primitive can be used for an optimised narrow-case fast path, but then drop back to a slower catch-all case in Ruby. This is typically used for the Fixnum math operators, where the fastpath primitive is used if the argument to the method is also a Fixnum, but the slow path is used when it is not.
Generally, methods that use primitives will be found in kernel/bootstrap, since it is a goal that kernel/core should be as close to pure Ruby as possible.
Subtend is Rubinius’s MatzRuby compatible C interface. It exists to enable C extensions written for MatzRuby to work under Rubinius.
The Tuple is a basic building block used by Rubinius as the backing store for collection classes such as Array and Hash. A Tuple is simply a fixe-size array; it cannot be resized, and all storage is contiguous.