rtinspect 0.0.1 → 0.0.19

data/lib/rti/redirect.rb

@@ -0,0 +1,102 @@
+# Contains the RuntimeInspection::ThreadRedirect.
+#
+# 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
+
+    # 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
+
+        # 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.
+        #
+        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
+
+end

data/lib/rti/state.rb

@@ -0,0 +1,65 @@
+# Contains the RuntimeInspection::State.
+#
+# 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
+
+    # 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.
+        #
+        # +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, 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[: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
+        end
+
+    end
+
+end

data/lib/rti/thread.rb

@@ -0,0 +1,553 @@
+# Contains the RuntimeInspection::Thread.
+#
+# 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
+
+    # A thread that exposes inspection and debugging functionality
+    # over a TCP socket.
+    #
+    class Thread < ::Thread
+
+        # 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.
+        #
+        def initialize( host='localhost', port=56789, binding=TOPLEVEL_BINDING,
+                        prompt_name=File.basename($0,'.rb') )
+
+            @server = TCPServer.new( host, port )
+            @binding = binding
+
+            OPTS[: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
+                            socket.set_peerstr
+                            def socket.to_s
+                                @peerstr or super
+                            end
+                            def socket.inspect
+                                super.chop + " #{to_s}>"
+                            end
+
+                            OPTS[:dbg_handler].call "Connection established " +
+                                "with #{socket}"
+
+                            run_client_thread( prompt_name, socket )
+                        end
+                    end
+                rescue Object => e
+                    OPTS[:exc_handler].call( "running inspection thread", e )
+                end
+            end
+        end
+
+        #####################################################################
+        # Remaining functions are 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
+
+        def kill # :nodoc:
+            super
+            cleanup
+        end
+
+        def exit # :nodoc:
+            super
+            cleanup
+        end
+
+        private
+
+        # Establish a thread that cleans up dead or disconnected
+        # client threads (see #run_client_thread).
+        #
+        def run_gc_thread
+            @gc_thread = ::Thread.new do
+                ::Thread.current[:thread_name] = :rti_gc
+                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
+
+                    OPTS[:dbg_handler].call "Cleaning up #{th[:socket]}"
+
+                    state = th[:state]
+                    state.rti.bp_stop if state.bp_portal
+
+                    list = @breakpoints.collect do |key, bp|
+                        if bp.state == state
+                            bp
+                        end
+                    end
+                    list.compact!
+                    list.each do |bp|
+                        state.rti.bp_delete( bp.id )
+                    end
+
+                    begin
+                        th.kill if th.alive?
+                        th.join
+                    rescue Object => e
+                        OPTS[:exc_handler].call( "cleaning up thread for " +
+                                                 "#{th[:socket]}", e )
+                    end
+
+                    begin
+                        socket = th[:socket]
+                        unless socket.closed?
+                            socket.close
+                            OPTS[:dbg_handler].call( "Closed connection from " +
+                                                     "#{socket}" )
+                        end
+                    rescue Object => e
+                        OPTS[:exc_handler].call( "cleaning up socket for " +
+                                                 "#{th[:socket]}", e )
+                    end
+                end
+            end
+        end
+
+        # A new client socket has been established. Handle the
+        # connection in a separate thread so we don't block other
+        # connections.
+        #
+        def run_client_thread( prompt_name, socket )
+            client_thread = ::Thread.new do
+                t = ::Thread.current
+                t[:thread_name] = :rti_client
+                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
+                        OPTS[: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
+        end
+
+        # Show the client a nice prompt with data about the state of
+        # the session.
+        #
+        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}) in #{sp.thread}" )
+                end
+            end
+
+            socket.print( "#{prompt_name}:#{'%03d'%state.cmd_count}:" +
+                          "#{state.block_count}#{crit}> " )
+        end
+
+        # Used to coordinate both the redirected eval output as well
+        # as the eval returned value.
+        #
+        EvalReturn = Struct.new( :out, :value )
+
+        # 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.
+        #
+        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+/ )
+
+                direct_thread = ::Thread.new do
+                    Thread.current[:thread_name] = :rti_direct
+                    state.rti.send( rti_cmd, *rti_args )
+                end
+
+                watch_req = nil
+                watch_thread = run_watch_thread( ::Thread.current ) do |th, req|
+                    watch_req = req
+                    direct_thread.kill
+                end
+
+                begin
+                    direct_thread.join
+                ensure
+                    if watch_req
+                        if watch_req == :dead_client
+                            @dead_clients << ::Thread.current
+                        end
+                    else
+                        watch_thread.kill
+                    end
+                end
+
+                ret = EvalReturn.new( nil, direct_thread.value )
+            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 "#{OPTS[: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 )
+            th = ::Thread.current
+            tracer = th[:rti_tracer]
+            sp = StopPoint.new( classname, methodname, file, line, event, th )
+
+            if tracer
+                found = tracer.stoppoint( sp )
+                if found == :continue
+                    found = nil
+                end
+            end
+
+            unless found
+                return unless file and line
+                # The first delete is due to the one-time nature of
+                # RTIManager#bp_attach.
+                if( bp = @breakpoints.delete( ">#{th.object_id}" ) or
+                    bp = @breakpoints["#{file}:#{line}"] or
+                    bp = @breakpoints["#{file}:#{line}>#{th.object_id}"] )
+                    sp.breakpoint = bp
+                    sp.state = bp.state
+                    found = sp
+                else
+                    # These breakpoints only stop at the initial call
+                    # into this method.
+                    return unless event == 'call'
+                    if( bp = @breakpoints["#{classname}##{methodname}"] or
+                        bp = @breakpoints["#{classname}##{methodname}>#{th.object_id}"] )
+                        sp.breakpoint = bp
+                        sp.state = bp.state
+                        found = sp
+                    elsif( bp = @breakpoints["#{methodname}"] or
+                           bp = @breakpoints["#{methodname}>#{th.object_id}"] )
+                        sp.breakpoint = bp
+                        sp.state = bp.state
+                        found = sp
+                    else
+                        if OPTS[:show_trace]
+                            OPTS[:dbg_handler].call(
+                                "Skipping #{classname}##{methodname} " +
+                                "at #{file}:#{line} in #{th}" )
+                        end
+                        return
+                    end
+                end
+            end
+
+            # If we've found a stoppoint, we no longer need the tracer
+            # as it is just looking for the next stopping point.
+            th[:rti_tracer] = nil
+            portal = Portal.new( found, Queue.new, Queue.new )
+            found.state.bp_waiting << portal
+            loop do
+                cmd = portal.cmds.pop
+                case cmd
+                when :step
+                    th[:rti_tracer] = Tracer.new( portal, cmd )
+                    break
+                when :next
+                    th[:rti_tracer] = Tracer.new( portal, cmd )
+                    break
+                when :fin
+                    th[:rti_tracer] = Tracer.new( portal, cmd )
+                    break
+                when :continue
+                    break
+                when :stop
+                    set_trace_func( nil )
+                    break
+                else
+                    out = run_eval( found.state, cmd, binding )
+                    portal.out << out
+                end
+            end
+        rescue Object => e
+            OPTS[: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.
+        #
+        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
+                OPTS[: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[:thread_name] = :rti_eval
+                t[:rti_redirect_io] = ret.out
+                t[:rti_manager] = state.rti
+                begin
+                    eval( *eval_args )
+                rescue Object => e
+                    e
+                end
+            end
+
+            watch_req = nil
+            watch_thread = run_watch_thread( ::Thread.current ) do |th, req|
+                watch_req = req
+                eval_thread.kill
+            end
+
+            begin
+                eval_thread.join
+            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
+            ensure
+                ThreadRedirect.stop
+                if watch_req
+                    if watch_req == :dead_client
+                        @dead_clients << ::Thread.current
+                    end
+                    # nothing more--let the watch thread stop on its own
+                else
+                    watch_thread.kill
+                end
+            end
+
+            ret.value = eval_thread.value
+
+            return ret
+        end
+
+        # Here, we do not protect this with a timeout as the amount of
+        # time to wait is indeterminate (i.e. in some cases, one may
+        # wait a long time for a breakpoint to hit based on how
+        # complicated the setup is to get the codepath in to that
+        # state). However, we must detect when a client disconnects
+        # while this thread waits around trying to find a breakpoint,
+        # otherwise, this thread will hang around forever.
+        #
+        def run_watch_thread( client_thread )
+            ::Thread.new do
+                ::Thread.current[:thread_name] = :rti_watch
+                socket = client_thread[:socket]
+                loop do
+                    IO.select( [socket] )
+                    if socket.eof?
+                        yield( client_thread, :dead_client )
+                        break
+                    else
+                        req = socket.read_nonblock( 100 )
+                        chars = req.unpack( "C*" )
+                        # There has *got* to be a better way...
+                        case chars
+                        when [4]
+                            # This is the ^d so the client can
+                            # interrupt a command without killing the
+                            # connection.
+                            yield( client_thread, :interrupt )
+                            break
+                        when [0xff, 0xf4, 0xff, 0xfd, 0x6]
+                            # When we capture ^c it appears that
+                            # nothing else is ever displayed by the
+                            # telnet client for some strange
+                            # reason. So, we terminate the connection.
+                            yield( client_thread, :dead_client )
+                            break
+                        else
+                            hexstr = chars.collect{|c| c.to_s(16)}.join
+                            OPTS[:dbg_handler].call( "Ignoring #{req} " +
+                                                     "(#{hexstr})" )
+                            socket.puts "Unknown request (#{req.chomp}). " +
+                                "Use control-d to interrupt the process."
+                        end
+                    end
+                end
+            end
+        end
+
+        # Close down all our threads and clean stuff up in
+        # anticipation of the main thread going away.
+        #
+        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
+
+end