Recent changes to Call Frame

Call Frame modified by Rocky Bernstein

Rocky Bernstein — Thu, 12 Mar 2015 15:18:53 -0000

--- v17
+++ v18
@@ -100,7 +100,7 @@
     :::ruby
     irb$ proc { | a=1 | eval("a+2", RubyVM::Frame::get.binding ) }.call
    => 3
-
+

 ### #getlocal(index) => Object

 Returns the local variable at the given stack index. The values of local variables in the Ruby MRI indexed by number. This method retrieves the value of a local variable by number.

Call Frame modified by Rocky Bernstein

Rocky Bernstein — Wed, 11 Mar 2015 22:05:20 -0000

--- v16
+++ v17
@@ -10,7 +10,51 @@

 [TOC]

-## Frame Methods
+## Frame Singleton Methods
+
+### stack_size()
+
+Get the frame stack size for the current thread.
+
+
+### get() -> RubyVM::Frame object
+
+
+    :::ruby
+    RubyVM::Frame::get(thread)     -> RubyVM::Frame object
+    RubyVM::Frame::get(thread, n)  -> RubyVM::Frame object
+    RubyVM::Frame::get             -> RubyVM::Frame object
+    RubyVM::Frame::get(n)          -> RubyVM::Frame object
+

+In the first form, *get(thread)*, we return the current RubyVM::Frame
+for the [Thread](http://ruby-doc.org/core-2.2.0/Thread.html) object
+passed. This is the current frame, [Thread::current](http://ruby-doc.org/core-2.2.0/Thread.html#method-c-current).
+
+In the second form, *get(thread, n)* we try to go back that Fixnum *n* frames.
+
+In the the third form, *get()*,  the current thread is assumed, and like the
+first form, but we use get the current frame.
+
+The fourth form, *get(n)*, like the third form, we assume the current
+thread.  And like the first form we go back we try to back a
+Fixnum *n*, number of frame.
+
+When count *n* is given, 1 is synonymous with the previous frame. If *n* is negative, we count from the bottom of the frame stack.
+
+In all cases we return a RubyVM::Frame or *nil* if we can't go back (or forward for a negative *n*) that many frames.
+
+*FrameError* can be raised if the frame object is no longer valid.
+
+All of the following are equivalent
+
+    :::ruby
+    RubyVM::Frame::get(Thread::current) #     -> RubyVM::Frame object
+    RubyVM::Frame::get(Thread::current, 0)a
+    RubyVM::Frame::get
+    RubyVM::Frame::get(0)
+
+

+## Frame Instrance Methods

 ### #argc() -> Fixnum

@@ -57,46 +101,6 @@
     irb$ proc { | a=1 | eval("a+2", RubyVM::Frame::get.binding ) }.call
    => 3

-
-### get() -> RubyVM::Frame object
-
-
-In contrast to most of the other methods, this is a class method.
-
-    :::ruby
-    RubyVM::Frame::get(thread)     -> RubyVM::Frame object
-    RubyVM::Frame::get(thread, n)  -> RubyVM::Frame object
-    RubyVM::Frame::get             -> RubyVM::Frame object
-    RubyVM::Frame::get(n)          -> RubyVM::Frame object
-

-In the first form, *get(thread)*, we return the current RubyVM::Frame
-for the [Thread](http://ruby-doc.org/core-2.2.0/Thread.html) object
-passed. This is the current frame, [Thread::current](http://ruby-doc.org/core-2.2.0/Thread.html#method-c-current).
-
-In the second form, *get(thread, n)* we try to go back that Fixnum *n* frames.
-
-In the the third form, *get()*,  the current thread is assumed, and like the
-first form, but we use get the current frame.
-
-The fourth form, *get(n)*, like the third form, we assume the current
-thread.  And like the first form we go back we try to back a
-Fixnum *n*, number of frame.
-
-When count *n* is given, 1 is synonymous with the previous frame. If *n* is negative, we count from the bottom of the frame stack.
-
-In all cases we return a RubyVM::Frame or *nil* if we can't go back (or forward for a negative *n*) that many frames.
-
-*FrameError* can be raised if the frame object is no longer valid.
-
-All of the following are equivalent
-
-    :::ruby
-    RubyVM::Frame::get(Thread::current) #     -> RubyVM::Frame object
-    RubyVM::Frame::get(Thread::current, 0)
-    RubyVM::Frame::get
-    RubyVM::Frame::get(0)
-
-

 ### #getlocal(index) => Object

 Returns the local variable at the given stack index. The values of local variables in the Ruby MRI indexed by number. This method retrieves the value of a local variable by number.

Call Frame modified by Rocky Bernstein

Rocky Bernstein — Wed, 11 Mar 2015 21:05:31 -0000

--- v15
+++ v16
@@ -57,8 +57,9 @@
     irb$ proc { | a=1 | eval("a+2", RubyVM::Frame::get.binding ) }.call
    => 3

-

+
 ### get() -> RubyVM::Frame object
+

 In contrast to most of the other methods, this is a class method.

@@ -94,7 +95,6 @@
     RubyVM::Frame::get(Thread::current, 0)
     RubyVM::Frame::get
     RubyVM::Frame::get(0)
-

 

 ### #getlocal(index) => Object
@@ -196,7 +196,7 @@
 

 ### #prev(n=1) -> Frame

-Returns a *RubyVM::Frame* object for the frame prior to the Frame object or +nil+ if there is none. Setting *n* to 0 just returns the object passed.  A negative number starts from the end. So prev(-1) is the top frame. Counts outside of the range of `[-stack_size* ..  stack_size-1]` exceed the the range of the stack and return *nil* See also [Call Frame#get()]
+Returns a *RubyVM::Frame* object for the frame prior to the Frame object or +nil+ if there is none. Setting *n* to 0 just returns the object passed.  A negative number starts from the end. So prev(-1) is the top frame. Counts outside of the range of `[-stack_size* ..  stack_size-1]` exceed the the range of the stack and return *nil* See also get()

 *FrameError* can be raised if the frame object is no longer valid.

@@ -207,7 +207,7 @@
 *FrameError* can be raised if the frame object is no longer valid.

 

-### #source_container() -> [String, Object, [,String]]
+### #source_container() -> \[String, Object, \[,String\]\]

 Returns a tuple representing

Call Frame modified by Rocky Bernstein

Rocky Bernstein — Wed, 11 Mar 2015 12:53:05 -0000

--- v14
+++ v15
@@ -1,18 +1,18 @@
+__Note: we describe the Frame object for used in 2.1.5; this is a little different form object in 1.9.3.__
+
+A big change I've made, is access to the call stack, or call frame. This is done via the object *RubyVM::Frame*.
+
+Information here overlaps with [Thread::Backtrace::Location](http://ruby-doc.org/core-2.2.0/Thread/Backtrace/Location.html), but frame objects can access dynamic information. Thread::Backtrace::Location object is confined to static information around a backtrace at a given point of time.
+
+For example, one method on the frame object is *binding()* which returns a [Binding](http://ruby-doc.org/core-2.2.0/Binding.html) object. Over the course of execution, values available to the frame may change and new objects may get added; the *binding()* method will track those changes, and can all you to set variables in the context of the frame as well.
+
+Since a frame tracks dynamic call-stack information, it is meaningful only while that frame is active. I have put in checks in methods using frames to test that the frame is still valid. However these checks aren't foolprool. You shouldn't save frames in variables which have a lifetime longer than the lifetime of the frame it refers to. If you do, either the check will raise an error that the frame is invalid, or you will get garbage information back, or possibly a system crash.
+
 [TOC]

-__Note: we describe the Frame object for used in 2.1.5; this is a little different form object in 1.9.3.__
-
-A big change I've made, is access to the call stack, or call frame. This is done via the object *RubyVM::Frame*.
-
-Information here overlaps with [Thread::Backtrace::Location](http://ruby-doc.org/core-2.2.0/Thread/Backtrace/Location.html), but frame objects can access dynamic information. Thread::Backtrace::Location object is confined to static information around a backtrace at a given point of time.
-
-For example, one method on the frame object is *binding()* which returns a [Binding](http://ruby-doc.org/core-2.2.0/Binding.html) object. Over the course of execution, values available to the frame may change and new objects may get added; the *binding*()* method will track those changes, and can all you to set variables in the context of the frame as well.
-
-Since a frame tracks dynamic call-stack information, it is meaningful only while that frame is active. I have put in checks in methods using frames to test that the frame is still valid. However these checks aren't foolprool. You shouldn't save frames in variables which have a lifetime longer than the lifetime of the frame it refers to. If you do, either the check will raise an error that the frame is invalid, or you will get garbage information back, or possibly a system crash.
-
 ## Frame Methods

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

 Returns the number of arguments that were actually passed in the call to this frame. This often the same value as *arity()*, but differs when arity can take optional or "splat"ted parameters.

@@ -29,7 +29,7 @@
    => 2

 

-### arity() -> Fixnum
+### #arity() -> Fixnum

 Returns the number of arguments that would not be ignored. See Ruby 2.1 [proc#arity](http://ruby-doc.org/core-2.2.0/Proc.html#method-i-arity)

@@ -46,7 +46,7 @@
    => 2

 

-### binding() -> Binding
+### #binding() -> Binding

 Returns a [Binding](http://ruby-doc.org/core-2.2.0/Binding.html) object for
 the frame.
@@ -58,7 +58,9 @@
    => 3

 

-### get()
+### get() -> RubyVM::Frame object
+
+In contrast to most of the other methods, this is a class method.

     :::ruby
     RubyVM::Frame::get(thread)     -> RubyVM::Frame object
@@ -95,7 +97,7 @@

 

-### getlocal(index) => Object
+### #getlocal(index) => Object

 Returns the local variable at the given stack index. The values of local variables in the Ruby MRI indexed by number. This method retrieves the value of a local variable by number.

@@ -106,7 +108,7 @@
    => "ab"

 

-### iseq()
+### #iseq()

 Returns an Ruby VM instruction sequence object create from the Frame object or *nil* if there is none. Note that frames associated with calls to C functions do not Ruby VM instructions sequences.

@@ -138,7 +140,7 @@
     0027 leave

 

-### klass()
+### #klass()

 Returns the class (if any) associated with the frame.
@@ -147,7 +149,7 @@

 

-### label() -> String or nil
+### #label() -> String or nil

 Returns the name of the frame.

@@ -160,14 +162,14 @@
     => "foo"

 

-### method() -> String or nil
+### #method() -> String or nil

 Returns the method associated with the frame or *nil* of none.

 *FrameError* can be raised if the frame object is no longer valid.

 

-### pc_offset() -> Fixnum
+### #pc_offset() -> Fixnum

 Returns the offset inside the instruction sequence or -1 if invalid. Note that C frames do not have VM instruction sequences associated with them.

@@ -178,7 +180,7 @@
     => [23, 27]

 

-### pc_offset=(Fixnum)
+### #pc_offset=(Fixnum)

 Sets Ruby VM PC to the offset given. This is pretty dangerous.
 It is the way a debugger can implement skipping over statements.
@@ -192,20 +194,20 @@
 *FrameError* can be raised if the frame object is no longer valid.

 

-### prev(n=1) -> Frame
+### #prev(n=1) -> Frame

 Returns a *RubyVM::Frame* object for the frame prior to the Frame object or +nil+ if there is none. Setting *n* to 0 just returns the object passed.  A negative number starts from the end. So prev(-1) is the top frame. Counts outside of the range of `[-stack_size* ..  stack_size-1]` exceed the the range of the stack and return *nil* See also [Call Frame#get()]

 *FrameError* can be raised if the frame object is no longer valid.

 

-### setlocal
+### #setlocal

 Sets the local variable at the given stack index. The values of local variables in the Ruby MRI indexed by number.
 *FrameError* can be raised if the frame object is no longer valid.

 

-### source_container() -> [String, Object, [,String]]
+### #source_container() -> [String, Object, [,String]]

 Returns a tuple representing

@@ -222,7 +224,7 @@
 *FrameError* can be raised if the frame object is no longer valid.

 

-### source_location() -> Array
+### #source_location() -> Array

 Returns an array of source location positions that match
 tf.instruction_offset. A source location here is a line number, a Fixnum. In the future we may want to change that to a pair of line and column numbers or byte offset in the file, or interval of start end locations.
@@ -236,7 +238,7 @@
    => [1]

 

-### sp()
+### #sp()

     RubyVM::Frame#sp(n)  -> Object

@@ -249,44 +251,38 @@
    => 20

 

-### sp_set(n, new_value) -> Object
+### #sp_set(n, new_value) -> Object

 Sets VM stack position *n*to *new_value*. The top object is position 0. 1 is the next object.

 *FrameError* can be raised if the frame object is no longer valid.

 

-### sp_size() -> Fixnum
-
-Returns the number of stack or sp entries in the current frame. That is the, number values that have been pushed onto the stack since the current call.  This is different than*RubyVM::Frame#stack_size()* which counts the number of frames in the call stack. *nil* is returned if there is an error.
-
-*FrameError* can be raised if the frame object is no longer valid.
-

-### sp_size()
-
-Returns the number of VM stack pointer entries in the current frame. This is the number of values that have been pushed onto the stack since the current call.  This is different than *RubyVM::Frame#stack_size()* which counts the number of frames in the call stack. *nil* is returned if there is an error.
-
-*FrameError* can be raised if the frame object is no longer valid.
-

-### step_out()
+### #sp_size() -> Fixnum
+
+Returns the number of stack or sp entries in the current frame. This is the number values that have been pushed onto the stack since the current call.  This is different than*RubyVM::Frame#stack_size()* which counts the number of frames in the call stack. *nil* is returned if there is an error.
+
+*FrameError* can be raised if the frame object is no longer valid.
+

+### #step_out()

 Assists in a debugger implementing a "step out" command by turning off any tracing for this call frame and any call frames that are called from this frame.

 *FrameError* can be raised if the frame object is no longer valid.
 

-### step_over()
+### #step_over()

 Assists in a debugger implementing a "step oover" command by turning off any tracing for ny call frames that are called from this frame.

 *FrameError* can be raised if the frame object is no longer valid.
 

-### thread()
+### #thread()

 Returns the [Thread](http://ruby-doc.org/core-2.2.0/Thread.html) object for the call frame.

 *FrameError* can be raised if the frame object is no longer valid.
 

-### valid? -> boolean
+### #valid? -> boolean

 Returns *true* if the frame is no longer valid. On the other hand, since the test we use is weak, returning false might not mean the frame is valid, just that we can't disprove that it is not invalid.

Call Frame modified by Rocky Bernstein

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

--- v13
+++ v14
@@ -1,6 +1,6 @@
 [TOC]

-__Note: we describe the Frame object for used in 2.1.5; this is a  little different form object in 1.9.3.__
+__Note: we describe the Frame object for used in 2.1.5; this is a little different form object in 1.9.3.__

 A big change I've made, is access to the call stack, or call frame. This is done via the object *RubyVM::Frame*.

@@ -8,13 +8,13 @@

 For example, one method on the frame object is *binding()* which returns a [Binding](http://ruby-doc.org/core-2.2.0/Binding.html) object. Over the course of execution, values available to the frame may change and new objects may get added; the *binding*()* method will track those changes, and can all you to set variables in the context of the frame as well.

-Since a frame tracks dynamic call-stack information, it is meaningful only while that frame is active. I have put in checks in methods using frames to test that the frame is still valid. However these checks aren't foolprool. Generally speaking, you shouldn't save frames in variables which have a lifetime longer than the lifetime of the frame it refers to. If you do, either the check will raise an error that the frame is invalid, or yo will get garbage information back, or possibly a system crash.
+Since a frame tracks dynamic call-stack information, it is meaningful only while that frame is active. I have put in checks in methods using frames to test that the frame is still valid. However these checks aren't foolprool. You shouldn't save frames in variables which have a lifetime longer than the lifetime of the frame it refers to. If you do, either the check will raise an error that the frame is invalid, or you will get garbage information back, or possibly a system crash.

 ## Frame Methods

-### argc() -> FixNum
-
-Returns the number of arguments that were actually passed in the call to this frame. This often the same value as *arity()*, but differs  when arity can take optional or "splat"ted parameters.
+### argc() -> Fixnum
+
+Returns the number of arguments that were actually passed in the call to this frame. This often the same value as *arity()*, but differs when arity can take optional or "splat"ted parameters.

 *FrameError* can be raised if the frame object is no longer valid.

@@ -29,7 +29,7 @@
    => 2

 

-### arity() -> FixNum
+### arity() -> Fixnum

 Returns the number of arguments that would not be ignored. See Ruby 2.1 [proc#arity](http://ruby-doc.org/core-2.2.0/Proc.html#method-i-arity)

@@ -70,14 +70,14 @@
 for the [Thread](http://ruby-doc.org/core-2.2.0/Thread.html) object
 passed. This is the current frame, [Thread::current](http://ruby-doc.org/core-2.2.0/Thread.html#method-c-current).

-In the second form, *get(thread, n)* we try to go back that FixNum *n* frames.
+In the second form, *get(thread, n)* we try to go back that Fixnum *n* frames.

 In the the third form, *get()*,  the current thread is assumed, and like the
 first form, but we use get the current frame.

 The fourth form, *get(n)*, like the third form, we assume the current
 thread.  And like the first form we go back we try to back a
-FixNum *n*, number of frame.
+Fixnum *n*, number of frame.

 When count *n* is given, 1 is synonymous with the previous frame. If *n* is negative, we count from the bottom of the frame stack.

@@ -113,7 +113,7 @@
 *FrameError* can be raised if the frame object is no longer valid.

     :::ruby
-    irb$ puts proc { || a = 'ab'; RubyVM::Frame::get.iseq.disassemble  }.call
+    irb$ puts proc { || a = 'ab'; RubyVM::Frame::get.iseq.disassemble }.call
     <{ || a = 'ab'; RubyVM::Frame::get.iseq.disassemble  }.call
     == disasm: <RubyVM::InstructionSequence:block in="" irb_binding@(irb)="">=====
     == catch table
@@ -122,7 +122,7 @@
     |------------------------------------------------------------------------
     local table (size: 2, argc: 0 [opts: 0, rest: -1, post: 0, block: -1, keyword: 0@3] s1)
     [ 2] a
-    0000 trace            4096                                            (   1)
+    0000 trace            4096 (   1)
     0002 trace            1
     0004 putstring        "ab"
     0006 setlocal_OP__WC__0 2
@@ -167,41 +167,127 @@
 *FrameError* can be raised if the frame object is no longer valid.

 

-### pc
-

-### pc_offset
-

-### prev()
+### pc_offset() -> Fixnum
+
+Returns the offset inside the instruction sequence or -1 if invalid. Note that C frames do not have VM instruction sequences associated with them.
+
+*FrameError* can be raised if the frame object is no longer valid.
+
+    :::ruby
+     proc { || f = RubyVM::Frame::get; [f.pc_offset, f.pc_offset] }.call
+    => [23, 27]
+
+

+### pc_offset=(Fixnum)
+
+Sets Ruby VM PC to the offset given. This is pretty dangerous.
+It is the way a debugger can implement skipping over statements.
+
+You need to make sure set this to a valid instruction offset since
+little checking is done.
+
+Note that C frames do not have VM instruction sequences
+associated with them.
+
+*FrameError* can be raised if the frame object is no longer valid.
+
+

+### prev(n=1) -> Frame
+
+Returns a *RubyVM::Frame* object for the frame prior to the Frame object or +nil+ if there is none. Setting *n* to 0 just returns the object passed.  A negative number starts from the end. So prev(-1) is the top frame. Counts outside of the range of `[-stack_size* ..  stack_size-1]` exceed the the range of the stack and return *nil* See also [Call Frame#get()]
+
+*FrameError* can be raised if the frame object is no longer valid.
+
 

 ### setlocal
-

-### source_container
-

-### source_location
+
+Sets the local variable at the given stack index. The values of local variables in the Ruby MRI indexed by number.
+*FrameError* can be raised if the frame object is no longer valid.
+
+

+### source_container() -> [String, Object, [,String]]
+
+Returns a tuple representing
+
+* a kind of container
+* a name of thing inside the container
+* an optional absolute path if the container is a file.
+
+A container represents where where the code that is getting run comes from. Most Ruby programs of course come from reading in a Ruby source-code file. In that case, the container would be "file", and the second entry in the tuple is the name of a file. The 3rd and last parameter here is the absolute name of the file. Note that even though the type may be "file" and the second parameter is a file name, sometimes it is not Ruby source code. The trepanning debugger performs and additional test to make sure a filename given pack is a Ruby file.
+
+However somtimes, code comes from *eval*'ing a string. In that container is "string". If that's the case, the value of the string is probably somewhere on the call stack. The trepanning debugger picks this value out from the stack. What is stored as the filename may be somewhat arbitrary.
+
+Finally, it could be the case that the code running comes from some Dynamically linked code. Here, the container type is "binary". Here the second parameter is the machine address, and one can use this inside say *gdb* to get the function name.
+
+*FrameError* can be raised if the frame object is no longer valid.
+
+

+### source_location() -> Array
+
+Returns an array of source location positions that match
+tf.instruction_offset. A source location here is a line number, a Fixnum. In the future we may want to change that to a pair of line and column numbers or byte offset in the file, or interval of start end locations.
+
+But why do we return an array? Underneath you are stopped at an instruction. In the presence of compiler optimization and common-subexpression elimination, an instruction may map to several different positions in the Ruby source code. In the MRI VM specifically, I don't believe this can happen. But it doesn't hurt to handle the general case.
+
+*FrameError* can be raised if the frame object is no longer valid.
+
+    :::ruby
+   proc { || f = RubyVM::Frame::get.source_location }.call
+   => [1]
+
 

 ### sp()

     RubyVM::Frame#sp(n)  -> Object

-The MRI VM stores interediate values on a stack; *sp()* will retrieve
-the object given position *n*; 0 is the top object, 1 the next-to-top
-object and so on.
+The MRI VM stores interediate values on a stack; *sp()* will retrieve the object given position *n*; 0 is the top object, 1 the next-to-top object and so on.
+
+*FrameError* can be raised if the frame object is no longer valid.

     :::ruby
    irb $ proc { || 10 + RubyVM::Frame::get.sp(1)  }.call()
    => 20

 

-### sp_set
-

-### sp_size
-

-### sp_size
-

-### step_out
-

-### step_over
-

-### thread
-

-### valid?
+### sp_set(n, new_value) -> Object
+
+Sets VM stack position *n*to *new_value*. The top object is position 0. 1 is the next object.
+
+*FrameError* can be raised if the frame object is no longer valid.
+
+

+### sp_size() -> Fixnum
+
+Returns the number of stack or sp entries in the current frame. That is the, number values that have been pushed onto the stack since the current call.  This is different than*RubyVM::Frame#stack_size()* which counts the number of frames in the call stack. *nil* is returned if there is an error.
+
+*FrameError* can be raised if the frame object is no longer valid.
+

+### sp_size()
+
+Returns the number of VM stack pointer entries in the current frame. This is the number of values that have been pushed onto the stack since the current call.  This is different than *RubyVM::Frame#stack_size()* which counts the number of frames in the call stack. *nil* is returned if there is an error.
+
+*FrameError* can be raised if the frame object is no longer valid.
+

+### step_out()
+
+Assists in a debugger implementing a "step out" command by turning off any tracing for this call frame and any call frames that are called from this frame.
+
+*FrameError* can be raised if the frame object is no longer valid.
+

+### step_over()
+
+Assists in a debugger implementing a "step oover" command by turning off any tracing for ny call frames that are called from this frame.
+
+*FrameError* can be raised if the frame object is no longer valid.
+

+### thread()
+
+Returns the [Thread](http://ruby-doc.org/core-2.2.0/Thread.html) object for the call frame.
+
+*FrameError* can be raised if the frame object is no longer valid.
+

+### valid? -> boolean
+
+Returns *true* if the frame is no longer valid. On the other hand, since the test we use is weak, returning false might not mean the frame is valid, just that we can't disprove that it is not invalid.
+
+You shouldn't save frames in variables which have a lifetime longer than the lifetime of the frame it refers to. If you do, either the check will raise an error that the frame is invalid, or you will get garbage information back, or possibly a system crash.

Call Frame modified by Rocky Bernstein

Rocky Bernstein — Mon, 09 Mar 2015 21:53:40 -0000

--- v12
+++ v13
@@ -4,7 +4,7 @@

 A big change I've made, is access to the call stack, or call frame. This is done via the object *RubyVM::Frame*.

-Information here overlaps with [Thread::Backtrace::Location](http://ruby-doc.org/core-2.2.0/Thread/Backtrace/Location.html), but frame objects can access dynamic information. Thread::Backtrace::Location object is confined to static information around a backtrace at a given point of time. 
+Information here overlaps with [Thread::Backtrace::Location](http://ruby-doc.org/core-2.2.0/Thread/Backtrace/Location.html), but frame objects can access dynamic information. Thread::Backtrace::Location object is confined to static information around a backtrace at a given point of time.

 For example, one method on the frame object is *binding()* which returns a [Binding](http://ruby-doc.org/core-2.2.0/Binding.html) object. Over the course of execution, values available to the frame may change and new objects may get added; the *binding*()* method will track those changes, and can all you to set variables in the context of the frame as well.

@@ -14,28 +14,36 @@

 ### argc() -> FixNum

-Returns the number of arguments that were actually passed in the call to this frame. This often the same value as *arity()*, but differs  when arity can take optional or "splat"ted parameters. 
-
-*FrameError* can be raised if the threadframe object is no longer valid.
-
-    :::ruby
-    proc { || RubyVM::Frame::get.argc }.call  # => 0
-    proc { |a| RubyVM::Frame::get.argc }.call # => 1
-    proc { |a,*b| RubyVM::Frame::get.argc }.call # => 1
-    proc { |a,b| RubyVM::Frame::get.argc }.call # => 2
+Returns the number of arguments that were actually passed in the call to this frame. This often the same value as *arity()*, but differs  when arity can take optional or "splat"ted parameters.
+
+*FrameError* can be raised if the frame object is no longer valid.
+
+    :::ruby
+    irb$ proc { || RubyVM::Frame::get.argc }.call
+   => 0
+    irb$ proc { |a| RubyVM::Frame::get.argc }.call
+   => 1
+    irb$ proc { |a,*b| RubyVM::Frame::get.argc }.call
+   => 1
+    irb$ proc { |a,b| RubyVM::Frame::get.argc }.call
+   => 2

 

 ### arity() -> FixNum

 Returns the number of arguments that would not be ignored. See Ruby 2.1 [proc#arity](http://ruby-doc.org/core-2.2.0/Proc.html#method-i-arity)

-*FrameError* can be raised if the threadframe object is no longer valid.
-
-    :::ruby
-    proc { || RubyVM::Frame::get.arity }.call  # => 0
-    proc { |a| RubyVM::Frame::get.arity }.call # => 1
-    proc { |a,*b| RubyVM::Frame::get.arity }.call # => -2
-    proc { |a,b| RubyVM::Frame::get.argc }.call # => 2
+*FrameError* can be raised if the frame object is no longer valid.
+
+    :::ruby
+    irb$ proc { || RubyVM::Frame::get.arity }.call
+   => 0
+    irb$ proc { |a| RubyVM::Frame::get.arity }.call
+   => 1
+    irb$ proc { |a,*b| RubyVM::Frame::get.arity }.call
+   => -2
+    irb$ proc { |a,b| RubyVM::Frame::get.argc }.call
+   => 2

 

 ### binding() -> Binding
@@ -43,10 +51,11 @@
 Returns a [Binding](http://ruby-doc.org/core-2.2.0/Binding.html) object for
 the frame.

-*FrameError* can be raised if the threadframe object is no longer valid.
-
-    :::ruby
-    proc { | a=1 | eval("a+2", RubyVM::Frame::get.binding ) }.call
+*FrameError* can be raised if the frame object is no longer valid.
+
+    :::ruby
+    irb$ proc { | a=1 | eval("a+2", RubyVM::Frame::get.binding ) }.call
+   => 3

 

 ### get()
@@ -72,47 +81,47 @@

 When count *n* is given, 1 is synonymous with the previous frame. If *n* is negative, we count from the bottom of the frame stack.

-In all cases we return a RubyVM::Frame or nil if we can't go back (or forward for a negative *n*) that many frames.
-
-*FrameError* can be raised if the threadframe object is no longer valid.
+In all cases we return a RubyVM::Frame or *nil* if we can't go back (or forward for a negative *n*) that many frames.
+
+*FrameError* can be raised if the frame object is no longer valid.

 All of the following are equivalent

     :::ruby
     RubyVM::Frame::get(Thread::current) #     -> RubyVM::Frame object
-    RubyVM::Frame::get(Thread::current, 0) 
+    RubyVM::Frame::get(Thread::current, 0)
     RubyVM::Frame::get
     RubyVM::Frame::get(0)
-    
-
-

-### getlocal(index) => Value
+
+
+

+### getlocal(index) => Object

 Returns the local variable at the given stack index. The values of local variables in the Ruby MRI indexed by number. This method retrieves the value of a local variable by number.

-*FrameError* can be raised if the threadframe object is no longer valid.
-
-
-    :::ruby
-      proc { || a = 'ab'; RubyVM::Frame::get.getlocal(2)  }.call -> 'ab'
+*FrameError* can be raised if the frame object is no longer valid.
+
+    :::ruby
+   irb$ proc { || a = 'ab'; RubyVM::Frame::get.getlocal(2)  }.call
+   => "ab"

 

 ### iseq()

 Returns an Ruby VM instruction sequence object create from the Frame object or *nil* if there is none. Note that frames associated with calls to C functions do not Ruby VM instructions sequences.

-*FrameError* can be raised if the threadframe object is no longer valid.
-
-    :::ruby        
-    irb(main):001:0> puts proc { || a = 'ab'; RubyVM::Frame::get.iseq.disassemble  }.call 
-    <{ || a = 'ab'; RubyVM::Frame::get.iseq.disassemble  }.call 
+*FrameError* can be raised if the frame object is no longer valid.
+
+    :::ruby
+    irb$ puts proc { || a = 'ab'; RubyVM::Frame::get.iseq.disassemble  }.call
+    <{ || a = 'ab'; RubyVM::Frame::get.iseq.disassemble  }.call
     == disasm: <RubyVM::InstructionSequence:block in="" irb_binding@(irb)="">=====
     == catch table
     | catch type: redo   st: 0002 ed: 0025 sp: 0000 cont: 0002
     | catch type: next   st: 0002 ed: 0025 sp: 0000 cont: 0025
     |------------------------------------------------------------------------
     local table (size: 2, argc: 0 [opts: 0, rest: -1, post: 0, block: -1, keyword: 0@3] s1)
-    [ 2] a          
+    [ 2] a
     0000 trace            4096                                            (   1)
     0002 trace            1
     0004 putstring        "ab"
@@ -126,15 +135,15 @@
     0021 opt_send_simple  <callinfo!mid:iseq, argc:0,="" ARGS_SKIP="">
     0023 opt_send_simple  <callinfo!mid:disassemble, argc:0,="" ARGS_SKIP="">
     0025 trace            512
-    0027 leave            
+    0027 leave

 

 ### klass()

-Returns the class (if any) associated with the frame. 
-
-*FrameError* can be raised if the threadframe object is no longer valid.
+Returns the class (if any) associated with the frame.
+
+*FrameError* can be raised if the frame object is no longer valid.

 

@@ -142,16 +151,20 @@

 Returns the name of the frame.

-*FrameError* can be raised if the threadframe object is no longer valid.
-
-    :::ruby
-    irb(main):014:0> proc { || a = 'ab'; RubyVM::Frame::get.label  }.call()
+*FrameError* can be raised if the frame object is no longer valid.
+
+    :::ruby
+    irb$ proc { || a = 'ab'; RubyVM::Frame::get.label  }.call()
     => "block in irb_binding"
     irb(main):005:0> def foo; RubyVM::Frame::get.label ; end; foo
     => "foo"

 

-### method
+### method() -> String or nil
+
+Returns the method associated with the frame or *nil* of none.
+
+*FrameError* can be raised if the frame object is no longer valid.

 

 ### pc
@@ -166,7 +179,18 @@
 

 ### source_location
 

-### sp
+### sp()
+
+    RubyVM::Frame#sp(n)  -> Object
+
+The MRI VM stores interediate values on a stack; *sp()* will retrieve
+the object given position *n*; 0 is the top object, 1 the next-to-top
+object and so on.
+
+    :::ruby
+   irb $ proc { || 10 + RubyVM::Frame::get.sp(1)  }.call()
+   => 20
+
 

 ### sp_set

Call Frame modified by Rocky Bernstein

Rocky Bernstein — Mon, 09 Mar 2015 20:58:28 -0000

--- v11
+++ v12
@@ -1,6 +1,8 @@
+[TOC]
+
 __Note: we describe the Frame object for used in 2.1.5; this is a  little different form object in 1.9.3.__

-A big change I've made, access to the call stack, or call frame. This is done via the object *RubyVM::Frame*.
+A big change I've made, is access to the call stack, or call frame. This is done via the object *RubyVM::Frame*.

 Information here overlaps with [Thread::Backtrace::Location](http://ruby-doc.org/core-2.2.0/Thread/Backtrace/Location.html), but frame objects can access dynamic information. Thread::Backtrace::Location object is confined to static information around a backtrace at a given point of time.

Call Frame modified by Rocky Bernstein

Rocky Bernstein — Mon, 09 Mar 2015 20:43:01 -0000

--- v10
+++ v11
@@ -14,6 +14,8 @@

 Returns the number of arguments that were actually passed in the call to this frame. This often the same value as *arity()*, but differs  when arity can take optional or "splat"ted parameters. 

+*FrameError* can be raised if the threadframe object is no longer valid.
+
     :::ruby
     proc { || RubyVM::Frame::get.argc }.call  # => 0
     proc { |a| RubyVM::Frame::get.argc }.call # => 1
@@ -24,6 +26,8 @@
 ### arity() -> FixNum

 Returns the number of arguments that would not be ignored. See Ruby 2.1 [proc#arity](http://ruby-doc.org/core-2.2.0/Proc.html#method-i-arity)
+
+*FrameError* can be raised if the threadframe object is no longer valid.

     :::ruby
     proc { || RubyVM::Frame::get.arity }.call  # => 0
@@ -36,6 +40,8 @@

 Returns a [Binding](http://ruby-doc.org/core-2.2.0/Binding.html) object for
 the frame.
+
+*FrameError* can be raised if the threadframe object is no longer valid.

     :::ruby
     proc { | a=1 | eval("a+2", RubyVM::Frame::get.binding ) }.call
@@ -66,6 +72,8 @@

 In all cases we return a RubyVM::Frame or nil if we can't go back (or forward for a negative *n*) that many frames.

+*FrameError* can be raised if the threadframe object is no longer valid.
+
 All of the following are equivalent

     :::ruby
@@ -80,6 +88,9 @@

 Returns the local variable at the given stack index. The values of local variables in the Ruby MRI indexed by number. This method retrieves the value of a local variable by number.

+*FrameError* can be raised if the threadframe object is no longer valid.
+
+
     :::ruby
       proc { || a = 'ab'; RubyVM::Frame::get.getlocal(2)  }.call -> 'ab'

@@ -88,6 +99,9 @@

 Returns an Ruby VM instruction sequence object create from the Frame object or *nil* if there is none. Note that frames associated with calls to C functions do not Ruby VM instructions sequences.

+*FrameError* can be raised if the threadframe object is no longer valid.
+
+    :::ruby        
     irb(main):001:0> puts proc { || a = 'ab'; RubyVM::Frame::get.iseq.disassemble  }.call 
     <{ || a = 'ab'; RubyVM::Frame::get.iseq.disassemble  }.call 
     == disasm: <RubyVM::InstructionSequence:block in="" irb_binding@(irb)="">=====
@@ -113,10 +127,26 @@
     0027 leave            

 

-### klass
+### klass()
+
+
+Returns the class (if any) associated with the frame. 
+
+*FrameError* can be raised if the threadframe object is no longer valid.
+

 

-### label
+### label() -> String or nil
+
+Returns the name of the frame.
+
+*FrameError* can be raised if the threadframe object is no longer valid.
+
+    :::ruby
+    irb(main):014:0> proc { || a = 'ab'; RubyVM::Frame::get.label  }.call()
+    => "block in irb_binding"
+    irb(main):005:0> def foo; RubyVM::Frame::get.label ; end; foo
+    => "foo"

 

 ### method

Call Frame modified by Rocky Bernstein

Rocky Bernstein — Mon, 09 Mar 2015 20:18:38 -0000

--- v9
+++ v10
@@ -84,7 +84,33 @@
       proc { || a = 'ab'; RubyVM::Frame::get.getlocal(2)  }.call -> 'ab'

 

-### iseq
+### iseq()
+
+Returns an Ruby VM instruction sequence object create from the Frame object or *nil* if there is none. Note that frames associated with calls to C functions do not Ruby VM instructions sequences.
+
+    irb(main):001:0> puts proc { || a = 'ab'; RubyVM::Frame::get.iseq.disassemble  }.call 
+    <{ || a = 'ab'; RubyVM::Frame::get.iseq.disassemble  }.call 
+    == disasm: <RubyVM::InstructionSequence:block in="" irb_binding@(irb)="">=====
+    == catch table
+    | catch type: redo   st: 0002 ed: 0025 sp: 0000 cont: 0002
+    | catch type: next   st: 0002 ed: 0025 sp: 0000 cont: 0025
+    |------------------------------------------------------------------------
+    local table (size: 2, argc: 0 [opts: 0, rest: -1, post: 0, block: -1, keyword: 0@3] s1)
+    [ 2] a          
+    0000 trace            4096                                            (   1)
+    0002 trace            1
+    0004 putstring        "ab"
+    0006 setlocal_OP__WC__0 2
+    0008 trace            1
+    0010 getinlinecache   19, <is:0>
+    0013 getconstant      :RubyVM
+    0015 getconstant      :Frame
+    0017 setinlinecache   <is:0>
+    0019 opt_send_simple  <callinfo!mid:get, argc:0,="" ARGS_SKIP="">
+    0021 opt_send_simple  <callinfo!mid:iseq, argc:0,="" ARGS_SKIP="">
+    0023 opt_send_simple  <callinfo!mid:disassemble, argc:0,="" ARGS_SKIP="">
+    0025 trace            512
+    0027 leave            

 

 ### klass

Call Frame modified by Rocky Bernstein

Rocky Bernstein — Mon, 09 Mar 2015 19:43:55 -0000

--- v8
+++ v9
@@ -78,7 +78,7 @@
 

 ### getlocal(index) => Value

-Returns the local variable at the given stack index. The values of local variables in the Ruby MRI indexed by number. This method retrieves the value of one
+Returns the local variable at the given stack index. The values of local variables in the Ruby MRI indexed by number. This method retrieves the value of a local variable by number.

     :::ruby
       proc { || a = 'ab'; RubyVM::Frame::get.getlocal(2)  }.call -> 'ab'