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



660
661
662
663
664
665
666
667
668
669
670
671
672
 
# File 'iseq.c', line 660

static VALUE
iseq_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 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>



694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
 
# File 'iseq.c', line 694

static VALUE
iseq_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 rb_iseq_new_with_opt(node, rb_str_new2("<main>"), file,
				rb_realpath_internal(Qnil, file, 1), line, Qfalse,
				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=.



772
773
774
775
776
 
# File 'iseq.c', line 772

static VALUE
iseq_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.



754
755
756
757
758
759
760
761
762
 
# File 'iseq.c', line 754

static VALUE
iseq_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:



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

static VALUE
iseq_s_disasm(VALUE klass, VALUE body)
{
    VALUE iseqval = iseq_s_of(klass, body);
    return NIL_P(iseqval) ? Qnil : rb_iseq_disasm(iseqval);
}

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



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

static VALUE
iseq_s_disasm(VALUE klass, VALUE body)
{
    VALUE iseqval = iseq_s_of(klass, body);
    return NIL_P(iseqval) ? Qnil : rb_iseq_disasm(iseqval);
}

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



660
661
662
663
664
665
666
667
668
669
670
671
672
 
# File 'iseq.c', line 660

static VALUE
iseq_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 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>



1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
 
# File 'iseq.c', line 1520

static VALUE
iseq_s_of(VALUE klass, VALUE body)
{
    VALUE ret = Qnil;
    rb_iseq_t *iseq;

    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)) {
	    ret = iseq->self;
	}
    }
    else if ((iseq = rb_method_get_iseq(body)) != 0) {
	ret = iseq->self;
    }
    return ret;
}

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



869
870
871
872
873
874
875
 
# File 'iseq.c', line 869

VALUE
rb_iseq_absolute_path(VALUE self)
{
    rb_iseq_t *iseq;
    GetISeqPtr(self, iseq);
    return iseq->location.absolute_path;
}

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



928
929
930
931
932
933
934
 
# File 'iseq.c', line 928

VALUE
rb_iseq_base_label(VALUE self)
{
    rb_iseq_t *iseq;
    GetISeqPtr(self, iseq);
    return iseq->location.base_label;
}

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



1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
 
# File 'iseq.c', line 1374

VALUE
rb_iseq_disasm(VALUE self)
{
    rb_iseq_t *iseqdat = iseq_check(self); /* TODO: rename to iseq */
    VALUE *iseq;
    VALUE str = rb_str_new(0, 0);
    VALUE child = rb_ary_new();
    unsigned int size;
    int i;
    long l;
    ID *tbl;
    size_t n;
    enum {header_minlen = 72};

    rb_secure(1);

    size = iseqdat->iseq_size;

    rb_str_cat2(str, "== disasm: ");

    rb_str_concat(str, iseq_inspect(iseqdat->self));
    if ((l = RSTRING_LEN(str)) < header_minlen) {
	rb_str_resize(str, header_minlen);
	memset(RSTRING_PTR(str) + l, '=', header_minlen - l);
    }
    rb_str_cat2(str, "\n");

    /* show catch table information */
    if (iseqdat->catch_table) {
	rb_str_cat2(str, "== catch table\n");
    }
    if (iseqdat->catch_table) for (i = 0; i < iseqdat->catch_table->size; i++) {
	struct iseq_catch_table_entry *entry = &iseqdat->catch_table->entries[i];
	rb_str_catf(str,
		    "| catch type: %-6s st: %04d ed: %04d sp: %04d cont: %04d\n",
		    catch_type((int)entry->type), (int)entry->start,
		    (int)entry->end, (int)entry->sp, (int)entry->cont);
	if (entry->iseq) {
	    rb_str_concat(str, rb_iseq_disasm(entry->iseq));
	}
    }
    if (iseqdat->catch_table) {
	rb_str_cat2(str, "|-------------------------------------"
		    "-----------------------------------\n");
    }

    /* show local table information */
    tbl = iseqdat->local_table;

    if (tbl) {
	rb_str_catf(str,
		    "local table (size: %d, argc: %d "
		    "[opts: %d, rest: %d, post: %d, block: %d, kw: %d@%d, kwrest: %d])\n",
		    iseqdat->local_size,
		    iseqdat->param.lead_num,
		    iseqdat->param.opt_num,
		    iseqdat->param.flags.has_rest ? iseqdat->param.rest_start : -1,
		    iseqdat->param.post_num,
		    iseqdat->param.flags.has_block ? iseqdat->param.block_start : -1,
		    iseqdat->param.flags.has_kw ? iseqdat->param.keyword->num : -1,
		    iseqdat->param.flags.has_kw ? iseqdat->param.keyword->required_num : -1,
		    iseqdat->param.flags.has_kwrest ? iseqdat->param.keyword->rest_start : -1);

	for (i = 0; i < iseqdat->local_table_size; i++) {
	    long width;
	    VALUE name = id_to_name(tbl[i], 0);
	    char argi[0x100] = "";
	    char opti[0x100] = "";

	    if (iseqdat->param.flags.has_opt) {
		int argc = iseqdat->param.lead_num;
		int opts = iseqdat->param.opt_num;
		if (i >= argc && i < argc + opts) {
		    snprintf(opti, sizeof(opti), "Opt=%"PRIdVALUE,
			     iseqdat->param.opt_table[i - argc]);
		}
	    }

	    snprintf(argi, sizeof(argi), "%s%s%s%s%s",	/* arg, opts, rest, post  block */
		     iseqdat->param.lead_num > i ? "Arg" : "",
		     opti,
		     (iseqdat->param.flags.has_rest && iseqdat->param.rest_start == i) ? "Rest" : "",
		     (iseqdat->param.flags.has_post && iseqdat->param.post_start <= i && i < iseqdat->param.post_start + iseqdat->param.post_num) ? "Post" : "",
		     (iseqdat->param.flags.has_block && iseqdat->param.block_start == i) ? "Block" : "");

	    rb_str_catf(str, "[%2d] ", iseqdat->local_size - i);
	    width = RSTRING_LEN(str) + 11;
	    if (name)
		rb_str_append(str, name);
	    else
		rb_str_cat2(str, "?");
	    if (*argi) rb_str_catf(str, "<%s>", argi);
	    if ((width -= RSTRING_LEN(str)) > 0) rb_str_catf(str, "%*s", (int)width, "");
	}
	rb_str_cat2(str, "\n");
    }

    /* show each line */
    iseq = rb_iseq_original_iseq(iseqdat);
    for (n = 0; n < size;) {
	n += rb_iseq_disasm_insn(str, iseq, n, iseqdat, child);
    }

    for (i = 0; i < RARRAY_LEN(child); i++) {
	VALUE isv = rb_ary_entry(child, i);
	rb_str_concat(str, rb_iseq_disasm(isv));
    }

    return str;
}

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



1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
 
# File 'iseq.c', line 1374

VALUE
rb_iseq_disasm(VALUE self)
{
    rb_iseq_t *iseqdat = iseq_check(self); /* TODO: rename to iseq */
    VALUE *iseq;
    VALUE str = rb_str_new(0, 0);
    VALUE child = rb_ary_new();
    unsigned int size;
    int i;
    long l;
    ID *tbl;
    size_t n;
    enum {header_minlen = 72};

    rb_secure(1);

    size = iseqdat->iseq_size;

    rb_str_cat2(str, "== disasm: ");

    rb_str_concat(str, iseq_inspect(iseqdat->self));
    if ((l = RSTRING_LEN(str)) < header_minlen) {
	rb_str_resize(str, header_minlen);
	memset(RSTRING_PTR(str) + l, '=', header_minlen - l);
    }
    rb_str_cat2(str, "\n");

    /* show catch table information */
    if (iseqdat->catch_table) {
	rb_str_cat2(str, "== catch table\n");
    }
    if (iseqdat->catch_table) for (i = 0; i < iseqdat->catch_table->size; i++) {
	struct iseq_catch_table_entry *entry = &iseqdat->catch_table->entries[i];
	rb_str_catf(str,
		    "| catch type: %-6s st: %04d ed: %04d sp: %04d cont: %04d\n",
		    catch_type((int)entry->type), (int)entry->start,
		    (int)entry->end, (int)entry->sp, (int)entry->cont);
	if (entry->iseq) {
	    rb_str_concat(str, rb_iseq_disasm(entry->iseq));
	}
    }
    if (iseqdat->catch_table) {
	rb_str_cat2(str, "|-------------------------------------"
		    "-----------------------------------\n");
    }

    /* show local table information */
    tbl = iseqdat->local_table;

    if (tbl) {
	rb_str_catf(str,
		    "local table (size: %d, argc: %d "
		    "[opts: %d, rest: %d, post: %d, block: %d, kw: %d@%d, kwrest: %d])\n",
		    iseqdat->local_size,
		    iseqdat->param.lead_num,
		    iseqdat->param.opt_num,
		    iseqdat->param.flags.has_rest ? iseqdat->param.rest_start : -1,
		    iseqdat->param.post_num,
		    iseqdat->param.flags.has_block ? iseqdat->param.block_start : -1,
		    iseqdat->param.flags.has_kw ? iseqdat->param.keyword->num : -1,
		    iseqdat->param.flags.has_kw ? iseqdat->param.keyword->required_num : -1,
		    iseqdat->param.flags.has_kwrest ? iseqdat->param.keyword->rest_start : -1);

	for (i = 0; i < iseqdat->local_table_size; i++) {
	    long width;
	    VALUE name = id_to_name(tbl[i], 0);
	    char argi[0x100] = "";
	    char opti[0x100] = "";

	    if (iseqdat->param.flags.has_opt) {
		int argc = iseqdat->param.lead_num;
		int opts = iseqdat->param.opt_num;
		if (i >= argc && i < argc + opts) {
		    snprintf(opti, sizeof(opti), "Opt=%"PRIdVALUE,
			     iseqdat->param.opt_table[i - argc]);
		}
	    }

	    snprintf(argi, sizeof(argi), "%s%s%s%s%s",	/* arg, opts, rest, post  block */
		     iseqdat->param.lead_num > i ? "Arg" : "",
		     opti,
		     (iseqdat->param.flags.has_rest && iseqdat->param.rest_start == i) ? "Rest" : "",
		     (iseqdat->param.flags.has_post && iseqdat->param.post_start <= i && i < iseqdat->param.post_start + iseqdat->param.post_num) ? "Post" : "",
		     (iseqdat->param.flags.has_block && iseqdat->param.block_start == i) ? "Block" : "");

	    rb_str_catf(str, "[%2d] ", iseqdat->local_size - i);
	    width = RSTRING_LEN(str) + 11;
	    if (name)
		rb_str_append(str, name);
	    else
		rb_str_cat2(str, "?");
	    if (*argi) rb_str_catf(str, "<%s>", argi);
	    if ((width -= RSTRING_LEN(str)) > 0) rb_str_catf(str, "%*s", (int)width, "");
	}
	rb_str_cat2(str, "\n");
    }

    /* show each line */
    iseq = rb_iseq_original_iseq(iseqdat);
    for (n = 0; n < size;) {
	n += rb_iseq_disasm_insn(str, iseq, n, iseqdat, child);
    }

    for (i = 0; i < RARRAY_LEN(child); i++) {
	VALUE isv = rb_ary_entry(child, i);
	rb_str_concat(str, rb_iseq_disasm(isv));
    }

    return str;
}

#eval ⇒ Object

Evaluates the instruction sequence and returns the result.

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

Returns:



797
798
799
800
801
802
 
# File 'iseq.c', line 797

static VALUE
iseq_eval(VALUE self)
{
    rb_secure(1);
    return rb_iseq_eval(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



946
947
948
949
950
951
952
 
# File 'iseq.c', line 946

VALUE
rb_iseq_first_lineno(VALUE self)
{
    rb_iseq_t *iseq;
    GetISeqPtr(self, iseq);
    return iseq->location.first_lineno;
}

#inspect ⇒ Object

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



808
809
810
811
812
813
814
815
816
817
818
819
820
 
# File 'iseq.c', line 808

static VALUE
iseq_inspect(VALUE self)
{
    rb_iseq_t *iseq;
    GetISeqPtr(self, iseq);
    if (!iseq->location.label) {
        return rb_sprintf("#<%s: uninitialized>", rb_obj_classname(self));
    }

    return rb_sprintf("<%s:%s@%s>",
                      rb_obj_classname(self),
		      RSTRING_PTR(iseq->location.label), RSTRING_PTR(iseq->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>



900
901
902
903
904
905
906
 
# File 'iseq.c', line 900

VALUE
rb_iseq_label(VALUE self)
{
    rb_iseq_t *iseq;
    GetISeqPtr(self, iseq);
    return iseq->location.label;
}

#line_trace_all ⇒ Object

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

Returns all specified_line events.



2233
2234
2235
2236
2237
2238
2239
 
# File 'iseq.c', line 2233

VALUE
rb_iseq_line_trace_all(VALUE iseqval)
{
    VALUE result = rb_ary_new();
    rb_iseq_line_trace_each(iseqval, 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.



2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
 
# File 'iseq.c', line 2280

VALUE
rb_iseq_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_iseq_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



845
846
847
848
849
850
851
 
# File 'iseq.c', line 845

VALUE
rb_iseq_path(VALUE self)
{
    rb_iseq_t *iseq;
    GetISeqPtr(self, iseq);
    return iseq->location.path;
}

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



1060
1061
1062
1063
1064
1065
1066
 
# File 'iseq.c', line 1060

static VALUE
iseq_to_a(VALUE self)
{
    rb_iseq_t *iseq = iseq_check(self);
    rb_secure(1);
    return iseq_data_to_ary(iseq);
}