rtinspect 0.0.1 → 0.0.19

data/lib/rti/tracer.rb

@@ -0,0 +1,71 @@
+# Contains the RuntimeInspection::Tracer.
+#
+# 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 help track the tracing of a particular StopPoint in a
+    # given thread. Having a tracer assigned to a thread (via the
+    # :rti_tracer element stored in the thread from
+    # Thread#handle_tracing) ensures that a RTIManager#bp_finish,
+    # RTIManager#bp_next, or RTIManager#bp_step will always occur
+    # within in the same thread. Note that it is still possible for
+    # another breakpoint to "interrupt" this tracer and stop
+    # processing somewhere else.
+    #
+    class Tracer
+        def initialize( portal, cmd )
+            @portal = portal
+            @cmd = cmd
+        end
+
+        # Given a generic StopPoint, adjust it where necessary if we
+        # are at the next real StopPoint that should be passed off to
+        # the client.
+        #
+        def stoppoint( sp )
+            case @cmd
+            when :step
+                sp.state = @portal.stoppoint.state
+                return sp
+            when :next
+                case sp.event
+                when 'line'
+                    if( @portal.stoppoint.classname == sp.classname and
+                        @portal.stoppoint.methodname == sp.methodname )
+                        sp.state = @portal.stoppoint.state
+                        return sp
+                    end
+                when 'return'
+                    if( @portal.stoppoint.classname == sp.classname and
+                        @portal.stoppoint.methodname == sp.methodname )
+                        @cmd = :any_line
+                    end
+                end
+                return :continue
+            when :fin
+                if( sp.event == 'return' and
+                    @portal.stoppoint.classname == sp.classname and
+                    @portal.stoppoint.methodname == sp.methodname )
+                    sp.state = @portal.stoppoint.state
+                    return sp
+                end
+            when :any_line
+                if sp.event == 'line'
+                    sp.state = @portal.stoppoint.state
+                    return sp
+                else
+                    return :continue
+                end
+            else
+                raise "Unknown tracer command: #{@cmd}"
+            end
+        end
+    end
+
+end

data/lib/rtinspect.rb

@@ -1,7 +1,6 @@
 # :main: README
-# :title: Runtime Inspection and Debugging Thread
 #
-# Contains the RuntimeInspectionThread.
+# Contains main entry point of the RuntimeInspection module.
 #
 # Copyright (c) 2006-2007 Brad Robel-Forrest.
 #
@@ -11,940 +10,118 @@
 
 require 'socket'
 require 'thread'
-require 'timeout'
 require 'yaml'
 
-# A thread that exposes inspection and debugging functionality over a
-# TCP socket.
-#
-class RuntimeInspectionThread < Thread
-
-    # This is the value used to distinguish data sent to the client
-    # from within the command evaluation from the value returned from
-    # the evaluation.
-    #
-    OUTPUT_MARKER = '=>'
-
-    if $DEBUG
-        @@dbg_handler = Proc.new {|msg| puts msg}
-    else
-        @@dbg_handler = Proc.new {}
-    end
-
-    @@exc_handler = Proc.new do |msg, exc|
-        STDERR.puts( "#{Thread.current}: Exception while #{msg}",
-                      exc, exc.backtrace )
-    end
-
-    # Optionally enable your own handling of debug output. Default is
-    # to either suppress it or send it to $stdout if $DEBUG is enabled
-    # (only checked at class load time).
-    #
-    def self.dbg_handler( &block ) # :yields: msg
-        @@dbg_handler = block
-    end
-
-    # Optionally enable your own exception handler. Default is to
-    # write the exception and backtrace out to $stderr.
-    #
-    def self.exc_handler( &block ) # :yields: msg, exc
-        @@exc_handler = block
-    end
-
-    # Used to manage information found at each stopping point--either
-    # hit by a BreakPoint or because of a rti_next or rti_step
-    # request.
-    #
-    StopPoint = Struct.new( :classname, :methodname, :file, :line, :event,
-                            :breakpoint )
-
-    # Used as a messaging mechanism once a StopPoint is hit to
-    # coordinate commands received from the client in a client thread
-    # (see run_client_thread) with the actual evaluation run from
-    # within the StopPoint's context (it's binding--see
-    # handle_tracing).
-    #
-    Portal = Struct.new( :stoppoint, :cmds, :out )
-
-    # Used when we want to redirect stdout or stderr for a specific
-    # thread. This is intelligent enough so that it reuses one if it
-    # is already in place from another thread.
-    #
-    class ThreadRedirect
+module RuntimeInspection
 
-        # Synchronization for ensuring we are either using the same
-        # redirection manager or creating only one new one.
-        #
-        MUTEX = Mutex.new
-
-        # Replace the global stdout and stderr with a redirection
-        # object. If one is already there, then use it.
-        #
-        def self.start
-            MUTEX.synchronize do
-                if $stdout.kind_of? self
-                    $stdout.usage += 1
-                else
-                    $stdout = new( $stdout )
-                end
-                if $stderr.kind_of? self
-                    $stderr.usage += 1
-                else
-                    $stderr = new( $stderr )
-                end
-            end
-            return true
-        end
-
-        # Stop any redirection and put the original IO back in its
-        # place unless there are still other threads using
-        # redirection. Then, wait for them to stop
-        #
-        def self.stop
-            MUTEX.synchronize do
-                unless $stdout.kind_of? self
-                    if $stdout.usage > 0
-                        $stdout.usage -= 1
-                    else
-                        $stdout = $stdout.default_io
-                    end
-                end
-                unless $stderr.kind_of? self
-                    if $stderr.usage > 0
-                        $stderr.usage -= 1
-                    else
-                        $stderr = $stderr.default_io
-                    end
-                end
-            end
-        end
-
-        # Create a new redirection manager for the IO stream provided.
-        #
-        def initialize( default_io )
-            @default_io = default_io
-            @usage = 0
-        end
-
-        # A reference counter if other threads are also using this
-        # redirection manager.
-        #
-        attr_accessor :usage
-
-        # The IO to use for non-redirected output.
-        #
-        attr_reader :default_io
-
-        # Provide the output method so this object can be used as
-        # either stdout or stderr.
-        #
-        def write( *args )
-            if rio = Thread.current[:rti_redirect_io]
-                rio.write( *args )
-            else
-                @default_io.write( *args )
-            end
-        end
-
-        def method_missing( sym, *args, &block )
-            if rio = Thread.current[:rti_redirect_io]
-                rio.send( sym, *args, &block )
-            else
-                @default_io.send( sym, *args, &block )
-            end
-        end
-
-    end
-
-    # Data managed about each TCP connection. Note that these values
-    # can be manged from the remote session (e.g. by issuing commands
-    # like <em>state.use_yaml = true</em>).
-    #
-    class State < Hash
-
-        # Create a new object for tracking state information.
-        #
-        # +socket+:: The owner connection for this data.
-        #
-        # +cmd_count+:: The current evaluation number.
-        #
-        # +block_count+:: The current block number. When bigger than zero,
-        #                 multiple lines are collected until a blank line
-        #                 is encountered and then the entire block is
-        #                 evaluated. Each successive block will increase
-        #                 the number (similar to the normal _cmd_count_
-        #                 value).
-        #
-        # +block_cmd+:: The collection of the block if the +block_count+
-        #               is larger than zero.
-        #
-        # +use_yaml+:: The output should be YAML.
-        #
-        # +eval_timeout+:: The number of seconds to allow an evaluation to
-        #                  continue. All other connections are blocked during
-        #                  this period.
-        #
-        # +safe_level+:: The level $SAFE is declared at for each evaluation.
-        #
-        def initialize( socket=Thread.current[:socket],
-                        cmd_count=1, block_count=0, block_cmd='',
-                        use_yaml=false, eval_timeout=60, safe_level=3 )
-            super()
-            self[:socket] = socket
-            self[:cmd_count] = cmd_count
-            self[:block_count] = block_count
-            self[:block_cmd] = block_cmd
-            self[:use_yaml] = use_yaml
-            self[:eval_timeout] = eval_timeout
-            self[:safe_level] = safe_level
-        end
-
-        def method_missing( sym, val=nil )
-            if key?( sym )
-                self[sym]
-            else
-                str = sym.to_s
-                if str[-1] == ?=
-                    self[str.chop.to_sym] = val
-                else
-                    self[sym]
-                end
-            end
+    class ::Thread
+        alias inspect_without_name inspect
+        def inspect
+            show_with_name( inspect_without_name )
         end
-
-    end
-
-    class Tracer
-        def initialize( portal, cmd )
-            @portal = portal
-            @cmd = cmd
+        alias to_s_without_name to_s
+        def to_s
+            show_with_name( to_s_without_name )
         end
-
-        def stoppoint( sp )
-            case @cmd
-            when :step
-                sp.breakpoint = @portal.stoppoint.breakpoint
-                return sp
-            when :next
-                case sp.event
-                when 'line'
-                    if( @portal.stoppoint.classname == sp.classname and
-                        @portal.stoppoint.methodname == sp.methodname )
-                        sp.breakpoint = @portal.stoppoint.breakpoint
-                        return sp
-                    end
-                when 'return'
-                    if( @portal.stoppoint.classname == sp.classname and
-                        @portal.stoppoint.methodname == sp.methodname )
-                        @cmd = :any_line
-                    end
-                end
-                return :continue
-            when :fin
-                if( sp.event == 'return' and
-                    @portal.stoppoint.classname == sp.classname and
-                    @portal.stoppoint.methodname == sp.methodname )
-                    sp.breakpoint = @portal.stoppoint.breakpoint
-                    return sp
-                end
-            when :any_line
-                if sp.event == 'line'
-                    sp.breakpoint = @portal.stoppoint.breakpoint
-                    return sp
-                else
-                    return :continue
-                end
+        def show_with_name( str )
+            if( name = self[:thread_name] or
+                (::Thread.main == self and name = :main) )
+                str.sub( /Thread:0x[[:xdigit:]]+/,
+                         "Thread:#{object_id} #{name.inspect}" )
             else
-                raise "Unknown tracer command: #{@cmd}"
+                str
             end
         end
+        private :show_with_name
     end
 
-    # 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 )
-            name = id.id2name
-            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 RuntimeInsepctionThread. 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
-
-        # Add a new BreakPoint. Execution will not stop at any BreakPoints
-        # until rti_bp_start is called. The argument should use one of the
-        # following forms:
-        #
-        # * Class#method
-        # * Module#method
-        # * method
-        # * file:line
-        #
-        # In the first three forms, the BreakPoint will stop on the 'call'
-        # event into that method.
-        #
-        def bp_add( key )
-            if bp = @breakpoints[key]
-                return "Breakpoint already held as #{bp.id} by #{bp.state.socket}"
-            end
+    # Load in the supporting files.
+    require "rti/state.rb"
+    require "rti/tracer.rb"
+    require "rti/manager.rb"
+    require "rti/redirect.rb"
+    require "rti/thread.rb"
 
-            @state.bp_waiting ||= Queue.new
-
-            @state.breakpoint_id ||= 0
-            @state.breakpoint_id += 1
-
-            @breakpoints[key] = BreakPoint.new( @state.breakpoint_id, @state )
-
-            ret = "Added breakpoint #{@state.breakpoint_id}"
-
-            return ret
-        end
-
-        # Delete a breakpoint.
-        #
-        def bp_del( 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
-            set_trace_func( @tracing_proc )
-            @state.bp_portal = @state.bp_waiting.pop
-            return nil
-        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
-
-        def bp_fin
-            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
-
-        # 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
-
-    end
-
-    # Create a new inspection thread.
-    #
-    # +host+:: What address to listen on.
-    #
-    # +port+:: What port to listen on.
-    #
-    # +binding+:: In what context should the evaluations be run?
-    #
-    # +prompt_name+:: What name to use in the prompt.
+    # This is the set of options managed by RTI. The output_marker is
+    # the value used to distinguish data sent to the client from
+    # within the command evaluation from the value returned from the
+    # evaluation.
     #
-    def initialize( host='localhost', port=56789, binding=TOPLEVEL_BINDING,
-                    prompt_name=File.basename($0,'.rb') )
-
-        @server = TCPServer.new( host, port )
-        @binding = binding
-
-        @@dbg_handler.call "Runtime inspection available at #{host}:#{port}"
-
-        @breakpoints = {}
-        @tracing_proc = method( :handle_tracing ).to_proc
-
-        @clients = []
-        @clients_mutex = Mutex.new
-        @dead_clients = Queue.new
-
-        run_gc_thread
-
-        super do
-            begin
-                while sockets = select( [@server] )
-                    sockets.first.each do |socket|
-                        socket = @server.accept
-                        def socket.set_peerstr
-                            unless closed?
-                                peer = peeraddr
-                                @peerstr = "#{peer[3]}:#{peer[1]}"
-                            end
-                        end
-                        def socket.to_s
-                            @peerstr or super
-                        end
-                        def socket.inspect
-                            super.chop + " #{to_s}>"
-                        end
-
-                        socket.set_peerstr
-                        @@dbg_handler.call "Connection established with " +
-                            "#{socket}"
-
-                        run_client_thread( prompt_name, socket )
-                    end
-                end
-            rescue Object => e
-                @@exc_handler.call( "running inspection thread", e )
-            end
-        end
-    end
-
-    ######################################################################
-    # Remaining functions just overrides for Thread class and then
-    # private stuff.
-
-    def inspect # :nodoc:
-        super.chop + " #{@clients.inspect}>"
-    end
-
-    def to_s # :nodoc:
-        inspect
-    end
-
-    def terminate # :nodoc:
-        super
-        cleanup
-    end
+    OPTS = { :output_marker => '=>' }
 
-    def kill # :nodoc:
-        super
-        cleanup
+    if $DEBUG
+        OPTS[:dbg_handler] = Proc.new {|msg| puts msg}
+    else
+        OPTS[:dbg_handler] = Proc.new {}
     end
 
-    def exit # :nodoc:
-        super
-        cleanup
+    OPTS[:exc_handler] = Proc.new do |msg, exc|
+        STDERR.puts( "#{::Thread.current}: Exception while #{msg}",
+                     exc, exc.backtrace )
     end
 
-    private
-
-    # Establish a thread that cleans up dead or disconnected client
-    # threads (see #run_client_thread).
+    # Optionally enable your own handling of debug output. Default is
+    # to either suppress it or send it to $stdout if $DEBUG is enabled
+    # (only checked at class load time).
     #
-    def run_gc_thread
-        @gc_thread = Thread.new do
-            loop do
-                th = @dead_clients.pop
-                if th == :quit
-                    break
-                end
-
-                if th[:cleaned]
-                    next
-                else
-                    th[:cleaned] = true
-                end
-
-                @clients_mutex.synchronize do
-                    @clients.delete( th )
-                end
-
-                @@dbg_handler.call "Cleaning up #{th[:socket]}"
-
-                state = th[:state]
-                bp.rti.bp_stop if state.bp_portal
-                @breakpoints.delete_if{|key, bp| bp.state == state}
-
-                begin
-                    th.kill if th.alive?
-                    th.join
-                rescue Object => e
-                    @@exc_handler.call( "cleaning up thread for #{th[:socket]}",
-                                        e )
-                end
-
-                begin
-                    socket = th[:socket]
-                    unless socket.closed?
-                        socket.close
-                        @@dbg_handler.call "Closed connection from #{socket}"
-                    end
-                rescue Object => e
-                    @@exc_handler.call( "cleaning up socket for #{th[:socket]}",
-                                        e )
-                end
-            end
-        end
+    def self.dbg_handler( &block ) # :yields: msg
+        OPTS[:dbg_handler] = block
     end
 
-    # A new client socket has been established. Handle the connection
-    # in a separate thread so we don't block other connections.
+    # Optionally enable display of any trace methods that are not seen
+    # as break or stop points. This will use the dbg_handler to
+    # output, so if that isn't set, nothing will be shown.
     #
-    def run_client_thread( prompt_name, socket )
-        client_thread = Thread.new do
-            t = Thread.current
-            t[:socket] = socket
-            t[:state] = state = State.new
-            state.rti = RTIManager.new( @breakpoints, @tracing_proc, state )
-
-            loop do
-                begin
-                    prompt( prompt_name, socket, state )
-                    select( [socket] )
-                    if handle_client( socket, state ) == :dead
-                        break
-                    end
-                rescue Object => e
-                    @@exc_handler.call( "handling connection from #{socket}:", e )
-                    if socket.closed?
-                        break
-                    else
-                        socket.puts( "Connection handler exception:" )
-                        socket.puts( e )
-                        socket.puts( e.backtrace )
-                    end
-                end
-            end
-
-            @dead_clients << t
-        end
-
-        def client_thread.inspect
-            super.chop + " #{self[:socket]}>"
-        end
-
-        @clients_mutex.synchronize do
-            @clients << client_thread
-        end
+    def self.show_trace=( val )
+        OPTS[:show_trace] = val
     end
 
-    # Show the client a nice prompt with data about the state of the session.
+    # Optionally enable your own exception handler. Default is to
+    # write the exception and backtrace out to $stderr.
     #
-    def prompt( prompt_name, socket, state )
-        if Thread.critical
-            crit = '-!!'
-        end
-
-        if state.block_cmd.empty?
-            socket.puts
-
-            if portal = state.bp_portal
-                sp = portal.stoppoint
-                if sp.breakpoint
-                    pre = "Breakpoint #{sp.breakpoint.id}"
-                else
-                    pre = "Stopped"
-                end
-                socket.puts( "#{pre} in #{sp.classname}\#" +
-                             "#{sp.methodname} from #{sp.file}:#{sp.line} " +
-                             "(#{sp.event})" )
-            end
-        end
-
-        socket.print( "#{prompt_name}:#{'%03d'%state.cmd_count}:" +
-                      "#{state.block_count}#{crit}> " )
+    def self.exc_handler( &block ) # :yields: msg, exc
+        OPTS[:exc_handler] = block
     end
 
-    # Used to coordinate both the redirected eval output as well as
-    # the eval returned value.
+    # The placeholder for an RTI thread started via on_signal.
     #
-    EvalReturn = Struct.new( :out, :value )
+    @@signal_rti = nil
 
-    # Get the next command from the client and process it by either
-    # evaluating it in the default binding context or in the context
-    # of a breakpoint.
+    # Used to have RTI register itself on or off when the given signal
+    # is trapped. This way, the RTI thread is only running when needed
+    # during trouble-shooting or debugging. The remaining arguments
+    # are passed off to the #new method when the RTI thread is
+    # instantiated.
     #
-    def handle_client( socket, state )
-        unless cmd = socket.gets
-            return :dead
-        end
-
-        if state.block_count > 0
-            if cmd.match( /^\s*$/ )
-                cmd = state.block_cmd
-                state.block_count += 1
-                state.block_cmd = ''
-            else
-                state.block_cmd += cmd
-                return state.cmd_count += 1
-            end
-        end
-
-        if( cmd[0] == RTIManager::CMD_MARKER )
-            # Handle RTI commands (e.g. bp_add, bp_start...).
-            rti_cmd, *rti_args = cmd[1..-1].split( /\s+/ )
-            ret = EvalReturn.new( nil, state.rti.send( rti_cmd, *rti_args ))
-        end
-
-        unless ret
-            # Determine to either run the cmd locally or in a thread
-            # waiting at a breakpoint.
-            if state.bp_portal
-                state.bp_portal.cmds << cmd
-                ret = state.bp_portal.out.pop
-            else
-                ret = run_eval( state, cmd )
-            end
-        end
-
-        if out = ret.out
-            if out.kind_of? StringIO
-                socket.puts out.string unless out.length < 1
-            else
-                socket.puts out
-            end
-        end
-
-        v = ret.value
-        if state.use_yaml
-            v = v.to_yaml
-        elsif v.kind_of? Exception
-            v = "#{v}\n" + v.backtrace.join("\n")
-        else
-            v = v.inspect
-        end
-
-        socket.puts "#{OUTPUT_MARKER} #{v}"
-
-        state.cmd_count += 1
-    end
-
-    # Turned on selectively via #rti_bp_start where we are actively
-    # trying to find a point to stop and process commands in this
-    # context.
-    #
-    def handle_tracing( event, file, line, methodname, binding, classname )
-        sp = StopPoint.new( classname, methodname, file, line, event)
-        tracer = Thread.current[:rti_tracer]
-
-        if tracer
-            $goober.puts [:tracer, sp].inspect
-            $goober.flush
-
-            found = tracer.stoppoint( sp )
-            if found == :continue
-                found = nil
-            end
-        end
-
-        unless found
-            return unless file and line
-            if bp = @breakpoints["#{file}:#{line}"]
-                sp.breakpoint = bp
-                found = sp
-            else
-                # These breakpoints only stop at the initial call into
-                # this method.
-                return unless event == 'call'
-                if bp = @breakpoints["#{classname}##{methodname}"]
-                    sp.breakpoint = bp
-                    found = sp
-                elsif bp = @breakpoints["#{methodname}"]
-                    sp.breakpoint = bp
-                    found = sp
+    def self.on_signal( signal='USR1', *args )
+        unless OPTS[:signal_is_set]
+            OPTS[:signal_is_set] = true
+            Signal.trap( signal ) do
+                if @@signal_rti
+                    @@signal_rti.kill
+                    @@signal_rti = nil
+                    OPTS[:dbg_handler].call "Stopped signal-based RTI thread"
                 else
-                    return
+                    @@signal_rti = Thread.new( *args )
+                    OPTS[:dbg_handler].call "Started signal-based RTI thread"
                 end
             end
         end
-
-        if bp = found.breakpoint
-            # If we've found a stoppoint, we no longer need the tracer
-            # as it is just looking for the next stopping point.
-            Thread.current[:rti_tracer] = nil
-            portal = Portal.new( found, Queue.new, Queue.new )
-            bp.state.bp_waiting << portal
-            loop do
-                cmd = portal.cmds.pop
-                case cmd
-                when :step
-                    Thread.current[:rti_tracer] = Tracer.new( portal, cmd )
-                    break
-                when :next
-                    Thread.current[:rti_tracer] = Tracer.new( portal, cmd )
-                    break
-                when :fin
-                    Thread.current[:rti_tracer] = Tracer.new( portal, cmd )
-                    break
-                when :continue
-                    break
-                when :stop
-                    set_trace_func( nil )
-                    break
-                else
-                    out = run_eval( bp.state, cmd, binding )
-                    portal.out << out
-                end
-            end
-        end
-    rescue Object => e
-        @@exc_handler.call( "tracing", e )
     end
 
-    # Run a safe evaluation of a client's command. This redirect's any
-    # output from the command's evaluation. The return will be both
-    # the output from the evaluation as well as the value of the
-    # evaluation.
+    # Used to manage information found at each stopping point--either
+    # hit by a BreakPoint or because of one of the bp_* methods in the
+    # RTIManager.
     #
-    def run_eval( state, cmd, binding=@binding, safe_level=nil )
-        safe_level = state.safe_level unless safe_level
-        ret = EvalReturn.new
-
-        eval_args = ["$SAFE=#{safe_level};rti=Thread.current[:rti_manager];" +
-                     cmd]
-        if binding
-            eval_args << binding
-        end
-
-        if $DEBUG
-            if binding != @binding
-                bindstr = " (explicit binding)"
-            elsif !binding
-                bindstr = " (without binding)"
-            end
-            @@dbg_handler.call "Executing#{bindstr} [#{safe_level}]: #{cmd}"
-        end
-
-        # Temporarily capture stdout/stderr into string for just the
-        # evaluation thread.
-        ret.out = StringIO.new
-        ThreadRedirect.start
-
-        eval_thread = Thread.new do
-            t = Thread.current
-            t[:rti_redirect_io] = ret.out
-            t[:rti_manager] = state.rti
-            begin
-                eval( *eval_args )
-            rescue Object => e
-                e
-            end
-        end
-
-        begin
-            timeout( state.eval_timeout ) do
-                eval_thread.join
-            end
-        rescue Object => e
-            ret.out.puts e, e.backtrace
-            # The thread could hang around forever if it isn't
-            # taken care of...
-            eval_thread.kill if eval_thread
-        ensure
-            ThreadRedirect.stop
-        end
-
-        ret.value = eval_thread.value
-
-        return ret
-    end
+    StopPoint = Struct.new( :classname, :methodname, :file, :line, :event,
+                            :thread, :state, :breakpoint )
 
-    # Close down all our threads and clean stuff up in anticipation of
-    # the main thread going away.
+    # Used as a messaging mechanism once a StopPoint is hit to
+    # coordinate commands received from the client in a client thread
+    # (see run_client_thread) with the actual evaluation run from
+    # within the StopPoint's context (it's binding--see
+    # handle_tracing).
     #
-    def cleanup
-        @server.close unless @server.closed?
-
-        until @clients.empty?
-            client = nil
-            @clients_mutex.synchronize do
-                client = @clients.pop
-            end
-            @dead_clients << client
-        end
-
-        # Tell the GC thread to but still give it a chance to finish
-        # up with all the clients we just gave it.
-        @dead_clients << :quit
-
-        until @dead_clients.empty?
-            @gc_thread.run
-        end
-
-        @gc_thread.kill
-    end
-
-end
-
-if $0 == __FILE__
-    class Foo
-        def bar
-            @a ||= 0
-            b = @a + 1
-            sleep 5
-            puts @a
-            @a += 1
-        end
-    end
-
-    def start_foo
-        Thread.new do
-            foo = Foo.new
-            z = 0
-            y = 100
-            loop do
-                z += 1
-                foo.bar
-                y += 2
-            end
-        end
-    end
-
-    $goober = File.open( 'goober', 'w' )
-    $goober.sync = false
-    at_exit do
-        $goober.flush
-    end
+    Portal = Struct.new( :stoppoint, :cmds, :out )
 
-    unless ARGV.length > 0
-        RuntimeInspectionThread.new.join
-        exit
-    end
 end