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

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

path = File.expand_path("test.rb")
RubyVM::InstructionSequence.compile(File.read(path), path, path)
#=> <RubyVM::InstructionSequence:<compiled>@/absolute/path/to/test.rb:1>

1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
# File 'iseq.c', line 1240

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

    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_lit("<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, 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>

1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
# File 'iseq.c', line 1285

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;

    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_ast_t *)rb_parser_load_file(parser, file);
    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->body, rb_fstring_lit("<main>"),
					 file,
					 rb_realpath_internal(Qnil, file, 1),
					 line, NULL, 0, ISEQ_TYPE_TOP, &option));
    rb_ast_dispose(ast);
    return ret;
}

.compile_optionObject

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

For details, see InstructionSequence.compile_option=.


1373
1374
1375
1376
1377
# File 'iseq.c', line 1373

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

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.


1356
1357
1358
1359
1360
1361
1362
1363
# File 'iseq.c', line 1356

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

.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:[email protected]/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:


2570
2571
2572
2573
2574
2575
# File 'iseq.c', line 2570

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:[email protected]/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:


2570
2571
2572
2573
2574
2575
# File 'iseq.c', line 2570

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:


1008
1009
1010
1011
1012
1013
1014
# File 'iseq.c', line 1008

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.


3412
3413
3414
3415
3416
# File 'iseq.c', line 3412

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

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

Load extra data embed into binary format String object.

Returns:


3424
3425
3426
3427
3428
# File 'iseq.c', line 3424

static VALUE
iseqw_s_load_from_binary_extra_data(VALUE self, VALUE str)
{
    return rb_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 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>

path = File.expand_path("test.rb")
RubyVM::InstructionSequence.compile(File.read(path), path, path)
#=> <RubyVM::InstructionSequence:<compiled>@/absolute/path/to/test.rb:1>

1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
# File 'iseq.c', line 1240

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

    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_lit("<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, 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 [email protected](irb)>

# for a method > def foo(bar); puts bar; end > RubyVM::InstructionSequence.of(method(:foo)) > #=> <RubyVM::InstructionSequence:[email protected](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>


2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
# File 'iseq.c', line 2496

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

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

Instance Method Details

#absolute_pathObject

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


1481
1482
1483
1484
1485
# File 'iseq.c', line 1481

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

#base_labelObject

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>


1536
1537
1538
1539
1540
# File 'iseq.c', line 1536

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

#disasmString #disassembleString

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:


2345
2346
2347
2348
2349
# File 'iseq.c', line 2345

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

#disasmString #disassembleString

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:


2345
2346
2347
2348
2349
# File 'iseq.c', line 2345

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

#each_child {|child_iseq| ... } ⇒ Object

Iterate all direct child instruction sequences. Iteration order is implementation/version defined so that people should not rely on the order.

Yields:

  • (child_iseq)

2415
2416
2417
2418
2419
2420
2421
# File 'iseq.c', line 2415

static VALUE
iseqw_each_child(VALUE self)
{
    const rb_iseq_t *iseq = iseqw_check(self);
    iseq_iterate_children(iseq, yield_each_children, NULL);
    return self;
}

#evalObject

Evaluates the instruction sequence and returns the result.

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

Returns:


1408
1409
1410
1411
1412
# File 'iseq.c', line 1408

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

#first_linenoObject

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


1552
1553
1554
1555
1556
# File 'iseq.c', line 1552

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

#inspectObject

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


1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
# File 'iseq.c', line 1418

static VALUE
iseqw_inspect(VALUE self)
{
    const rb_iseq_t *iseq = iseqw_check(self);
    const struct rb_iseq_constant_body *const body = iseq->body;
    VALUE klass = rb_class_name(rb_obj_class(self));

    if (!body->location.label) {
	return rb_sprintf("#<%"PRIsVALUE": uninitialized>", klass);
    }
    else {
	return rb_sprintf("<%"PRIsVALUE":%"PRIsVALUE"@%"PRIsVALUE":%d>",
			  klass,
			  body->location.label, rb_iseq_path(iseq),
			  FIX2INT(rb_iseq_first_lineno(iseq)));
    }
}

#labelObject

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>


1510
1511
1512
1513
1514
# File 'iseq.c', line 1510

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

#marshal_dumpObject (private)

#marshal_loadObject (private)

#pathObject

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


1459
1460
1461
1462
1463
# File 'iseq.c', line 1459

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

#to_aArray

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

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.

Returns:


1641
1642
1643
1644
1645
1646
# File 'iseq.c', line 1641

static VALUE
iseqw_to_a(VALUE self)
{
    const rb_iseq_t *iseq = iseqw_check(self);
    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.


3392
3393
3394
3395
3396
3397
# File 'iseq.c', line 3392

static VALUE
iseqw_to_binary(int argc, VALUE *argv, VALUE self)
{
    VALUE opt = !rb_check_arity(argc, 0, 1) ? Qnil : argv[0];
    return rb_iseq_ibf_dump(iseqw_check(self), opt);
}

#trace_pointsArray

Return trace points in the instruction sequence. Return an array of [line, event_symbol] pair.

Returns:


2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
# File 'iseq.c', line 2444

static VALUE
iseqw_trace_points(VALUE self)
{
    const rb_iseq_t *iseq = iseqw_check(self);
    const struct rb_iseq_constant_body *const body = iseq->body;
    unsigned int i;
    VALUE ary = rb_ary_new();

    for (i=0; i<body->insns_info.size; i++) {
	const struct iseq_insn_info_entry *entry = &body->insns_info.body[i];
	if (entry->events) {
	    push_event_info(iseq, entry->events, entry->line_no, ary);
	}
    }
    return ary;
}