Previous: Virtual Machine Up: Tabela de Conteúdos Next: Custom Dispatch Logic

Instructions

The virtual machine instructions are contained in vm/instructions.def. The documentation below is generated by rakelib/vm.rake.

noop()

The classic no-op operator. It performs no actions and does not modify the stack.

BeforeAfter
......

See Also

push_nil()

The special object nil is pushed onto the stack.

BeforeAfter
...nil
...

push_true()

The special value true is pushed onto the stack.

BeforeAfter
...true
...

push_false()

The special object false is pushed onto the stack.

BeforeAfter
...false
...

push_int(number)

Pushes the value of the integer literal onto the stack.

BeforeAfter
...number
...

Notes

Certain common cases (i.e. -1, 0, 1, and 2) are optimised to avoid the decoding of the argument.

See Also

push_self()

The current self object is pushed onto the stack.

BeforeAfter
...self
...

set_literal(literal)

Used to set the value of a literal. The stack top is set to the literal indicated by the operand.

BeforeAfter
valuevalue
......

Notes

Unlike other literals such as strings and numbers, creating a Regexp literal (i.e. via the /regex/ syntax) is a two step process to create the literal slot for the Regexp, create a literal for the string between the '/' delimiters and create a new Regexp object passing it the string. Only then can the literal value be set, using the set_literal opcode.

push_literal(literal)

The value identified by the operand literal in the current state literals tuple is retrieved and placed onto the stack.

BeforeAfter
...literal
...

Notes

The literals tuple is part of the machine state, and holds all literal objects defined or used within a particular scope.

goto(location)

Unconditionally moves the instruction pointer to the position specified by location.

BeforeAfter
......

Notes

All goto instructions use absolute addressing. This is absolute movement rather than a relative one, so the operand must specify the ip starting from 0 to move to.

See Also

goto_if_false(location)

Remove the top value on the stack, and if nil or false, set the instruction pointer to the value specified by location.

BeforeAfter
value...
...

See Also

goto_if_true(location)

Remove the top value on the stack, and if not nil or false, set the instruction pointer to the value specified by location.

BeforeAfter
value...
...

See Also

ret()

Return a value to the direct caller

Pops the top value from the stack, and returns to the direct caller of the current invocation.

BeforeAfter
valuevalue
......

Notes

In a method, the return keyword uses this instruction. In a block though, return uses the raise_return instruction and next uses this instruction.

See Also

swap_stack()

Swaps the top two values on the stack, so that the second value becomes the first, and the first value becomes the second.

BeforeAfter
s0s1
s1s0
......

dup_top()

Read a value from the top of the stack and push it on the stack again without removing the original value.

BeforeAfter
s0s0
...s0
...

dup_many(count)

Duplicate multiple values on the stack

Read count values from the stack and push them onto the stack again in order without removing the original values.

BeforeAfter
value1 value1
value2 value2
... value1
value2
...

pop()

Removes the top value from the stack, discarding it.

BeforeAfter
value...
...

Notes

Pop is typically used when the return value of another opcode is not required.

pop_many(count)

Removes count values from the stack and discard them.

BeforeAfter
value1 ...
value2
...

rotate(count)

Reverses the order on the stack of the top count values.

BeforeAfter
obj1 obj3
obj2 obj2
obj3 obj1
... ...

move_down(positions)

The top value on the stack is moved down by the specified number of positions, with all values above that position shuffling up by one.

BeforeAfter
obj1 obj2
obj2 ...
... objn
objn obj1

set_local(local)

Read the top of the stack and set the local variable identified by operand local to it. The stack is not modified by this instruction.

BeforeAfter
valuevalue
......

See Also

push_local(local)

Retrieves the current value of the local variable referenced by operand local and push it onto the stack.

BeforeAfter
...value
...

See Also

push_local_depth(depth, index)

Pushes the value of a local from an enclosing scope onto the stack

Retrieves the value of a local variable. Operand depth indicates how many upward enclosing scopes to walk up and then operand index indicates which local in that context to read. The value is then pushed on the stack.

BeforeAfter
...value
...

Example

 k = 0
 foo.each do |i|
   bar.each do |j|
     # i is a local variable from enclosing scope at depth 1
     # k is a local variable from enclosing scope at depth 2
     i = i + j + k
   end
 end

See Also

set_local_depth(depth, index)

Updates the value of a local variable contained in an enclosing scope

Read a value from the top of the stack and use it to update a local variable in an enclosing scope. The depth and index operands identify the specific local the same as in push_local_depth.

BeforeAfter
valuevalue
......

Example

 foo.each do |i|
   bar.each do |j|
     i = i + j  # i is a local variable from enclosing scope at depth 1
   end
 end

See Also

passed_arg(index)

Checks if the argument specified by the operand index was passed to the current invocation. If so, push true, otherwise false.

BeforeAfter
...boolean
...

Notes

Arguments are specified via a zero-index, so the first argument is 0.

push_current_exception()

Pushes the current exception onto the stack, so that it can be used for some purpose, such as checking the exception type, setting an exception variable in a rescue clause, etc.

BeforeAfter
...exception
...

Example

 begin
   foo = BAR        # BAR is not defined
 rescue NameError   # push_exception used to check type of exception (via ===)
   puts "No BAR"
 end

See Also

clear_exception()

Clears any exceptions from the current thread.

BeforeAfter
......

push_exception_state()

Package up the current exception state into an object and push it. This is used to preserve the exception state around code that might mutate it. For instance, when handling an ensure while an exception is being raised

BeforeAfter
...exc_state
...

restore_exception_state()

Pops a value off the stack and set the threads exception state from it. This instruction is only to be used with a value pushed on the stack by the push_exception_state instruction.

BeforeAfter
exception...
...

See Also

raise_exc()

Raises an exception

Pops a value off the stack and make it the current exception. If the value is not an instance of Exception, a TypeError is raised.

BeforeAfter
value...
...

setup_unwind(ip, type)

Register an unwind handler

Registers what to happen when an exception wants to unwind through the current invocation. Operand ip specifies where to set the instruction pointer if used. Operand type is either 0 for if the value should be used in rescue style (not run when unwinding because of a return caused by raise_return) or 1 for ensure style (always used). The registrations are nested within the current invocation and are automatically removed from the registry when they are used. The pop_unwind instruction can be used to remove an unused registration.

BeforeAfter
......

Notes

The registration also contains the value of the stack depth when created. If the registration is used, then the stack depth is restored to the value contained in the registration

See Also

pop_unwind()

Remove the next unused unwind registration from the current invocation. This instruction is paired with setup_unwind to remove registrations when control exits a section of code that registered a handler but didn't use it. For example, exiting a begin that had a rescue expression.

BeforeAfter
......

See Also

raise_return()

Cause the toplevel enclosing scope to return

Only used in a block, pop a value from the stack and raise a special internal exception and begin unwinding the stack. The toplevel method scope will rescue the exception and return the value.

BeforeAfter
valuevalue
......

See Also

ensure_return()

Return from a scope but run ensures first

A one use instruction, used only in a method toplevel within a begin that has an ensure. Use the same internal exception as raise_return which will coax the ensure registration to run.

BeforeAfter
valuevalue
......

See Also

raise_break()

Cause the method that yielded the current block to return. Used to implement the break keyword in a block.

BeforeAfter
valuevalue
......

reraise()

Continue unwinding the stack with the current exception. Verify that there is a current exception, then begin the unwinding process again.

BeforeAfter
......

make_array(count)

Create an array and populate with values on the stack

Creates a new array, populating its contents by remove the number of values specified by operand count and putting them into the array in the order they were on the stack. The resulting array is pushed onto the stack.

BeforeAfter
valueN [value1, value2, ..., valueN]
... ...
value2
value1
...

cast_array()

Removes the object on the top of the stack, and:

  1. . If the input is a tuple, a new array object is created based on the tuple data.
  2. . If the input is an array, it is unmodified.
  3. . If in 1.9 mode and the input is nil, an empty Array is returned

If the input is any other type, call Rubinius::Type.coerce_to_array(value). If the return value of the method call is an Array, make it the result. Otherwise make the result an 1 element Array contain the original value.

The resulting array is then pushed back onto the stack.

BeforeAfter
valuearray
......

shift_array()

Pops an array off the top of the stack. If the array is empty, it is pushed back onto the stack, followed by nil.

Otherwise, the array is shifted, then pushed back onto the stack, followed by the object that was shifted from the front of the array.

BeforeAfter
[value1, value2, ..., valueN] value1
... [value2, ..., valueN]
...

set_ivar(literal)

Pops a value off the stack, and uses it to set the value of the instance variable identifies by the literal specified by operand literal. The value popped off the stack is then pushed back on again.

BeforeAfter
valuevalue
......

push_ivar(literal)

Pushes the instance variable identified by literal onto the stack.

BeforeAfter
...value
...

push_const(literal)

Locates the constant indicated by the operand literal from the current context, and pushes it onto the stack. If the constant cannot be found in the current context, nothing is pushed onto the stack, and a NameError exception is raised.

BeforeAfter
...constant
...

Example

 engine = RUBY_ENGINE # RUBY_ENGINE is a constant defined by Rubinius

set_const(literal)

Pops an object off the stack, and uses value to set a constant named by the literal. The value is pushed back onto the stack.

BeforeAfter
valuevalue
......

set_const_at(literal)

Pop a value from the literals table specified by the operand literal and use it as the value of a constant named inside a Module object popped from the stack. The value is pushed back on the stack.

BeforeAfter
value value
module ...
...

find_const(literal)

Pops module off the stack, and searches within its namespace for the constant named by the literal specified by the operand literal. If found, it is pushed onto the stack; otherwise, nothing is pushed onto the stack, and a NameError exception is raised.

BeforeAfter
moduleconstant
......

Example

 str = "abc"
 enum = Enumerable::Enumerator(str, :each_byte)

push_cpath_top()

Pushes the top-level global object that represents the top-level namespace for constants. Used to find constants relative to the toplevel. In Ruby, this is the class Object.

BeforeAfter
...constant
...

push_const_fast(literal)

Pushes a constant onto the stack. Caches the lookup to provide faster future lookup. This instruction is normally emitted only by the Generator.

BeforeAfter
...constant
...

Example

 engine = RUBY_ENGINE # RUBY_ENGINE is a constant defined by Rubinius

See Also

find_const_fast(literal)

Pushes a constant onto the stack scoped under the module on the top of the stack. Caches the lookup to provide faster future lookup. This instruction is normally emitted only by the Generator.

BeforeAfter
moduleconstant
......

Example

 str = "abc"
 enum = Enumerable::Enumerator(str, :each_byte)

See Also

set_call_flags(flags)

The call flags on the current execution context are set to the opcode argument flags.

BeforeAfter
......

Notes

Currently this only has one use, which is that send_stack_with_splat checks if flags is set to CALL_FLAG_CONCAT which indicates that the splat represents arguments at the beginning rather than the end.

allow_private()

Indicate that the next send is allowed to see private methods.

BeforeAfter
......

send_method(literal)

Pops a receiver object off the top of the stack and sends it the message specified by the operand literal with zero arguments.

When the method returns, the return value is pushed on the stack.

BeforeAfter
receivervalue
......

Notes

This form of send is for methods that take no arguments.

See Also

send_stack(literal, count)

Sends a message with arguments on the stack

Pops the receiver of the message off the stack and sends the message specified by the operand literal with count arguments. The arguments are removed from the stack also.

When the method returns, the return value is pushed on the stack.

BeforeAfter
argN value
... ...
arg2
arg1
receiver

Notes

This opcode does not pass a block to the receiver; see send_stack_with_block for the equivalent op code used when a block is to be passed.

See Also

send_stack_with_block(literal, count)

Sends a message with arguments and a block on the stack

Pops the receiver of the message off the stack and sends the message specified by the operand literal with count arguments. The arguments are removed from the stack also. A value that represents the block to pass on is popped off the stack after the normal arguments.

When the method returns, the return value will be on top of the stack.

BeforeAfter
block retval
argN ...
...
arg2
arg1
receiver

Notes

This opcode passes a block to the receiver; see send_stack for the equivalent op code used when no block is to be passed.

See Also

send_stack_with_splat(literal, count)

BeforeAfter
blockvalue
array...
receiver
...

send_super_stack_with_block(literal, count)

Call a method on the superclass with a block

The same as send_stack_with_block, but receiver is the current self instead of being read from the stack, and the method to call is looked up starting with the receiver superclass.

BeforeAfter
block retval
argN ...
...
arg2
arg1

send_super_stack_with_splat(literal, count)

Call a method on the superclass, passing args plus a block.

The same as send_stack_with_block, but receiver is the current self instead of being read from the stack, and the method to call is looked up starting with the receiver superclass.

BeforeAfter
block retval
argN ...
...
arg2
arg1

push_block()

Pushes the current block onto the stack. The value is not wrapped in a Proc if it is a BlockEnvironment.

BeforeAfter
...block
...

See Also

passed_blockarg(count)

Check if exactly count arguments were passed to the current invocation.

BeforeAfter
...boolean
...

Notes

This instruction is deprecated and no longer used.

create_block(literal)

Read a CompiledCode specified by the operand +literal+ and create a BlockEnvironment. Push the new BlockEnvironment object on the stack.

BeforeAfter
...block
...

cast_for_single_block_arg()

Converts the value on the top of the stack into an argument for a block taking one argument.

The value on the top of the stack is popped, and:

If it has no fields, the result is nil.

If the value contains a single field, the result is the value in the first field.

Otherwise, package up all the arguments in an Array as the result.

The result is then pushed onto the stack.

BeforeAfter
...argument
...

Notes

This is a single use instruction, only used to simplify how to handle a block that accepts one argument.

cast_for_multi_block_arg()

Converts a block argument single-valued tuple into multiple arguments if the arg is an array.

If the Proc invoked from was in lambda mode, and one argument is passed: * and it's an Array, push it. * and it responds to #to_ary, try and convert it and push it. * otherwise wrap it in a one element Array and push it.

Otherwise: Package up the arguments into an Array and push it onto the stack.

BeforeAfter
value1 array[value1,..] | value1
value2 ...
...

Example

 [[1,2,3]].each do |i,j,k|
   # do something
 end

Notes

This is a single use instruction, only used to simplify how to handle a block that accepts 2 or more arguments. The semantics for this instruction change depending on if the current block invocation is from a Proc with lambda semantics or not.

cast_for_splat_block_arg()

Take all arguments passed to the current invocation and package them into an Array, which is then pushed on the stack.

BeforeAfter
...arguments
...

yield_stack(count)

Invoke the current block, passing count arguments to it.

BeforeAfter
argN value
... ...
arg2
arg1
...

See Also

yield_splat(count)

Invoke the current block, passing count arguments to it in addition to the values in the Array array.

BeforeAfter
array value
argN ...
...
arg2
arg1
...

See Also

string_append()

Pops two strings off the stack, appends the second to the first, and then pushes the combined string back onto the stack.

BeforeAfter
prefixstring
suffix...
...

Notes

The original string is modified by the append.

string_build(count)

Build a new string using many substrings

Remove count elements from the stack and interpret each as a String. Build a new string which is all the removed elements concatenated together in the order they were on the stack.

Push the resulting string.

BeforeAfter
stringN string1string2..stringN
... ...
string2
string1

string_dup()

Consume the string on the stack, replacing it with a duplicate. Mutating operations on the original string will not affect the duplicate, and vice-versa.

BeforeAfter
stringstring
......

push_scope()

Pushes the current ConstantScope object on the stack. Many operations are defered to the current scope. This operation retrieves the current scope so methods can be called on it.

BeforeAfter
...scope
...

add_scope()

Create a new ConstantScope object for the given Module on the stack. This scope is chained off the current scope of the method.

This also sets the scope of the current CompiledCode to the new ConstantScope.

BeforeAfter
module...
...

push_variables()

Push the VariableScope for the current method/block invocation on the stack.

BeforeAfter
...scope
...

check_interrupts()

Perform required occasional checks that must be done. This instruction is used by loops to allow them to be interrupted externally, and thus also cause the current method to heat up.

BeforeAfter
......

yield_debugger()

Pauses virtual machine execution and yields control to the debugger on the debug channel. If no debugger is registered, an error is raised.

BeforeAfter
......

Notes

This instruction is deprecated and should not be used.

is_nil()

Pop the value from the stack, and push true or false depending on whether the consumed value was the special value nil.

BeforeAfter
valueboolean
......

check_serial(literal, serial)

Checks if the specified method serial number matches an expected value.

Pops the receiver object from the stack and checks if it responds to the message specified by the operand literal and the target method has serial number serial. If so, push true, else push false.

BeforeAfter
receiverboolean
......

Notes

This opcode is typically used to determine at runtime whether an optimisation can be performed. At compile time, two code paths are generated: a slow, but guaranteed correct path, and a fast path that uses certain optimisations. The serial number check is then performed at runtime to determine which code path is executed.

For example, a method such as Fixnum#times can be optimised at compile time, but we can't know until runtime whether or not the Fixnum#times method has been overridden. The serial number check is used to determine each time the code is executed, whether or not the standard Fixnum#times has been overridden. It leverages the serial number field on a CompiledCode, is initialised to either 0 (for kernel land methods) or 1 (for user land methods).

check_serial_private(literal, serial)

Checks if the specified method's serial number matches an expected value. Considers private methods too.

BeforeAfter
receiverboolean
......

See Also

push_my_field(index)

Pushes the value of the specified field in the current object onto the stack.

BeforeAfter
...value
...

Notes

Fields are similar to instance variables, but have dedicated storage allocated. They are primarily used on core or bootstrap classes. This instruction should not be used directly. The VM will specialize push_ivar instructions into this.

store_my_field(index)

Stores the value at the top of the stack into the field specified by index on self.

The stack is left unmodified.

BeforeAfter
valuevalue
......

Notes

This instruction should not be used directly. The VM will specialize push_ivar instructions into this.

kind_of()

Evaluate if object is an instance of class or of an ancestor of class. If so, push true, else push false.

The equivalent of object.kind_of?(klass) in Ruby.

BeforeAfter
objectboolean
class...
...

See Also

instance_of()

Evaluate if object is an instance of class. If so, push true, else push false.

The equivalent of object.instance_of?(klass) in Ruby.

BeforeAfter
objectboolean
class...
...

See Also

meta_push_neg_1()

Push -1 (negative 1) onto the stack.

BeforeAfter
...value
...

Notes

This is an optimisation applied by the compiler.

meta_push_0()

Push 0 (zero) onto the stack.

BeforeAfter
...value
...

Notes

This is an optimisation applied by the compiler.

meta_push_1()

Push 1 (one) onto the stack.

BeforeAfter
...value
...

Notes

This is an optimisation applied by the compiler.

meta_push_2()

Push 2 (two) onto the stack.

BeforeAfter
...value
...

Notes

This is an optimisation applied by the compiler.

meta_send_op_plus(literal)

Implementation of #+ optimised for Fixnum.

Pops value1 and value2 off the stack, and pushes the sum (value1 + value2). If both values are Fixnums, the addition is done directly via the fixnum_add primitive. Otherwise, the #+ method is called on value1, passing value2 as the argument.

BeforeAfter
value1sum
value2...
...

meta_send_op_minus(literal)

Implementation of #- optimised for Fixnum.

Pops value1 and value2 off the stack, and pushes the difference (value1 - value2). If both values are Fixnums, the subtraction is done directly via the fixnum_sub primitive. Otherwise, the #- method is called on value1, passing value2 as the argument.

BeforeAfter
value1difference
value2...
...

meta_send_op_equal(literal)

Implementation of #== optimised for Fixnum and Symbol.

Pops value1 and value2 off the stack and pushes the logical result of (value1 == value2). If value1 and value2 are both Fixnums or both Symbols, the comparison is done directly. Otherwise, the #== method is called on value1, passing value2 as the argument.

BeforeAfter
value1boolean
value2...
...

meta_send_op_lt(literal)

Implementation of #< optimised for Fixnum.

Pops value1 and value2 off the stack, and pushes the logical result of (value1 < value2). If value1 and value2 are both Fixnums, the comparison is done directly. Otherwise, the #< method is called on value1, passing value2 as the argument.

BeforeAfter
value1boolean
value2...
...

meta_send_op_gt(literal)

Implementation of #> optimised for Fixnum.

Pops value1 and value2 off the stack, and pushes the logical result of (value1 > value2). If value1 and value2 are both Fixnums, the comparison is done directly. Otherwise, the #> method is called on value1, passing value2 as the argument.

BeforeAfter
value1boolean
value2...
...

meta_send_op_tequal(literal)

Implementation of #=== (triple equal) optimised for Fixnum and Symbol.

Pops value1 and value2 off the stack, and pushes the logical result of (value1 === value2). If value1 and value2 are both Fixnums or both Symbols, the comparison is done directly. Otherwise, the #=== method is called on value1, passing value2 as the argument.

BeforeAfter
value1boolean
value2...
...

Notes

Exactly like equal, except calls #=== if it can't handle it directly.

meta_send_call(literal, count)

Simplified call instruction used for non-dynamic yield calls and for simple calls with static arguments.

BeforeAfter
argN retval
...
arg1
receiver

push_my_offset(index)

Pushes a value read directly from within the body of an object.

BeforeAfter
...offset
...

Notes

This instruction must never be used directly. The VM will specialize push_my_field instructions into this.

See Also

zsuper(literal)

Call a superclass method on the current, passing the arguments passed to the current invocation.

BeforeAfter
argN value
... ...
arg2
arg1
...

Notes

This is a specialization of send_super_with_stack that is necessary for Ruby semantics regarding how to read the original arguments.

See Also

push_block_arg()

Push the block passed as an argument to the current invocation. This differs from push_block in that in is not the block for the current scope because of how the current block is seen within an existing block.

BeforeAfter
...block
...

See Also

push_undef()

Push the special undefined value on the stack.

BeforeAfter
...value
...

push_stack_local(which)

Push the stack local identified by operand which.

BeforeAfter
...value
...

Notes

Stack locals differ from normal locals in that they are not viewable by closures.

set_stack_local(which)

Set the stack local identified by operand which using the value on the top of the stack.

BeforeAfter
valuevalue
......

Notes

Stack locals differ from normal locals in that they are not viewable by closures.

push_has_block()

Push true or false based on whether there is a current block.

BeforeAfter
...value
...

Notes

Used to implement block_given? without having to directly expose the block object itself. This simplifies JIT inlining.

push_proc()

Wrap the current block in a Proc and push it onto the stack. If there is no current block, push nil.

BeforeAfter
...value
...

Notes

Used to implement &block in a method signature.

See Also

check_frozen()

Check if the value on the top of the stack is frozen. If so, raise a TypeError indicating so.

BeforeAfter
valuevalue
......

Notes

An optimization to deal with check for frozen.

cast_multi_value()

Convert a value into an Array

Pop value. If it is an Array, push it back on the stack. Otherwise, attempt to convert it to an Array using #to_ary and push the result. If the value can not be converted to an array, it is wrapped in a one element Array.

BeforeAfter
valuearray
......

invoke_primitive(literal, count)

Directly invoke a primitive by name.

Pop count values off the stack and pass them directly to the primitive operation named by the operand literal.

BeforeAfter
argN value
... ...
arg2
arg1

push_rubinius()

Pushes the top-level global Rubinius constant onto the stack. Generally this is done to call a utility method.

BeforeAfter
...constant
...

call_custom(literal, count)

Invoke a method via the call custom protocol.

Pop the receiver and count values off the stack and begin the call custom invocation protocol with them as arguments.

BeforeAfter
argN value
... ...
arg2
arg1
receiver

meta_to_s(literal)

Pop a value off the stack and if it's not a String, call a method indicated by literal on it. Push the resulting object back on the stack.

BeforeAfter
objectstring
......

Notes

Normally literal is :to_s, but this instruction leaves it up to the user to indicate for flexibility.

push_type()

Pushes the distinguished module Rubinius::Type onto the stack.

BeforeAfter
...constant
...

push_mirror()

Pushes the distinguished class Rubinius::Mirror onto the stack.

BeforeAfter
...constant
...
Previous: Virtual Machine Up: Tabela de Conteúdos Next: Custom Dispatch Logic

Tweet at @rubinius on Twitter or email community@rubini.us. Please report Rubinius issues to our issue tracker.