class RubyVM::InstructionSequence
The InstructionSequence class represents a compiled sequence of instructions for the Virtual Machine used in MRI. Not all implementations of Ruby may implement this class, and for the implementations that implement it, the methods defined and behavior of the methods can change in any version.
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 YARV 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.
Of course, this class is MRI specific.
Public Class Methods
Takes source, which can be a string of Ruby code, or an open File object. that contains Ruby source code.
Optionally takes file, path, and line which describe the file path, real path and first line number of the ruby code in source which are metadata attached to the returned iseq.
file is used for ‘__FILE__` and exception backtrace. path is used for require_relative base. It is recommended these should be the same full path.
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>> path = "test.rb" RubyVM::InstructionSequence.compile(File.read(path), path, File.expand_path(path)) #=> <RubyVM::InstructionSequence:<compiled>@test.rb:1> file = File.open("test.rb") RubyVM::InstructionSequence.compile(file) #=> <RubyVM::InstructionSequence:<compiled>@<compiled>:1> path = File.expand_path("test.rb") RubyVM::InstructionSequence.compile(File.read(path), path, path) #=> <RubyVM::InstructionSequence:<compiled>@/absolute/path/to/test.rb:1>
static VALUE
iseqw_s_compile(int argc, VALUE *argv, VALUE self)
{
return iseqw_s_compile_parser(argc, argv, self, rb_ruby_prism_p());
}
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, opt = Qnil;
VALUE parser, f, exc = Qnil, ret;
rb_ast_t *ast;
VALUE ast_value;
rb_compile_option_t option;
int i;
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");
rb_execution_context_t *ec = GET_EC();
VALUE v = rb_vm_push_frame_fname(ec, file);
parser = rb_parser_new();
rb_parser_set_context(parser, NULL, FALSE);
ast_value = rb_parser_load_file(parser, file);
ast = rb_ruby_ast_data_get(ast_value);
if (!ast->body.root) exc = GET_EC()->errinfo;
rb_io_close(f);
if (!ast->body.root) {
rb_ast_dispose(ast);
rb_exc_raise(exc);
}
make_compile_option(&option, opt);
ret = iseqw_new(rb_iseq_new_with_opt(ast_value, rb_fstring_lit("<main>"),
file,
rb_realpath_internal(Qnil, file, 1),
1, NULL, 0, ISEQ_TYPE_TOP, &option,
Qnil));
rb_ast_dispose(ast);
rb_vm_pop_frame(ec);
RB_GC_GUARD(v);
return ret;
}
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. It parses and compiles using prism.
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_prism("/tmp/hello.rb") #=> <RubyVM::InstructionSequence:<main>@/tmp/hello.rb>
static VALUE
iseqw_s_compile_file_prism(int argc, VALUE *argv, VALUE self)
{
VALUE file, opt = Qnil, ret;
rb_compile_option_t option;
int i;
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 */
rb_execution_context_t *ec = GET_EC();
VALUE v = rb_vm_push_frame_fname(ec, file);
pm_parse_result_t result = { 0 };
result.options.line = 1;
result.node.coverage_enabled = 1;
VALUE script_lines;
VALUE error = pm_load_parse_file(&result, file, ruby_vm_keep_script_lines ? &script_lines : NULL);
if (error == Qnil) {
make_compile_option(&option, opt);
int error_state;
rb_iseq_t *iseq = pm_iseq_new_with_opt(&result.node, rb_fstring_lit("<main>"),
file,
rb_realpath_internal(Qnil, file, 1),
1, NULL, 0, ISEQ_TYPE_TOP, &option, &error_state);
pm_parse_result_free(&result);
if (error_state) {
RUBY_ASSERT(iseq == NULL);
rb_jump_tag(error_state);
}
ret = iseqw_new(iseq);
rb_vm_pop_frame(ec);
RB_GC_GUARD(v);
return ret;
} else {
pm_parse_result_free(&result);
rb_vm_pop_frame(ec);
RB_GC_GUARD(v);
rb_exc_raise(error);
}
}
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 -
: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;
make_compile_option(&option, opt);
COMPILE_OPTION_DEFAULT = option;
return opt;
}
Takes source, which can be a string of Ruby code, or an open File object. that contains Ruby source code. It parses and compiles using parse.y.
Optionally takes file, path, and line which describe the file path, real path and first line number of the ruby code in source which are metadata attached to the returned iseq.
file is used for ‘__FILE__` and exception backtrace. path is used for require_relative base. It is recommended these should be the same full path.
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_parsey("a = 1 + 2") #=> <RubyVM::InstructionSequence:<compiled>@<compiled>> path = "test.rb" RubyVM::InstructionSequence.compile_parsey(File.read(path), path, File.expand_path(path)) #=> <RubyVM::InstructionSequence:<compiled>@test.rb:1> file = File.open("test.rb") RubyVM::InstructionSequence.compile_parsey(file) #=> <RubyVM::InstructionSequence:<compiled>@<compiled>:1> path = File.expand_path("test.rb") RubyVM::InstructionSequence.compile_parsey(File.read(path), path, path) #=> <RubyVM::InstructionSequence:<compiled>@/absolute/path/to/test.rb:1>
static VALUE
iseqw_s_compile_parsey(int argc, VALUE *argv, VALUE self)
{
return iseqw_s_compile_parser(argc, argv, self, false);
}
Takes source, which can be a string of Ruby code, or an open File object. that contains Ruby source code. It parses and compiles using prism.
Optionally takes file, path, and line which describe the file path, real path and first line number of the ruby code in source which are metadata attached to the returned iseq.
file is used for ‘__FILE__` and exception backtrace. path is used for require_relative base. It is recommended these should be the same full path.
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_prism("a = 1 + 2") #=> <RubyVM::InstructionSequence:<compiled>@<compiled>> path = "test.rb" RubyVM::InstructionSequence.compile_prism(File.read(path), path, File.expand_path(path)) #=> <RubyVM::InstructionSequence:<compiled>@test.rb:1> file = File.open("test.rb") RubyVM::InstructionSequence.compile_prism(file) #=> <RubyVM::InstructionSequence:<compiled>@<compiled>:1> path = File.expand_path("test.rb") RubyVM::InstructionSequence.compile_prism(File.read(path), path, path) #=> <RubyVM::InstructionSequence:<compiled>@/absolute/path/to/test.rb:1>
static VALUE
iseqw_s_compile_prism(int argc, VALUE *argv, VALUE self)
{
return iseqw_s_compile_parser(argc, argv, self, true);
}
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(rb_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 rb_iseq_ibf_load_extra_data(str);
}
Takes source, which can be a string of Ruby code, or an open File object. that contains Ruby source code.
Optionally takes file, path, and line which describe the file path, real path and first line number of the ruby code in source which are metadata attached to the returned iseq.
file is used for ‘__FILE__` and exception backtrace. path is used for require_relative base. It is recommended these should be the same full path.
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>> path = "test.rb" RubyVM::InstructionSequence.compile(File.read(path), path, File.expand_path(path)) #=> <RubyVM::InstructionSequence:<compiled>@test.rb:1> file = File.open("test.rb") RubyVM::InstructionSequence.compile(file) #=> <RubyVM::InstructionSequence:<compiled>@<compiled>:1> path = File.expand_path("test.rb") RubyVM::InstructionSequence.compile(File.read(path), path, path) #=> <RubyVM::InstructionSequence:<compiled>@/absolute/path/to/test.rb:1>
static VALUE
iseqw_s_compile(int argc, VALUE *argv, VALUE self)
{
return iseqw_s_compile_parser(argc, argv, self, rb_ruby_prism_p());
}
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;
if (rb_frame_info_p(body)) {
iseq = rb_get_iseq_from_frame_info(body);
}
else if (rb_obj_is_proc(body)) {
iseq = vm_proc_iseq(body);
if (!rb_obj_is_iseq((VALUE)iseq)) {
iseq = NULL;
}
}
else if (rb_obj_is_method(body)) {
iseq = rb_method_iseq(body);
}
else if (rb_typeddata_is_instance_of(body, &iseqw_data_type)) {
return body;
}
return iseq ? iseqw_new(iseq) : Qnil;
}
Public Instance Methods
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