Instruction Sequences

The runtime we have here adds a number of additional methods to RubyVM::InstructionSequence.

Many of the methods give access to rb_iseq_struct. When that's the case, we may provide the C comment for that field name.

• Argument Information
• #arg_block()
• #arg_opts()
• #arg_post_len()
• #arg_rest()
• #arg_simple()
• #argc() => Fixnum
• #catch_table_size() => Fixnum
• #encoded() => String
• #equal?(iseq2)
• #eval_source() => String
• #iseq_size() => Fixnum
• #klass() => ClassName
• #local_name(i) => String
• #local_size() => Fixnum
• #local_table_size() => Fixnum
• #offset2lines(offset) => Array or nil
• #offsetlines() => Hash
• #op_at(offset) => String
• #parent()
• #orig()
• #source_container() => tuple
• #start_insn(line) => Fixnum
• #type() => Fixnum
• #brkpt_alloc() => bool
• #brkpt_dealloc() => bool
• Breakpoints
  • #brkpt_get(iseq, offset) => bool
  • #brkpt_set()
  • #brkpt_get(iseq, offset) => bool
  • #brkpt_unset()
  • #brkpts() => Array

Argument Information

The following comment is from rb_iseq_struct and may be useful
in subsequent method access routines:

def m(a1, a2, ..., aM,                    # mandatory
      b1=(...), b2=(...), ..., bN=(...),  # optional
      *c,                                 # rest
      d1, d2, ..., dO,                    # post
      e1:(...), e2:(...), ..., eK:(...),  # keyword
      **f,                                # keyword rest
      &g)                                 # block
 =>
 argc           = M                 // or  0 if no mandatory arg
 arg_opts       = N+1               // or  0 if no optional arg
 arg_rest       = M+N               // or -1 if no rest arg
 arg_opt_table  = [ (arg_opts entries) ]
 arg_post_start = M+N+(*1)          // or 0 if no post arguments
 arg_post_len   = O                 // or 0 if no post arguments
 arg_keywords   = K                 // or 0 if no keyword arg
 arg_block      = M+N+(*1)+O+K      // or -1 if no block arg
 arg_keyword    = M+N+(*1)+O+K+(&1) // or -1 if no keyword arg/rest
 arg_simple     = 0 if not simple arguments.
                = 1 if no opt, rest, post, block.
                = 2 if ambiguous block parameter ({|a|}).
 arg_size       = M+N+O+(*1)+K+(&1)+(**1) argument size.

#arg_block()

The VM "arg_block" field of an instruction sequence.

 M+N+(*1)+O+K // or -1 if no block arg

See argument information.

#arg_opts()

The VM arg_opts field of an instruction sequence.

N+1 // or  0 if no optional arg

See argument information.

#arg_post_len()

The VM arg_block field of an instruction sequence.

#arg_rest()

The VM arg_rest field of an instruction sequence.

M+N // or -1 if no rest arg

See argument information.

#arg_simple()

The VM arg_simple field of an instruction sequence.

 = 0 if not simple arguments.
 = 1 if no opt, rest, post, block.
 = 2 if ambiguous block parameter ({|a|}).

See argument information.

#argc() => Fixnum

The VM argc field of an instruction sequence.

 = M // or  0 if no mandatory arg

See argument information.

#catch_table_size() => Fixnum

The VM catch_table_size field of an instruction sequence. The number
bytes used by the catch_table.

#encoded() => String

Returns a string of the encoded bytes of the instruction
sequence. Note that this is probably not usable as is, but may be useful in decoding instructions (using other info) or for getting a SHA1 checksum.

#equal?(iseq2)

Returns true if the instruction sequences are equal.

#eval_source() => String

Return the string used in the creation of this instruction sequence, but only if the instruction sequence was the result of running eval(). Otherwise nil is returned.

#iseq_size() => Fixnum

The VM iseq_size field of an instruction sequence. This is the number of bytes in the instruction sequence.

#klass() => ClassName

The VM klass field of an instruction sequence.

/* klass/module nest information stack (cref) */

#local_name(i) => String

Returns the string name of local variable in i'th position of the local table which goes from 0 to local_table-size-1. nil is returned if
i is out of range.

#local_size() => Fixnum

The VM local field of an instruction sequence.

#local_table_size() => Fixnum

Returns the number of entries in the local table.

/* sizeof(vars) + 1 */

See argument information.

#offset2lines(offset) => Array or nil

If one or more line numbers is associated with the given instruction offset, a Fixnum, then return the list of line number. If the offset isn't found, return nil. In the presence of common-subexpression eliminiation, and other compiler optimization, it is conceivable that an instruction can have more than one line associated with it. In practice for Ruby's VM, this doesn't seem to happen.

#offsetlines() => Hash

The keys in the hash form the VM instruction offsets. The value of the hash for a given offset is a list
of line numbers associated with that offset. In the presence of common-subexpression eliminiation, and other compiler optimization, it is conceivable that an instruction can have more than one line associated with it. In practice for Ruby's VM, this doesn't seem to happen.

#op_at(offset) => String

Returns the opcode name, a string, at the given instruction offset. Ideally it would better to have a Ruby module written in Ruby to access alll of the parts of an instruction. The trepan debugger sometimes looks at opcodes. For example it can set a return value when at a return event and the next opcode is a "leave" instruction.

#parent()

The VM local field of an instruction sequence. All instruction sequences except those with a type() equal to "TOP" have parent instruction sequences.

#orig()

The VM orig field of an instruction sequence.

/* non-NULL if its data have origin */

#source_container() => tuple

Return a tuple of source container. This is either ["file"
filename absolute-file] if the instruction sequence came from a file, or ["string", source-string] if it came from "eval".

TODO: could have come from other sources too.

#start_insn(line) => Fixnum

The Ruby VM instruction offset associcate with line.

#type() => Fixnum

The VM local field of an instruction sequence. Type is one of

• top
• method
• block
• class
• rescue
• ensure
• eval
• main
• guard

Use RubyVM::InstructionSequence::TYPE2STR[] to convert this number into a string.

#brkpt_alloc() => bool

Allocates a breakpoint byte vector of zeros for each
instruction in the instruction sequence. true is returned if
vector was allocated, false if there already was one allocated,
and nil if there was some problem.

#brkpt_dealloc() => bool

Deallocates a previously allocated breakpoint byte vector in the
instruction sequence. true is returned if vector was allocated and now free
false if there breakpoints had been allocated, and nil if there was
some problem.

Breakpoints

This runtime has support to make setting debugger breakpoint handling fast.

#brkpt_get(iseq, offset) => bool

Test if a breakpoint is set in the instruction sequence at offset.
true is returned if there is a breakpoint previously set, false
if not, and nil if there was some problem.

#brkpt_set()

Set a breakpoint of byte vector at offset. true is returned if the breakpoint is now set. An IndexError can or a TypeError can be raised if values are invalid.

#brkpt_get(iseq, offset) => bool

Set a breakpoint is the instruction sequence at offset.
true is returned the breakpoint was set successfully, false
if not, and nil if there was some problem.

#brkpt_unset()

Unset a breakpoint in the instruction sequence at offset.
true is returned the breakpoint was unset successfully, false
if not, and nil if there was some problem.

#brkpts() => Array

Returns a list of breakpoints in effect for this instruction sequence.
If no breakpoints have been allocated nil is returned. If breakpoints
were allocated but none are set then the empty array is returned.