Package com.tonic.analysis.execution.debug

Class DebugSession

  • public final class DebugSession
extends Object
    Interactive stepping debugger over a BytecodeEngine, driving breakpoints, step modes, and state snapshots for listeners.

    • Constructor Detail

      • DebugSession

        public DebugSession​(BytecodeContext context)
        Creates an idle session with a fresh breakpoint manager.
        Parameters:
        context - the execution configuration
        Throws:
        IllegalArgumentException - if context is null

      • DebugSession

        public DebugSession​(BytecodeContext context,
                    BreakpointManager breakpointManager)
        Creates an idle session using the given breakpoint manager.
        Parameters:
        context - the execution configuration
        breakpointManager - the breakpoint registry to use
        Throws:
        IllegalArgumentException - if context or breakpointManager is null

    • Method Detail

      • start

        public void start​(MethodEntry method,
                  ConcreteValue... args)
        Initializes the engine with the method's initial frame and pauses before the first instruction.
        Parameters:
        method - the method to debug
        args - argument values for the initial frame
        Throws:
        IllegalStateException - if the session was already started

      • stop

        public void stop()
        Terminates the session, interrupting the engine and notifying listeners.
        Throws:
        IllegalStateException - if the session was never started

      • pause

        public void pause()
        Requests a pause of a running execution at the next instruction boundary.
        Throws:
        IllegalStateException - if the session is not running

      • resume

        public DebugState resume()
        Resumes free-running execution until a breakpoint, pause request, or completion.
        Returns:
        the state when execution pauses or finishes
        Throws:
        IllegalStateException - if the session is idle, stopped, or already running

      • stepInto

        public DebugState stepInto()
        Executes a single instruction, pausing inside any invoked method.
        Returns:
        the state when execution pauses or finishes
        Throws:
        IllegalStateException - if the session is idle, stopped, or already running

      • stepOver

        public DebugState stepOver()
        Executes one instruction without pausing inside deeper frames.
        Returns:
        the state when execution pauses or finishes
        Throws:
        IllegalStateException - if the session is idle, stopped, or already running

      • stepOut

        public DebugState stepOut()
        Runs until the current frame returns to its caller.
        Returns:
        the state when execution pauses or finishes
        Throws:
        IllegalStateException - if the session is idle, stopped, or already running

      • runToCursor

        public DebugState runToCursor​(int pc)
        Runs until the current method reaches the given pc.
        Parameters:
        pc - the target program counter
        Returns:
        the state when execution pauses or finishes
        Throws:
        IllegalStateException - if the session cannot step or has no current frame

      • isRunning

        public boolean isRunning()
        Returns:
        true if the session is running

      • isPaused

        public boolean isPaused()
        Returns:
        true if the session is paused

      • isStopped

        public boolean isStopped()
        Returns:
        true if the session is stopped

      • getCurrentState

        public DebugState getCurrentState()
        Returns:
        a freshly built snapshot of the session's execution state

      • getResult

        public BytecodeResult getResult()
        Returns the final execution result.
        Returns:
        the result of the finished execution
        Throws:
        IllegalStateException - if the session is not stopped

      • addBreakpoint

        public void addBreakpoint​(Breakpoint bp)
        Adds a breakpoint to the session's manager.
        Parameters:
        bp - the breakpoint to add

      • removeBreakpoint

        public void removeBreakpoint​(Breakpoint bp)
        Removes a breakpoint from the session's manager.
        Parameters:
        bp - the breakpoint to remove

      • getBreakpoints

        public List<Breakpoint> getBreakpoints()
        Returns:
        a copy of all registered breakpoints

      • getCurrentFrame

        public StackFrame getCurrentFrame()
        Returns:
        the frame on top of the call stack, or null if not started or empty

      • getCallStack

        public List<StackFrame> getCallStack()
        Returns:
        a snapshot of the current call stack, empty if not started

      • setLocalValue

        public void setLocalValue​(int slot,
                          ConcreteValue value)
        Overwrites a local variable slot in the current frame while paused.
        Parameters:
        slot - the local variable slot
        value - the replacement value
        Throws:
        IllegalStateException - if the session is not paused or there is no current frame
        IllegalArgumentException - if value is null

      • setStackValue

        public void setStackValue​(int index,
                          ConcreteValue value)
        Overwrites an operand stack entry in the current frame while paused.
        Parameters:
        index - the stack entry index
        value - the replacement value
        Throws:
        IllegalStateException - if the session is not paused or there is no current frame
        IllegalArgumentException - if value is null

      • addListener

        public void addListener​(DebugEventListener listener)
        Registers a debug event listener.
        Parameters:
        listener - the listener to add; ignored if null

      • removeListener

        public void removeListener​(DebugEventListener listener)
        Unregisters a debug event listener.
        Parameters:
        listener - the listener to remove; ignored if null