rtinspect 0.0.1 → 0.0.19

data/README

@@ -50,16 +50,16 @@ thread's inspection abilities.
     Connected to localhost.
     Escape character is '^]'.
     
-    rtinspect:001:0> local_variables
+    myapp:001:0> local_variables
     => ["rti"]
     
-    rtinspect:002:0> rti.state
+    myapp:002:0> rti.state
     => {:socket=>#<TCPSocket:0xb7cb92d0 127.0.0.1:48720>, :rti=>#<RuntimeInspectionThread::RTIManager:0xb7cb5f18 @tracing_proc=#<Proc:0xb7cbe974@rtinspect.rb:511>, @breakpoints={}, @state={...}>, :cmd_count=>2, :safe_level=>3, :block_count=>0, :block_cmd=>"", :use_yaml=>false, :eval_timeout=>60}
     
-    rtinspect:003:0> rti.state.use_yaml = true
+    myapp:003:0> rti.state.use_yaml = true
     => --- true
     
-    rtinspect:004:0> rti.state
+    myapp:004:0> rti.state
     => --- &id001 !map:RuntimeInspectionThread::State
     :socket: !ruby/object:TCPSocket
       peerstr: 127.0.0.1:48720
@@ -76,24 +76,24 @@ thread's inspection abilities.
     :use_yaml: true
     :eval_timeout: 60
     
-    rtinspect:005:0> rti.state.block_count = 1
+    myapp:005:0> rti.state.block_count = 1
     => --- 1
     
-    rtinspect:006:1> 2.times do
-    rtinspect:007:1> |i|
-    rtinspect:008:1> p i
-    rtinspect:009:1> end
-    rtinspect:010:1>
+    myapp:006:1> 2.times do
+    myapp:007:1> |i|
+    myapp:008:1> p i
+    myapp:009:1> end
+    myapp:010:1>
     0
     1
     => --- 2
     
-    rtinspect:011:2> exit
-    rtinspect:012:2>
+    myapp:011:2> exit
+    myapp:012:2>
     => --- !ruby/exception:SystemExit
     message: "(eval):1:in `exit': exit"
     
-    rtinspect:013:3> ^]
+    myapp:013:3> ^]
     
     telnet> quit
     Connection closed.
@@ -114,7 +114,7 @@ value increases each time a full block is evaluated.
 Here's what happened on the server's side (note, it's running with
 debug enabled so we can see the details):
 
-    $ ruby -d rtinspect.rb
+    $ ruby -d -Ilib test/myapp.rb
     Runtime inspection available at localhost:56789
     Connection established with 127.0.0.1:48720
     Executing [3]: local_variables
@@ -142,57 +142,57 @@ what might be expected.
     Connected to localhost.
     Escape character is '^]'.
     
-    rtinspect:001:0> .bp_add Foo#bar
+    myapp:001:0> .bp_add Foo#bar
     => "Added breakpoint 1"
     
-    rtinspect:002:0> start_foo
+    myapp:002:0> start_foo
     => #<Thread:0xb7d22974 sleep>
     
-    rtinspect:003:0> .bp_start
+    myapp:003:0> .bp_start
     => nil
     
-    Breakpoint 1 in Foo#bar from rtinspect.rb:919 (call)
-    rtinspect:004:0> local_variables
+    Breakpoint 1 in Foo#bar from myapp.rb:10 (call)
+    myapp:004:0> local_variables
     => ["b", "rti"]
     
-    Breakpoint 1 in Foo#bar from rtinspect.rb:919 (call)
-    rtinspect:005:0> b
+    Breakpoint 1 in Foo#bar from myapp.rb:10 (call)
+    myapp:005:0> b
     => nil
     
-    Breakpoint 1 in Foo#bar from rtinspect.rb:919 (call)
-    rtinspect:006:0> b = 1003
+    Breakpoint 1 in Foo#bar from myapp.rb:10 (call)
+    myapp:006:0> b = 1003
     => 1003
     
-    Breakpoint 1 in Foo#bar from rtinspect.rb:919 (call)
-    rtinspect:007:0> @a
+    Breakpoint 1 in Foo#bar from myapp.rb:10 (call)
+    myapp:007:0> @a
     => 3
     
-    Breakpoint 1 in Foo#bar from rtinspect.rb:919 (call)
-    rtinspect:008:0> @a = 11
+    Breakpoint 1 in Foo#bar from myapp.rb:10 (call)
+    myapp:008:0> @a = 11
     => 11
     
-    Breakpoint 1 in Foo#bar from rtinspect.rb:919 (call)
-    rtinspect:009:0> .bp_next
+    Breakpoint 1 in Foo#bar from myapp.rb:10 (call)
+    myapp:009:0> .bp_next
     => nil
     
-    Breakpoint 1 in Foo#bar from rtinspect.rb:920 (line)
-    rtinspect:010:0> .bp_continue
+    Breakpoint 1 in Foo#bar from myapp.rb:11 (line)
+    myapp:010:0> .bp_continue
     => nil
     
-    Breakpoint 1 in Foo#bar from rtinspect.rb:919 (call)
-    rtinspect:011:0> b
+    Breakpoint 1 in Foo#bar from myapp.rb:10 (call)
+    myapp:011:0> b
     => nil
     
-    Breakpoint 1 in Foo#bar from rtinspect.rb:919 (call)
-    rtinspect:012:0> p @a
+    Breakpoint 1 in Foo#bar from myapp.rb:10 (call)
+    myapp:012:0> p @a
     12
     => nil
     
-    Breakpoint 1 in Foo#bar from rtinspect.rb:919 (call)
-    rtinspect:013:0> .bp_stop
+    Breakpoint 1 in Foo#bar from myapp.rb:10 (call)
+    myapp:013:0> .bp_stop
     => nil
     
-    rtinspect:014:0> ^]
+    myapp:014:0> ^]
     
     telnet> quit
     Connection closed.
@@ -210,7 +210,7 @@ begins printing out the value of its member variable, @a. Notice that
 the value jumps from 2 to 11 after the breakpoint is hit and the
 client has adjusted the value.
 
-    $ ruby -d rtinspect.rb
+    $ ruby -d -Ilib test/myapp.rb
     Runtime inspection available at localhost:56789
     Connection established with 127.0.0.1:40202
     Executing [3]: start_foo
@@ -243,33 +243,33 @@ it using methods added to the object dynamically.
     Connected to localhost.
     Escape character is '^]'.
     
-    rtinspect:001:0> start_foo
+    myapp:001:0> start_foo
     => #<Thread:0xb7d11d04 sleep>
     
-    rtinspect:002:0> f = rti.get_object('Foo')
+    myapp:002:0> f = rti.get_object('Foo')
     => #<Foo:0xb7d116b0 @a=2>
     
-    rtinspect:003:0> rti.state.block_count = 1
+    myapp:003:0> rti.state.block_count = 1
     => 1
     
-    rtinspect:004:1> def f.seeit
-    rtinspect:005:1> @a
-    rtinspect:006:1> end
-    rtinspect:007:1>
+    myapp:004:1> def f.seeit
+    myapp:005:1> @a
+    myapp:006:1> end
+    myapp:007:1>
     => nil
     
-    rtinspect:008:2> f.seeit
-    rtinspect:009:2>
+    myapp:008:2> f.seeit
+    myapp:009:2>
     => 11
     
-    rtinspect:010:3> ^]
+    myapp:010:3> ^]
     
     telnet> quit
     Connection closed.
 
 No surprises from the server...
 
-    $ ruby -d rtinspect.rb
+    $ ruby -d -Ilib test/myapp.rb
     Runtime inspection available at localhost:56789
     Connection established with 127.0.0.1:45689
     Executing [3]: start_foo
@@ -297,6 +297,40 @@ No surprises from the server...
     Cleaning up 127.0.0.1:45689
     Closed connection from 127.0.0.1:45689
 
+==== Inserting RTI Dynamically
+
+Now, imagine that you have a Ruby process running that did not require
+or load RTI on its own. Here's how to insert it live without stopping
+and restarting the process. First, we start up a process without RTI...
+
+    $ ruby -d -Ilib test/myapp.rb noload
+    Running as 26061
+
+...then we use the {rti helper script}[link:files/bin/rti.html] to load
+in RTI...
+
+    $ bin/rti -load lib 26061
+    Loaded lib/rtinspect.rb in process 26061
+
+...which does this in the myapp.rb process...
+
+    Running as 26061
+    true
+    Runtime inspection available at localhost:56789
+    #<RuntimeInspection::Thread:0xb79f9874 sleep []>
+
+...and now we telnet to RTI just like the previous examples...
+
+    $ telnet localhost 56789
+    Trying 127.0.0.1...
+    Connected to localhost.
+    Escape character is '^]'.
+    
+    myapp:001:0> local_variables
+    => ["a", "b", "rti"]
+    
+    myapp:002:0> 
+
 = RTI Use
 
 RTI can be distributed via the same kind of terms as the {Ruby

data/TODO

@@ -21,16 +21,27 @@
 * The binding should probably be part of the client connection state
   and not global to the main thread.
 
-* Cleanup not happening when client exits while at a stoppoint.
-
-* Add RuntimeInspectionThread.on_signal method to self-invoke when
-  given a signal (toggle).
-
-* Add helper to default output into a file.
-
 * Add support to open any port but report it to a handler (so it can
   be logged or noted somewhere).
 
 * Write a helper client to provide ease-of-use features like command
   completion, command history, command-line editing, etc
   (i.e. readline).
+
+* Maybe have a way to explicitly mark objects that are "traceable" so
+  that the user can optionally speed up performance so that
+  handle_tracing() will only look at objects that are marked and
+  immediately skip through for any others. Used in conjunction with
+  get_object(), this could be done dynamically (a. get_object; b. mark
+  object; c. add breakpoint; d. start tracing).
+
+* Add comparison of RTI with ruby-breakpoint, ruby-debug, and "ruby
+  --debug" to README.
+
+* Move handle_tracing into the Tracer.
+
+* Add support for bp_disable.
+
+* Add optional support for showing source-code at breakpoints (perhaps
+  managed only by the rti client so we don't bog down the rti
+  library).

data/VERSION

@@ -0,0 +1 @@
+RuntimeInspectionThread v0.0.19

data/bin/rti

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+
+# This is a helper script for working with a process that either needs
+# a RuntimeInspection::Thread or has one.
+#
+# Copyright (c) 2006-2007 Brad Robel-Forrest.
+#
+# This software can be distributed under the terms of the Ruby license
+# as detailed in the accompanying LICENSE[link:files/LICENSE.html]
+# file.
+
+require 'pathname'
+
+def gdb_file( path, port )
+    require 'tempfile'
+
+    if port
+        args = "(#{port})"
+    end
+
+    f = Tempfile.new( 'rti_' )
+    f.write <<EOF
+define eval
+  call(rb_p(rb_eval_string_protect($arg0,(int*)0)))
+end
+eval("load '#{path.realpath}'")
+eval("RuntimeInspection::Thread.new#{args}")
+EOF
+    f.flush
+    return f
+end
+
+if ARGV.empty?
+    $stderr.puts "usage: rti [-load <path_to_rtinspect> <pid>] [<port>]"
+    exit 1
+end
+
+if i = ARGV.index( '-load' )
+    ARGV.delete_at(i)
+    path = Pathname.new( ARGV.delete_at(i) )
+    pid = ARGV.delete_at(i)
+    port = ARGV.shift
+
+    if path.directory?
+        path += 'rtinspect.rb'
+    end
+
+    unless path.exist?
+        $stderr.puts "Unable to find #{path}"
+        exit 1
+    end
+
+    f = gdb_file( path, port )
+    begin
+        unless system( "gdb -n --batch-silent --pid #{pid} -x #{f.path}" )
+            $stderr.puts "Unable to load #{path} in process #{pid}"
+            exit 1
+        end
+    ensure
+        f.close
+    end
+
+    puts "Loaded #{path} in process #{pid}"
+end
+
+# use expect to wait for the prompt (like in the unit tests, but less
+# strict)
+
+# sock = TCPSocket.new( 'localhost', port )

data/lib/rti/manager.rb

@@ -0,0 +1,411 @@
+# Contains the RuntimeInspection::RTIManager.
+#
+# Copyright (c) 2006-2007 Brad Robel-Forrest.
+#
+# This software can be distributed under the terms of the Ruby license
+# as detailed in the accompanying LICENSE[link:files/LICENSE.html]
+# file.
+
+#
+module RuntimeInspection
+
+    # This will be the list of all public instance methods that start
+    # with 'rti_'. These methods are callable from a client's
+    # connection to invoke various helpers remotely (e.g. manipulating
+    # breakpoints as well as other helpful functions). The first
+    # argument to these will always be the state. Remaining arguments
+    # will be whatever strings were obtained from the client.
+    #
+    class RTIManager
+
+        # If this character is used as the first non-whitespace value
+        # in a command, the remaining data will be used to invoke an
+        # RTIManager method directly (outside the eval scope).
+        #
+        CMD_MARKER = ?.
+
+        # Track the list of available commands.
+        #
+        RTI_METHODS = []
+
+        # Used to collect data regarding each breakpoint. The state is
+        # associated with the appropriate client that is waiting for
+        # this breakpoint to be hit.
+        #
+        BreakPoint = Struct.new( :id, :state )
+
+        # Collect all methods that we are willing to expose to a
+        # caller.
+        #
+        def self.method_added( id )
+            RTI_METHODS << id.id2name
+        end
+
+        # Get a new RTIManager
+        #
+        def initialize( breakpoints, tracing_proc, state )
+            @breakpoints = breakpoints
+            @tracing_proc = tracing_proc
+            @state = state
+        end
+
+        # Get the list of RTI commands available.
+        #
+        def list
+            RTI_METHODS.sort
+        end
+
+        # Get the state information for this client.
+        #
+        def state
+            @state
+        end
+
+        # Given a name, return the real class object. Returns the
+        # first one found unless an explicit "path" is provided via ::
+        # designators.
+        #
+        def name2class( name )
+            if name.include?( '::' )
+                ObjectSpace.each_object( Class ) do |c|
+                    return c if name == c.name
+                end
+            else
+                ObjectSpace.each_object( Class ) do |c|
+                    return c if c.name.match( /#{name}$/ )
+                end
+            end
+            return nil
+        end
+
+        # Very simple helper to assist caller in retrieving a specific
+        # object. This will return the first one found. Anything
+        # requiring more complicated decision logic about what object
+        # to return should use ObjectSpace directly.
+        #
+        # +name+:: The object's class or name (uses #name2class for
+        #          the latter).
+        #
+        def get_object( name )
+            if name.kind_of? String
+                return nil unless c = name2class(name)
+            else
+                c = name
+            end
+            ObjectSpace.each_object( c ) {|obj| return obj}
+            return nil
+        end
+
+        # Stop all other threads except the
+        # RuntimeInsepction::Thread. Be careful. This will stop any
+        # new connections as well.
+        #
+        def stop_world
+            ::Thread.critical = true
+        end
+
+        # Start all other threads up again.
+        #
+        def start_world
+            ::Thread.critical = false
+        end
+
+        # Convenience method for what is essentially caller. The
+        # argument specifies the number of calls to report.
+        #
+        def backtrace( calls=5 )
+            caller[1..calls]
+        end
+
+        # Convenience method for listing threads in the system. The
+        # first value reported is the thread's object_id which can be
+        # used in bp_attach and bp_add. Only threads that do not have
+        # :thread_name keys that start with 'rti_' are shown.
+        #
+        def threads
+            tl = Thread.list.collect do |th|
+                unless( th[:thread_name].to_s.match( /^rti_/ ) or
+                        th.kind_of?( Thread ))
+                    th
+                end
+            end
+            tl.compact!
+            return tl
+        end
+
+        # Expression for splitting apart a user-supplied BreakPoint in
+        # bp_add.
+        #
+        BP_RE = Regexp.new( /^((.+):(\d+)|((.+)\#)?(.*?))(>(.+))?$/ )
+
+        # Add a new BreakPoint. Execution will not stop at any
+        # BreakPoints until bp_start is called. The argument
+        # should use one of the following forms:
+        #
+        # * Class#method
+        # * Module#method
+        # * method
+        # * file:line
+        # * Append >thread to any of the above
+        #
+        # In the first three forms, the BreakPoint will stop on the
+        # 'call' event into that method.
+        #
+        # The last form enables a BreakPoint to be declared for a
+        # particular thread. The thread value may either be an
+        # object_id (see #threads) or it's name as defined by the
+        # thread's :thread_name key.
+        #
+        # Once a BreakPoint is stopped in a thread, bp_finish,
+        # bp_next, and bp_step will act inside that thread. When
+        # bp_continue is called, the next BreakPoint to be hit
+        # regardless of the thread will be the StopPoint.
+        #
+        # Note that even though a particular sequence of StopPoints is
+        # thread-specific, that doesn't mean that some other generic
+        # BreakPoint might be hit and stop processing elsewhere. This
+        # can be mitigated by using the thread-specific BreakPoints.
+        #
+        def bp_add( key )
+            if bp = @breakpoints[key]
+                return "Breakpoint already held as #{bp.id} by " +
+                    "#{bp.state.socket}"
+            end
+
+            unless m = key.match( BP_RE )
+                return "Unable to parse #{key}"
+            end
+
+            file = m[2]
+            line = m[3]
+            cont = m[5]
+            meth = m[6]
+            thread = m[8]
+
+            if meth and meth.empty?
+                meth = nil
+            end
+
+            if cont
+                ObjectSpace.each_object( Class ) do |c|
+                    if c.name == cont
+                        cont = c
+                        break
+                    end
+                end
+                if cont.kind_of?( String )
+                    ObjectSpace.each_object( Module ) do |m|
+                        if m.name == cont
+                            cont = m
+                            break
+                        end
+                    end
+                end
+                if cont.kind_of?( String )
+                    return "Unable to find matching module or class " +
+                        "for #{cont}"
+                end
+            end
+
+            if meth
+                if cont
+                    unless( cont.instance_methods.include?( meth ) or
+                            cont.methods.include?( meth ))
+                        return "Unable to find #{meth} method in #{cont}"
+                    end
+                else
+                    ObjectSpace.each_object( Class ) do |c|
+                        if( c.instance_methods.include?( meth ) or
+                            c.methods.include?( meth ))
+                            cont = c
+                            break
+                        end
+                    end
+                    unless cont
+                        ObjectSpace.each_object( Module ) do |m|
+                            if( m.instance_methods.include?( meth ) or
+                                m.methods.include?( meth ))
+                                cont = m
+                                break
+                            end
+                        end
+                    end
+                    unless cont
+                        return "Unable to find containing class or module " +
+                            "for #{meth}"
+                    end
+                end
+            end
+
+            if thread
+                key.sub!( />.+$/, ">#{get_thread_id(thread)}" )
+            end
+
+            return real_bp_add( key )
+        end
+
+        # Delete a breakpoint.
+        #
+        def bp_delete( id )
+            id = id.to_i
+            ret = "Unable to find breakpoint #{id}"
+            @breakpoints.delete_if do |key, bp|
+                if bp.id == id and bp.state == @state
+                    ret = "Deleted breakpoint #{id}"
+                    true
+                end
+            end
+            return ret
+        end
+
+        # List all the breakpoints.
+        #
+        def bp_list( show_all=false )
+            ordered = @breakpoints.sort do |a, b|
+                a[1].id <=> b[1].id
+            end
+            ordered.collect do |key, bp|
+                next unless show_all or bp.state == @state
+                if show_all and bp.state != @state
+                    post = " (#{bp.state.socket})"
+                end
+                "#{bp.id}: #{key}#{post}"
+            end.compact
+        end
+
+        # Start tracing looking for breakpoints to stop at.
+        #
+        def bp_start
+            if @breakpoints.empty?
+                return "No breakpoints set"
+            end
+            bp_stop
+            set_trace_func( @tracing_proc )
+            @state.bp_portal = @state.bp_waiting.pop
+            return nil
+        end
+
+        # Stop tracing for breakpoints.
+        #
+        def bp_stop
+            unless @state.bp_portal
+                return "Not stopped at a breakpoint"
+            end
+            @state.bp_portal.cmds << :stop
+            @state.delete( :bp_portal )
+            return nil
+        end
+
+        # Continue tracing waiting for the very next call inside the
+        # specified thread. The thread value to use is either the
+        # thread's name (as available in the thread's :thread_name
+        # key) or the thread's object_id.
+        #
+        def bp_attach( thread )
+            # Need to stop any current tracing that may be running.
+            bp_stop
+            ret = bp_add( ">#{thread}" )
+            unless ret.match( /^Added / )
+                return ret
+            end
+            bp_start
+        end
+
+        # Continue tracing from current position waiting for next
+        # breakpoint to hit.
+        #
+        def bp_continue
+            unless @state.bp_portal
+                return "Not stopped at a breakpoint"
+            end
+            @state.bp_portal.cmds << :continue
+            @state.bp_portal = @state.bp_waiting.pop
+            return nil
+        end
+
+        # Finish the current frame and stop in the return.
+        #
+        def bp_finish
+            unless @state.bp_portal
+                return "Not stopped at a breakpoint"
+            end
+            @state.bp_portal.cmds << :fin
+            @state.bp_portal = @state.bp_waiting.pop
+            return nil
+        end
+
+        # Break execution at the next line (without going into another
+        # class).
+        #
+        def bp_next
+            unless @state.bp_portal
+                return "Not stopped at a breakpoint"
+            end
+            @state.bp_portal.cmds << :next
+            @state.bp_portal = @state.bp_waiting.pop
+            return nil
+        end
+
+        # Follow the next instruction--potentially into another class
+        # and/or method.
+        #
+        def bp_step
+            unless @state.bp_portal
+                return "Not stopped at a breakpoint"
+            end
+            @state.bp_portal.cmds << :step
+            @state.bp_portal = @state.bp_waiting.pop
+            return nil
+        end
+
+        private
+
+        def get_thread_id( thread )
+            if thread.kind_of?( String )
+                if thread[0] == ?:
+                    thread = thread[1..-1].to_sym
+                else
+                    id = thread.to_i
+                    if id != 0
+                        thread = id
+                    end
+                end
+            end
+            ::Thread.list.each do |th|
+                if thread.kind_of?( Fixnum )
+                    if th.object_id == thread
+                        thread = th
+                        break
+                    end
+                else
+                    if th[:thread_name] == thread
+                        thread = th
+                        break
+                    end
+                end
+            end
+            unless thread.kind_of?( ::Thread )
+                raise "Unable to locate thread #{thread.inspect}"
+            end
+            return thread.object_id
+        end
+
+        def real_bp_add( key )
+            @state.bp_waiting ||= Queue.new
+
+            @state.breakpoint_id ||= 0
+            @state.breakpoint_id += 1
+
+            @breakpoints[key] = BreakPoint.new( @state.breakpoint_id, @state )
+
+            return "Added breakpoint #{@state.breakpoint_id}"
+        end
+
+        # Now toss the private methods from our list...
+        private_instance_methods.each do |m|
+            RTI_METHODS.delete( m )
+        end
+
+    end
+
+end