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.
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>>
static VALUE iseqw_s_compile(int argc, VALUE *argv, VALUE self) { VALUE src, file = Qnil, path = Qnil, line = INT2FIX(1), opt = Qnil; int i; rb_secure(1); i = rb_scan_args(argc, argv, "1*:", &src, NULL, &opt); if (i > 4+NIL_P(opt)) rb_error_arity(argc, 1, 5); switch (i) { case 5: opt = argv[--i]; case 4: line = argv[--i]; case 3: path = argv[--i]; case 2: file = argv[--i]; } if (NIL_P(file)) file = rb_fstring_cstr("<compiled>"); if (NIL_P(path)) path = file; if (NIL_P(line)) line = INT2FIX(1); Check_Type(path, T_STRING); Check_Type(file, T_STRING); return iseqw_new(rb_iseq_compile_with_option(src, file, path, line, 0, opt)); }
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>
static VALUE iseqw_s_compile_file(int argc, VALUE *argv, VALUE self) { VALUE file, line = INT2FIX(1), opt = Qnil; VALUE parser, f, exc = Qnil, ret; rb_ast_t *ast; rb_compile_option_t option; int i; rb_secure(1); i = rb_scan_args(argc, argv, "1*:", &file, NULL, &opt); if (i > 1+NIL_P(opt)) rb_error_arity(argc, 1, 2); switch (i) { case 2: opt = argv[--i]; } FilePathValue(file); file = rb_fstring(file); /* rb_io_t->pathv gets frozen anyways */ f = rb_file_open_str(file, "r"); parser = rb_parser_new(); rb_parser_set_context(parser, NULL, FALSE); ast = rb_parser_compile_file_path(parser, file, f, NUM2INT(line)); if (!ast->root) exc = GET_EC()->errinfo; rb_io_close(f); if (!ast->root) { rb_ast_dispose(ast); rb_exc_raise(exc); } make_compile_option(&option, opt); ret = iseqw_new(rb_iseq_new_with_opt(ast->root, rb_fstring_cstr("<main>"), file, rb_realpath_internal(Qnil, file, 1), line, NULL, ISEQ_TYPE_TOP, &option)); rb_ast_dispose(ast); return ret; }
Returns a hash of default options used by the Ruby iseq compiler.
For details, see InstructionSequence.compile_option=
.
static VALUE iseqw_s_compile_option_get(VALUE self) { return make_compile_option_value(&COMPILE_OPTION_DEFAULT); }
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
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
.
static VALUE iseqw_s_compile_option_set(VALUE self, VALUE opt) { rb_compile_option_t option; rb_secure(1); make_compile_option(&option, opt); COMPILE_OPTION_DEFAULT = option; return opt; }
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
static VALUE iseqw_s_disasm(VALUE klass, VALUE body) { VALUE iseqw = iseqw_s_of(klass, body); return NIL_P(iseqw) ? Qnil : rb_iseq_disasm(iseqw_check(iseqw)); }
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
static VALUE iseqw_s_disasm(VALUE klass, VALUE body) { VALUE iseqw = iseqw_s_of(klass, body); return NIL_P(iseqw) ? Qnil : rb_iseq_disasm(iseqw_check(iseqw)); }
Load an iseq object from binary format String
object created by RubyVM::InstructionSequence.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.
static VALUE iseqw_s_load_from_binary(VALUE self, VALUE str) { return iseqw_new(iseq_ibf_load(str)); }
Load extra data embed into binary format String
object.
static VALUE iseqw_s_load_from_binary_extra_data(VALUE self, VALUE str) { return iseq_ibf_load_extra_data(str); }
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>>
static VALUE iseqw_s_compile(int argc, VALUE *argv, VALUE self) { VALUE src, file = Qnil, path = Qnil, line = INT2FIX(1), opt = Qnil; int i; rb_secure(1); i = rb_scan_args(argc, argv, "1*:", &src, NULL, &opt); if (i > 4+NIL_P(opt)) rb_error_arity(argc, 1, 5); switch (i) { case 5: opt = argv[--i]; case 4: line = argv[--i]; case 3: path = argv[--i]; case 2: file = argv[--i]; } if (NIL_P(file)) file = rb_fstring_cstr("<compiled>"); if (NIL_P(path)) path = file; if (NIL_P(line)) line = INT2FIX(1); Check_Type(path, T_STRING); Check_Type(file, T_STRING); return iseqw_new(rb_iseq_compile_with_option(src, file, path, line, 0, opt)); }
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>
static VALUE iseqw_s_of(VALUE klass, VALUE body) { const rb_iseq_t *iseq = NULL; rb_secure(1); if (rb_obj_is_proc(body)) { iseq = vm_proc_iseq(body); if (!rb_obj_is_iseq((VALUE)iseq)) { iseq = NULL; } } else { iseq = rb_method_iseq(body); } return iseq ? iseqw_new(iseq) : Qnil; }
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
static VALUE iseqw_absolute_path(VALUE self) { return rb_iseq_realpath(iseqw_check(self)); }
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>
static VALUE iseqw_base_label(VALUE self) { return rb_iseq_base_label(iseqw_check(self)); }
Returns the instruction sequence as a String
in human readable form.
puts RubyVM::InstructionSequence.compile('1 + 2').disasm
Produces:
== disasm: <RubyVM::InstructionSequence:<compiled>@<compiled>>========== 0000 trace 1 ( 1) 0002 putobject 1 0004 putobject 2 0006 opt_plus <ic:1> 0008 leave
static VALUE iseqw_disasm(VALUE self) { return rb_iseq_disasm(iseqw_check(self)); }
Returns the instruction sequence as a String
in human readable form.
puts RubyVM::InstructionSequence.compile('1 + 2').disasm
Produces:
== disasm: <RubyVM::InstructionSequence:<compiled>@<compiled>>========== 0000 trace 1 ( 1) 0002 putobject 1 0004 putobject 2 0006 opt_plus <ic:1> 0008 leave
static VALUE iseqw_disasm(VALUE self) { return rb_iseq_disasm(iseqw_check(self)); }
Iterate all direct child instruction sequences. Iteration order is implementation/version defined so that people should not rely on the order.
static VALUE iseqw_each_child(VALUE self) { const rb_iseq_t *iseq = iseqw_check(self); VALUE all_children = rb_iseq_all_children(iseq); rb_hash_foreach(all_children, iseqw_each_child_i, Qnil); return self; }
Evaluates the instruction sequence and returns the result.
RubyVM::InstructionSequence.compile("1 + 2").eval #=> 3
static VALUE iseqw_eval(VALUE self) { rb_secure(1); return rb_iseq_eval(iseqw_check(self)); }
Returns the number of the first source line where the instruction sequence was loaded from.
For example, using irb:
iseq = RubyVM::InstructionSequence.compile('num = 1 + 2') #=> <RubyVM::InstructionSequence:<compiled>@<compiled>> iseq.first_lineno #=> 1
static VALUE iseqw_first_lineno(VALUE self) { return rb_iseq_first_lineno(iseqw_check(self)); }
Returns a human-readable string representation of this instruction sequence, including the label
and path
.
static VALUE iseqw_inspect(VALUE self) { const rb_iseq_t *iseq = iseqw_check(self); VALUE klass = rb_class_name(rb_obj_class(self)); if (!iseq->body->location.label) { return rb_sprintf("#<%"PRIsVALUE": uninitialized>", klass); } else { return rb_sprintf("<%"PRIsVALUE":%"PRIsVALUE"@%"PRIsVALUE":%d>", klass, iseq->body->location.label, rb_iseq_path(iseq), FIX2INT(rb_iseq_first_lineno(iseq))); } }
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>
static VALUE iseqw_label(VALUE self) { return rb_iseq_label(iseqw_check(self)); }
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
static VALUE iseqw_path(VALUE self) { return rb_iseq_path(iseqw_check(self)); }
Returns an Array
with 14 elements representing the instruction sequence with the following data:
A string identifying the data format. Always YARVInstructionSequence/SimpleDataFormat
.
The major version of the instruction sequence.
The minor version of the instruction sequence.
A number identifying the data format. Always 1.
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.
The type of the instruction sequence.
Valid values are :top
, :method
, :block
, :class
, :rescue
, :ensure
, :eval
, :main
, and :defined_guard
.
An array containing the names of all arguments and local variables as symbols.
An Hash
object containing parameter information.
More info about these values can be found in vm_core.h
.
A list of exceptions and control flow operators (rescue, next, redo, break, etc.).
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.
static VALUE iseqw_to_a(VALUE self) { const rb_iseq_t *iseq = iseqw_check(self); rb_secure(1); return iseq_data_to_ary(iseq); }
Returns serialized iseq binary format data as a String
object. A corresponding iseq object is created by RubyVM::InstructionSequence.load_from_binary()
method.
String
extra_data will be saved with binary data. You can access this data with RubyVM::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.
static VALUE iseqw_to_binary(int argc, VALUE *argv, VALUE self) { VALUE opt; rb_scan_args(argc, argv, "01", &opt); return iseq_ibf_dump(iseqw_check(self), opt); }
Return trace points in the instruction sequence. Return an array of [line, event_symbol] pair.
static VALUE iseqw_trace_points(VALUE self) { const rb_iseq_t *iseq = iseqw_check(self); unsigned int i; VALUE ary = rb_ary_new(); for (i=0; i<iseq->body->insns_info_size; i++) { const struct iseq_insn_info_entry *entry = &iseq->body->insns_info[i]; if (entry->events) { push_event_info(iseq, entry->events, entry->line_no, ary); } } return ary; }