Class: RubyVM::InstructionSequence
Overview
The InstructionSequence class represents a compiled sequence of instructions for the Ruby Virtual Machine.
With it, you can get a handle to the instructions that make up a method or a proc, compile strings of Ruby code down to VM instructions, and disassemble instruction sequences to strings for easy inspection. It is mostly useful if you want to learn how the Ruby VM works, but it also lets you control various settings for the Ruby iseq compiler.
You can find the source for the VM instructions in insns.def
in the Ruby source.
The instruction sequence results will almost certainly change as Ruby changes, so example output in this documentation may be different from what you see.
Class Attribute Summary
-
.compile_option ⇒ options
rw
Returns a hash of default options used by the Ruby iseq compiler.
-
.compile_option=(options)
rw
Sets the default values for various optimizations in the Ruby iseq compiler.
Class Method Summary
-
.compile(source[, file[, path[, line[, options]]]]) ⇒ iseq
Alias for .new.
-
.compile_file(file[, options]) ⇒ iseq
Takes
file
, a ::String with the location of a Ruby source file, reads, parses and compiles the file, and returnsiseq
, the compiledInstructionSequence
with source location metadata set. - .disasm(body) ⇒ String (also: .disassemble)
-
.disassemble(body) ⇒ String
Alias for .disasm.
-
.load_from_binary(binary) ⇒ iseq
Load an iseq object from binary format ::String object created by #to_binary.
-
.load_from_binary_extra_data(binary) ⇒ String
Load extra data embed into binary format ::String object.
-
.new(source[, file[, path[, line[, options]]]]) ⇒ iseq
(also: .compile)
constructor
Takes
source
, a ::String of Ruby code and compiles it to anInstructionSequence
. -
.of(body)
Returns the instruction sequence containing the given proc or method.
Instance Method Summary
-
#absolute_path
Returns the absolute path of this instruction sequence.
-
#base_label
Returns the base label of this instruction sequence.
-
#disasm ⇒ String
(also: #disassemble)
Returns the instruction sequence as a ::String in human readable form.
-
#disassemble ⇒ String
Alias for #disasm.
-
#eval ⇒ Object
Evaluates the instruction sequence and returns the result.
-
#first_lineno
Returns the number of the first source line where the instruction sequence was loaded from.
- #inspect
-
#label
Returns the label of this instruction sequence.
-
#line_trace_all
Experimental MRI specific feature, only available as C level api..
-
#line_trace_specify(pos, set)
Experimental MRI specific feature, only available as C level api..
-
#path
Returns the path of this instruction sequence.
-
#to_a ⇒ Array
Returns an ::Array with 14 elements representing the instruction sequence with the following data:
-
#to_binary(extra_data = nil) ⇒ binary str
Returns serialized iseq binary format data as a ::String object.
- #marshal_dump private
- #marshal_load private
Constructor Details
.compile(source[, file[, path[, line[, options]]]]) ⇒ iseq
.new(source[, file[, path[, line[, options]]]]) ⇒ iseq
Also known as: .compile
iseq
.new(source[, file[, path[, line[, options]]]]) ⇒ iseq
Takes source
, a ::String of Ruby code and compiles it to an InstructionSequence
.
Optionally takes file
, #path, and line
which describe the filename, absolute path and first line number of the ruby code in source
which are metadata attached to the returned iseq
.
options
, which can be true
, false
or a ::Hash, is used to modify the default behavior of the Ruby iseq compiler.
For details regarding valid compile options see .compile_option=.
RubyVM::InstructionSequence.compile("a = 1 + 2")
#=> <RubyVM::InstructionSequence:<compiled>@<compiled>>
Class Attribute Details
.compile_option ⇒ options
(rw)
Returns a hash of default options used by the Ruby iseq compiler.
For details, see .compile_option=.
.compile_option=(options) (rw)
Sets the default values for various optimizations in the Ruby iseq compiler.
Possible values for options
include true
, which enables all options, false
which disables all options, and nil
which leaves all options unchanged.
You can also pass a ::Hash of options
that you want to change, any options not present in the hash will be left unchanged.
Possible option names (which are keys in options
) which can be set to true
or false
include:
-
:inline_const_cache
-
:instructions_unification
-
:operands_unification
-
:peephole_optimization
-
:specialized_instruction
-
:stack_caching
-
:tailcall_optimization
-
:trace_instruction
Additionally, :debug_level
can be set to an integer.
These default options can be overwritten for a single run of the iseq compiler by passing any of the above values as the options
parameter to .new, .compile and .compile_file.
Class Method Details
.compile(source[, file[, path[, line[, options]]]]) ⇒ iseq
.new(source[, file[, path[, line[, options]]]]) ⇒ iseq
iseq
.new(source[, file[, path[, line[, options]]]]) ⇒ iseq
Alias for .new.
.compile_file(file[, options]) ⇒ iseq
Takes file
, a ::String with the location of a Ruby source file, reads, parses and compiles the file, and returns iseq
, the compiled InstructionSequence
with source location metadata set.
Optionally takes options
, which can be true
, false
or a ::Hash, to modify the default behavior of the Ruby iseq compiler.
For details regarding valid compile options see .compile_option=.
# /tmp/hello.rb
puts "Hello, world!"
# elsewhere
RubyVM::InstructionSequence.compile_file("/tmp/hello.rb")
#=> <RubyVM::InstructionSequence:<main>@/tmp/hello.rb>
Also known as: .disassemble
Takes body
, a ::Method or ::Proc object, and returns a ::String with the human readable instructions for body
.
For a ::Method object:
# /tmp/method.rb
def hello
puts "hello, world"
end
puts RubyVM::InstructionSequence.disasm(method(:hello))
Produces:
== disasm: <RubyVM::InstructionSequence:hello@/tmp/method.rb>============
0000 trace 8 ( 1)
0002 trace 1 ( 2)
0004 putself
0005 putstring "hello, world"
0007 send :puts, 1, nil, 8, <ic:0>
0013 trace 16 ( 3)
0015 leave ( 2)
For a ::Proc:
# /tmp/proc.rb
p = proc { num = 1 + 2 }
puts RubyVM::InstructionSequence.disasm(p)
Produces:
== disasm: <RubyVM::InstructionSequence:block in <main>@/tmp/proc.rb>===
== catch table
| catch type: redo st: 0000 ed: 0012 sp: 0000 cont: 0000
| catch type: next st: 0000 ed: 0012 sp: 0000 cont: 0012
|------------------------------------------------------------------------
local table (size: 2, argc: 0 [opts: 0, rest: -1, post: 0, block: -1] s1)
[ 2] num
0000 trace 1 ( 1)
0002 putobject 1
0004 putobject 2
0006 opt_plus <ic:1>
0008 dup
0009 setlocal num, 0
0012 leave
Alias for .disasm.
.load_from_binary(binary) ⇒ iseq
Load an iseq object from binary format ::String object created by #to_binary.
This loader does not have a verifier, so that loading broken/modified binary causes critical problem.
You should not load binary data provided by others. You should use binary data translated by yourself.
.load_from_binary_extra_data(binary) ⇒ String
Load extra data embed into binary format ::String object.
.of(body)
Returns the instruction sequence containing the given proc or method.
For example, using irb:
# a proc
> p = proc { num = 1 + 2 }
> RubyVM::InstructionSequence.of(p)
> #=> <RubyVM::InstructionSequence:block in irb_binding@(irb)>
# for a method
> def foo(bar); puts bar; end
> RubyVM::InstructionSequence.of(method(:foo))
> #=> <RubyVM::InstructionSequence:foo@(irb)>
Using .compile_file:
# /tmp/iseq_of.rb
def hello
puts "hello, world"
end
$a_global_proc = proc { str = 'a' + 'b' }
# in irb
> require '/tmp/iseq_of.rb'
# first the method hello
> RubyVM::InstructionSequence.of(method(:hello))
> #=> #<RubyVM::InstructionSequence:0x007fb73d7cb1d0>
# then the global proc
> RubyVM::InstructionSequence.of($a_global_proc)
> #=> #<RubyVM::InstructionSequence:0x007fb73d7caf78>
Instance Method Details
#absolute_path
Returns the absolute path of this instruction sequence.
nil
if the iseq was evaluated from a string.
For example, using .compile_file:
# /tmp/method.rb
def hello
puts "hello, world"
end
# in irb
> iseq = RubyVM::InstructionSequence.compile_file('/tmp/method.rb')
> iseq.absolute_path #=> /tmp/method.rb
#base_label
Returns the base label of this instruction sequence.
For example, using irb:
iseq = RubyVM::InstructionSequence.compile('num = 1 + 2')
#=> <RubyVM::InstructionSequence:<compiled>@<compiled>>
iseq.base_label
#=> "<compiled>"
Using .compile_file:
# /tmp/method.rb
def hello
puts "hello, world"
end
# in irb
> iseq = RubyVM::InstructionSequence.compile_file('/tmp/method.rb')
> iseq.base_label #=> <main>
Also known as: #disassemble
Alias for #disasm.
#eval ⇒ Object
#first_lineno
#inspect
#label
Returns the label of this instruction sequence.
<main>
if it's at the top level, <compiled>
if it was evaluated from a string.
For example, using irb:
iseq = RubyVM::InstructionSequence.compile('num = 1 + 2')
#=> <RubyVM::InstructionSequence:<compiled>@<compiled>>
iseq.label
#=> "<compiled>"
Using .compile_file:
# /tmp/method.rb
def hello
puts "hello, world"
end
# in irb
> iseq = RubyVM::InstructionSequence.compile_file('/tmp/method.rb')
> iseq.label #=> <main>
#line_trace_all
Experimental MRI specific feature, only available as C level api.
Returns all specified_line
events.
#line_trace_specify(pos, set)
Experimental MRI specific feature, only available as C level api.
Set a specified_line
event at the given line position, if the set
parameter is true
.
This method is useful for building a debugger breakpoint at a specific line.
A TypeError is raised if set
is not boolean.
If pos
is a negative integer a ::TypeError exception is raised.
#marshal_dump (private)
#marshal_load (private)
#path
Returns the path of this instruction sequence.
<compiled>
if the iseq was evaluated from a string.
For example, using irb:
iseq = RubyVM::InstructionSequence.compile('num = 1 + 2')
#=> <RubyVM::InstructionSequence:<compiled>@<compiled>>
iseq.path
#=> "<compiled>"
Using .compile_file:
# /tmp/method.rb
def hello
puts "hello, world"
end
# in irb
> iseq = RubyVM::InstructionSequence.compile_file('/tmp/method.rb')
> iseq.path #=> /tmp/method.rb
#to_a ⇒ Array
Returns an ::Array with 14 elements representing the instruction sequence with the following data:
- magic
-
A string identifying the data format. Always
YARVInstructionSequence/SimpleDataFormat
. - major_version
-
The major version of the instruction sequence.
- minor_version
-
The minor version of the instruction sequence.
- format_type
-
A number identifying the data format. Always 1.
- misc
-
A hash containing:
:arg_size
-
the total number of arguments taken by the method or the block (0 if iseq doesn't represent a method or block)
:local_size
-
the number of local variables + 1
:stack_max
-
used in calculating the stack depth at which a SystemStackError is thrown.
- #label
-
The name of the context (block, method, class, module, etc.) that this instruction sequence belongs to.
<main>
if it's at the top level,<compiled>
if it was evaluated from a string. - #path
-
The relative path to the Ruby file where the instruction sequence was loaded from.
<compiled>
if the iseq was evaluated from a string. - #absolute_path
-
The absolute path to the Ruby file where the instruction sequence was loaded from.
nil
if the iseq was evaluated from a string. - #first_lineno
-
The number of the first source line where the instruction sequence was loaded from.
- type
-
The type of the instruction sequence.
Valid values are
:top
,:method
,:block
,:class
,:rescue
,:ensure
,:eval
,:main
, and:defined_guard
. - locals
-
An array containing the names of all arguments and local variables as symbols.
- params
-
An Hash object containing parameter information.
More info about these values can be found in
vm_core.h
. - catch_table
-
A list of exceptions and control flow operators (rescue, next, redo, break, etc.).
- bytecode
-
An array of arrays containing the instruction names and operands that make up the body of the instruction sequence.
Note that this format is MRI specific and version dependent.
#to_binary(extra_data = nil) ⇒ binary
str
Returns serialized iseq binary format data as a ::String object. A corresponding iseq object is created by InstructionSequence
.load_from_binary() method.
::String extra_data will be saved with binary data. You can access this data with InstructionSequence
.load_from_binary_extra_data(binary).
Note that the translated binary data is not portable. You can not move this binary data to another machine. You can not use the binary data which is created by another version/another architecture of Ruby.