Class: RubyVM::InstructionSequence

Inherits:
Object
  • Object
show all
Defined in:
iseq.c,
iseq.c

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 Method Summary collapse

Instance Method Summary collapse

Class Method Details

.compile(source[, file[, path[, line[, options]]]]) ⇒ Object .new(source[, file[, path[, line[, options]]]]) ⇒ Object

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>>



778
779
780
781
782
783
784
785
786
787
788
789
 
# File 'iseq.c', line 778

static VALUE
iseqw_s_compile(int argc, VALUE *argv, VALUE self)
{
    VALUE src, file = Qnil, path = Qnil, line = INT2FIX(1), opt = Qnil;
    rb_secure(1);

    rb_scan_args(argc, argv, "14", &src, &file, &path, &line, &opt);
    if (NIL_P(file)) file = rb_str_new2("<compiled>");
    if (NIL_P(line)) line = INT2FIX(1);

    return iseqw_new(rb_iseq_compile_with_option(src, file, path, line, 0, opt));
}

.compile_file(file[, options]) ⇒ Object

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>



811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
 
# File 'iseq.c', line 811

static VALUE
iseqw_s_compile_file(int argc, VALUE *argv, VALUE self)
{
    VALUE file, line = INT2FIX(1), opt = Qnil;
    VALUE parser;
    VALUE f;
    NODE *node;
    const char *fname;
    rb_compile_option_t option;

    rb_secure(1);
    rb_scan_args(argc, argv, "11", &file, &opt);
    FilePathValue(file);
    fname = StringValueCStr(file);

    f = rb_file_open_str(file, "r");

    parser = rb_parser_new();
    node = rb_parser_compile_file(parser, fname, f, NUM2INT(line));

    rb_io_close(f);

    make_compile_option(&option, opt);

    return iseqw_new(rb_iseq_new_with_opt(node, rb_str_new2("<main>"), file,
					  rb_realpath_internal(Qnil, file, 1), line, NULL,
					  ISEQ_TYPE_TOP, &option));
}

.compile_option ⇒ Object

Returns a hash of default options used by the Ruby iseq compiler.

For details, see InstructionSequence.compile_option=.



890
891
892
893
894
 
# File 'iseq.c', line 890

static VALUE
iseqw_s_compile_option_get(VALUE self)
{
    return make_compile_option_value(&COMPILE_OPTION_DEFAULT);
}

.compile_option=(options) ⇒ Object

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.



872
873
874
875
876
877
878
879
880
 
# File 'iseq.c', line 872

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;
}

.disasm(body) ⇒ String .disassemble(body) ⇒ String

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

Overloads:



1712
1713
1714
1715
1716
1717
 
# File 'iseq.c', line 1712

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));
}

.disasm(body) ⇒ String .disassemble(body) ⇒ String

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

Overloads:



1712
1713
1714
1715
1716
1717
 
# File 'iseq.c', line 1712

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(*args) ⇒ Object

:nodoc:



586
587
588
589
590
591
592
 
# File 'iseq.c', line 586

static VALUE
iseq_s_load(int argc, VALUE *argv, VALUE self)
{
    VALUE data, opt=Qnil;
    rb_scan_args(argc, argv, "11", &data, &opt);
    return iseq_load(data, NULL, opt);
}

.RubyVM::InstructionSequence.load_from_binary(binary) ⇒ Object

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.



2374
2375
2376
2377
2378
 
# File 'iseq.c', line 2374

static VALUE
iseqw_s_load_from_binary(VALUE self, VALUE str)
{
    return iseqw_new(iseq_ibf_load(str));
}

.RubyVM::InstructionSequence.load_from_binary_extra_data(binary) ⇒ String

Load extra data embed into binary format String object.

Returns:



2386
2387
2388
2389
2390
 
# File 'iseq.c', line 2386

static VALUE
iseqw_s_load_from_binary_extra_data(VALUE self, VALUE str)
{
    return  iseq_ibf_load_extra_data(str);
}

.compile(source[, file[, path[, line[, options]]]]) ⇒ Object .new(source[, file[, path[, line[, options]]]]) ⇒ Object

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>>



778
779
780
781
782
783
784
785
786
787
788
789
 
# File 'iseq.c', line 778

static VALUE
iseqw_s_compile(int argc, VALUE *argv, VALUE self)
{
    VALUE src, file = Qnil, path = Qnil, line = INT2FIX(1), opt = Qnil;
    rb_secure(1);

    rb_scan_args(argc, argv, "14", &src, &file, &path, &line, &opt);
    if (NIL_P(file)) file = rb_str_new2("<compiled>");
    if (NIL_P(line)) line = INT2FIX(1);

    return iseqw_new(rb_iseq_compile_with_option(src, file, path, line, 0, opt));
}

.of(body) ⇒ Object

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>



1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
 
# File 'iseq.c', line 1637

static VALUE
iseqw_s_of(VALUE klass, VALUE body)
{
    const rb_iseq_t *iseq = NULL;

    rb_secure(1);

    if (rb_obj_is_proc(body)) {
	rb_proc_t *proc;
	GetProcPtr(body, proc);
	iseq = proc->block.iseq;

	if (!RUBY_VM_NORMAL_ISEQ_P(iseq)) {
	    iseq = NULL;
	}
    }
    else {
	iseq = rb_method_iseq(body);
    }

    return iseq ? iseqw_new(iseq) : Qnil;
}

Instance Method Details

#absolute_path ⇒ Object

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



996
997
998
999
1000
 
# File 'iseq.c', line 996

static VALUE
iseqw_absolute_path(VALUE self)
{
    return rb_iseq_absolute_path(iseqw_check(self));
}

#base_label ⇒ Object

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>



1051
1052
1053
1054
1055
 
# File 'iseq.c', line 1051

static VALUE
iseqw_base_label(VALUE self)
{
    return rb_iseq_base_label(iseqw_check(self));
}

#disasm ⇒ String #disassemble ⇒ String

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

Overloads:



1596
1597
1598
1599
1600
 
# File 'iseq.c', line 1596

static VALUE
iseqw_disasm(VALUE self)
{
    return rb_iseq_disasm(iseqw_check(self));
}

#disasm ⇒ String #disassemble ⇒ String

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

Overloads:



1596
1597
1598
1599
1600
 
# File 'iseq.c', line 1596

static VALUE
iseqw_disasm(VALUE self)
{
    return rb_iseq_disasm(iseqw_check(self));
}

#eval ⇒ Object

Evaluates the instruction sequence and returns the result.

RubyVM::InstructionSequence.compile("1 + 2").eval #=> 3

Returns:



925
926
927
928
929
930
 
# File 'iseq.c', line 925

static VALUE
iseqw_eval(VALUE self)
{
    rb_secure(1);
    return rb_iseq_eval(iseqw_check(self));
}

#first_lineno ⇒ Object

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



1067
1068
1069
1070
1071
 
# File 'iseq.c', line 1067

static VALUE
iseqw_first_lineno(VALUE self)
{
    return rb_iseq_first_lineno(iseqw_check(self));
}

#inspect ⇒ Object

Returns a human-readable string representation of this instruction sequence, including the #label and #path.



936
937
938
939
940
941
942
943
944
945
946
947
948
949
 
# File 'iseq.c', line 936

static VALUE
iseqw_inspect(VALUE self)
{
    const rb_iseq_t *iseq = iseqw_check(self);

    if (!iseq->body->location.label) {
        return rb_sprintf("#<%s: uninitialized>", rb_obj_classname(self));
    }
    else {
	return rb_sprintf("<%s:%s@%s>",
			  rb_obj_classname(self),
			  RSTRING_PTR(iseq->body->location.label), RSTRING_PTR(iseq->body->location.path));
    }
}

#label ⇒ Object

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>



1025
1026
1027
1028
1029
 
# File 'iseq.c', line 1025

static VALUE
iseqw_label(VALUE self)
{
    return rb_iseq_label(iseqw_check(self));
}

#line_trace_all ⇒ Object

Experimental MRI specific feature, only available as C level api.

Returns all specified_line events.



2259
2260
2261
2262
2263
2264
2265
 
# File 'iseq.c', line 2259

VALUE
rb_iseqw_line_trace_all(VALUE iseqw)
{
    VALUE result = rb_ary_new();
    rb_iseqw_line_trace_each(iseqw, collect_trace, (void *)result);
    return result;
}

#line_trace_specify(pos, set) ⇒ Object

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.



2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
 
# File 'iseq.c', line 2306

VALUE
rb_iseqw_line_trace_specify(VALUE iseqval, VALUE pos, VALUE set)
{
    struct set_specifc_data data;

    data.prev = 0;
    data.pos = NUM2INT(pos);
    if (data.pos < 0) rb_raise(rb_eTypeError, "`pos' is negative");

    switch (set) {
      case Qtrue:  data.set = 1; break;
      case Qfalse: data.set = 0; break;
      default:
	rb_raise(rb_eTypeError, "`set' should be true/false");
    }

    rb_iseqw_line_trace_each(iseqval, line_trace_specify, (void *)&data);

    if (data.prev == 0) {
	rb_raise(rb_eTypeError, "`pos' is out of range.");
    }
    return data.prev == 1 ? Qtrue : Qfalse;
}

#marshal_dump ⇒ Object (private)

#marshal_load ⇒ Object (private)

#path ⇒ Object

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



974
975
976
977
978
 
# File 'iseq.c', line 974

static VALUE
iseqw_path(VALUE self)
{
    return rb_iseq_path(iseqw_check(self));
}

#to_a ⇒ Object

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.



1156
1157
1158
1159
1160
1161
1162
 
# File 'iseq.c', line 1156

static VALUE
iseqw_to_a(VALUE self)
{
    const rb_iseq_t *iseq = iseqw_check(self);
    rb_secure(1);
    return iseq_data_to_ary(iseq);
}

#to_binary(extra_data = nil) ⇒ Object

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.



2353
2354
2355
2356
2357
2358
2359
 
# File 'iseq.c', line 2353

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);
}