Recent changes to Instruction Sequences

Instruction Sequences modified by Rocky Bernstein

Rocky Bernstein — Fri, 13 Mar 2015 14:15:00 -0000

--- v10
+++ v11
@@ -206,6 +206,9 @@

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

Instruction Sequences modified by Rocky Bernstein

Rocky Bernstein — Fri, 13 Mar 2015 14:02:05 -0000

--- v9
+++ v10
@@ -75,7 +75,7 @@

 See argument information.
 

-## #argc() -> Fixnum
+## #argc() => Fixnum

 The VM *argc* field of an instruction sequence.

@@ -83,13 +83,13 @@

 See argument information.
 

-## #catch_table_size() -> Fixnum
+## #catch_table_size() => Fixnum

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

 

-## #encoded() -> String
+## #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.
@@ -98,31 +98,31 @@

 Returns *true* if the instruction sequences are equal.

-## #eval_source() -> String
+## #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
+## #iseq_size() => Fixnum

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

-## #klass() -> ClassName
+## #klass() => ClassName

 The VM *klass* field of an instruction sequence.

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

 

-## #local_name(i) -> String
+## #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
+## #local_size() => Fixnum

 The VM *local* field of an instruction sequence.

-## #local_table_size() -> Fixnum
+## #local_table_size() => Fixnum

 Returns the number of entries in the local table.

@@ -130,16 +130,16 @@

 See argument information.
 

-## #offset2lines(offset) -> Array or nil
+## #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
+## #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
+## #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.

@@ -153,18 +153,18 @@

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

-## #source_container() -> tuple
+## #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
+## #start_insn(*line*) => Fixnum

 The Ruby VM instruction offset associcate with *line*.

-## #type() -> Fixnum
+## #type() => Fixnum

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

@@ -180,14 +180,14 @@

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

-## #brkpt_alloc() -> bool
+## #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 *ni*l if there was some problem.

-## #brkpt_dealloc() -> bool
+## #brkpt_dealloc() => bool

 Deallocates a previously allocated breakpoint byte vector in the
 instruction sequence. *true* is returned if vector was allocated and now free
@@ -198,7 +198,7 @@

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

-### #brkpt_get(iseq, offset) -> bool
+### #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*
@@ -206,7 +206,7 @@

 ### #brkpt_set()

-### #brkpt_get(iseq, offset) -> bool
+### #brkpt_get(iseq, offset) => bool

 Set a breakpoint is the instruction sequence at *offset*.
 *true* is returned the breakpoint was set successfully, *false*
@@ -215,11 +215,11 @@

 ### #brkpt_unset()

-Unset a breakpoint is the instruction sequence at *offset*.
+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
+### #brkpts() => Array

 Returns a list of breakpoints in effect for this instruction sequence.
 If no breakpoints have been allocated *nil* is returned. If breakpoints

Instruction Sequences modified by Rocky Bernstein

Rocky Bernstein — Wed, 11 Mar 2015 21:38:47 -0000

--- v8
+++ v9
@@ -1,9 +1,11 @@
+The runtime we have here adds a number of additional methods to [RubyVM::InstructionSequence](http://ruby-doc.org/core-2.1.0/RubyVM/Instruct onSequence.html).
+
+Many of the methods give access to [rb_iseq_struct](http://fossies.org/dox/ruby-2.2.1/structrb__iseq__struct.html). When that's the case, we may provide the C comment for that field name.
+
 [TOC]

-A number of the methods below give access to [rb_iseq_struct](http://fossies.org/dox/ruby-2.2.1/structrb__iseq__struct.html). When that's the case, we may provide the C comment for that field name.
-
 
-## argument information
+## Argument Information
 

 The following comment is from `rb_iseq_struct` and may be useful
@@ -57,7 +59,7 @@

 The VM arg_rest field of an instruction sequence.

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

 See argument information.

@@ -77,7 +79,7 @@

 The VM *argc* field of an instruction sequence.

-     = M                 // or  0 if no mandatory arg
+     = M // or  0 if no mandatory arg

 See argument information.
 

@@ -177,3 +179,48 @@
 * 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 *ni*l 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()
+
+### #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 is 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.

Instruction Sequences modified by Rocky Bernstein

Rocky Bernstein — Wed, 11 Mar 2015 02:40:47 -0000

--- v7
+++ v8
@@ -32,7 +32,7 @@
                     = 2 if ambiguous block parameter ({|a|}).
      arg_size       = M+N+O+(*1)+K+(&1)+(**1) argument size.

-## arg_block()
+## #arg_block()

 The VM "arg_block" field of an instruction sequence.
@@ -41,7 +41,7 @@

 See argument information.

-## arg_opts()
+## #arg_opts()

 The VM arg_opts field of an instruction sequence.

@@ -49,11 +49,11 @@

 See argument information.

-## arg_post_len()
+## #arg_post_len()

 The VM arg_block field of an instruction sequence.

-## arg_rest()
+## #arg_rest()

 The VM arg_rest field of an instruction sequence.

@@ -63,7 +63,7 @@

 

-## arg_simple()
+## #arg_simple()

 The VM arg_simple field of an instruction sequence.

@@ -73,7 +73,7 @@

 See argument information.
 

-## argc() -> Fixnum
+## #argc() -> Fixnum

 The VM *argc* field of an instruction sequence.

@@ -81,46 +81,46 @@

 See argument information.
 

-## catch_table_size() -> Fixnum
+## #catch_table_size() -> Fixnum

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

 

-## encoded() -> String
+## #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)
+## #equal?(iseq2)

 Returns *true* if the instruction sequences are equal.

-## eval_source() -> String
+## #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()
+## #iseq_size() -> Fixnum

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

-## klass() -> ClassName
+## #klass() -> ClassName

 The VM *klass* field of an instruction sequence.

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

 

-## local_name(i) -> String
+## #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
+## #local_size() -> Fixnum

 The VM *local* field of an instruction sequence.

-## local_table_size() -> Fixnum
+## #local_table_size() -> Fixnum

 Returns the number of entries in the local table.

@@ -128,41 +128,41 @@

 See argument information.
 

-## offset2lines(offset) -> Array or nil
+## #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
+## #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
+## #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()
+## #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()
+## #orig()

 The VM *orig* field of an instruction sequence.

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

-## source_container() -> tuple
+## #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
+## #start_insn(*line*) -> Fixnum

 The Ruby VM instruction offset associcate with *line*.

-## type() -> Fixnum
+## #type() -> Fixnum

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

Instruction Sequences modified by Rocky Bernstein

Rocky Bernstein — Wed, 11 Mar 2015 01:52:05 -0000

--- v6
+++ v7
@@ -39,7 +39,7 @@

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

-See [#args]
+See argument information.

 ## arg_opts()

@@ -47,7 +47,7 @@

     N+1 // or  0 if no optional arg

-See [#args]
+See argument information.

 ## arg_post_len()

@@ -59,7 +59,7 @@

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

-See [#args]
+See argument information.

 

@@ -71,7 +71,7 @@
      = 1 if no opt, rest, post, block.
      = 2 if ambiguous block parameter ({|a|}).

-
+See argument information.
 

 ## argc() -> Fixnum

@@ -79,6 +79,7 @@

      = M                 // or  0 if no mandatory arg

+See argument information.
 

 ## catch_table_size() -> Fixnum

@@ -125,6 +126,7 @@

     /* sizeof(vars) + 1 */

+See argument information.
 

 ## offset2lines(offset) -> Array or nil

Instruction Sequences modified by Rocky Bernstein

Rocky Bernstein — Tue, 10 Mar 2015 21:08:08 -0000

--- v5
+++ v6
@@ -2,7 +2,9 @@

 A number of the methods below give access to [rb_iseq_struct](http://fossies.org/dox/ruby-2.2.1/structrb__iseq__struct.html). When that's the case, we may provide the C comment for that field name.

+
 ## argument information
+

 The following comment is from `rb_iseq_struct` and may be useful
 in subsequent method access routines:
@@ -37,7 +39,7 @@

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

-See [Instruction Sequences#argument information]
+See [#args]

 ## arg_opts()

@@ -45,7 +47,7 @@

     N+1 // or  0 if no optional arg

-See [#argument information]
+See [#args]

 ## arg_post_len()

@@ -57,27 +59,37 @@

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

-See [#argument information]
+See [#args]

+

 ## 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|}).
+
+
+

 ## argc() -> Fixnum

-The VM argc field of an instruction sequence.
+The VM *argc* field of an instruction sequence.

+     = M                 // or  0 if no mandatory arg
+
+

 ## catch_table_size() -> Fixnum

-The VM argc field of an instruction sequence.
+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.
+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)

@@ -95,6 +107,9 @@

 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
@@ -108,6 +123,9 @@

 Returns the number of entries in the local table.

+    /* sizeof(vars) + 1 */
+
+

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

Instruction Sequences modified by Rocky Bernstein

Rocky Bernstein — Tue, 10 Mar 2015 16:56:15 -0000

--- v4
+++ v5
@@ -37,7 +37,7 @@

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

-See [#argument information]
+See [Instruction Sequences#argument information]

 ## arg_opts()

Instruction Sequences modified by Rocky Bernstein

Rocky Bernstein — Tue, 10 Mar 2015 16:55:33 -0000

--- v3
+++ v4
@@ -1,12 +1,52 @@
 [TOC]

+A number of the methods below give access to [rb_iseq_struct](http://fossies.org/dox/ruby-2.2.1/structrb__iseq__struct.html). When that's the case, we may provide the C comment for that field name.
+
+## argument information
+
+The following comment is from `rb_iseq_struct` and may be useful
+in subsequent method access routines:
+
+    :::ruby
+    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.
@@ -14,6 +54,12 @@
 ## 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.
@@ -83,6 +129,8 @@

 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"

Instruction Sequences modified by Rocky Bernstein

Rocky Bernstein — Tue, 10 Mar 2015 16:55:01 -0000

Instruction Sequences modified by Rocky Bernstein

Rocky Bernstein — Tue, 10 Mar 2015 07:27:51 -0000

--- v1
+++ v2
@@ -85,8 +85,8 @@

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