Package ghidra.debug.api.tracermi

Interface TraceRmiConnection

All Superinterfaces:
AutoCloseable
public interface TraceRmiConnection extends AutoCloseable
A connection to a TraceRmi back end

TraceRmi is a two-way request-reply channel, usually over TCP. The back end, i.e., the trace-rmi plugin hosted in the target platform's actual debugger, is granted a fixed set of methods/messages for creating and populating a Trace. Each such trace is designated as a target. The back end provides a set of methods for the front-end to use to control the connection and its targets. For a given connection, the methods are fixed, but each back end may provide a different set of methods to best describe/model its command set. The same methods are applicable to all of the back end's target. While uncommon, one back end may create several targets. E.g., if a target creates a child process, and the back-end debugger is configured to remain attached to both parent and child, then it should create and publish a second target.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Close the TraceRmi connection.
    void
    forceCloseTrace(Trace trace)
    Forcefully remove the given trace from the connection.
    void
    forciblyCloseTransactions(Target target)
    Forcibly commit all transactions this connection has on the given trace
    String
    getDescription()
    Get the client-given description of this connection
    long
    getLastSnapshot(Trace trace)
    Get the last snapshot created by the back end for the given trace.
    RemoteMethodRegistry
    getMethods()
    Get the methods provided by the back end
    SocketAddress
    getRemoteAddress()
    Get the address of the back end debugger
    Collection<Target>
    getTargets()
    Get all the valid targets created by this connection
    boolean
    isBusy()
    Check if the connection has a transaction open on any of its targets
    boolean
    isBusy(Target target)
    Check if the given target has a transaction open
    boolean
    isClosed()
    Check if the connection has been closed
    boolean
    isTarget(Trace trace)
    Check if the given trace represents one of this connection's targets.
    void
    waitClosed()
    Wait for the connection to become closed.
    Trace
    waitForTrace(long timeoutMillis)
    Wait for the first trace created by the back end.

  • Method Details

    • getDescription

      String getDescription()
      Get the client-given description of this connection

      If the connection is still being negotiated, this will return a string indicating that.

      Returns:
      the description

    • getRemoteAddress

      SocketAddress getRemoteAddress()
      Get the address of the back end debugger
      Returns:
      the address, usually IP of the host and port for the trace-rmi plugin.

    • getMethods

      RemoteMethodRegistry getMethods()
      Get the methods provided by the back end
      Returns:
      the method registry

    • waitForTrace

      Trace waitForTrace(long timeoutMillis) throws TimeoutException
      Wait for the first trace created by the back end.

      Typically, a connection handles only a single target. A shell script handles launching the back-end debugger, creating its first target, and connecting back to the front end via TraceRmi. If a secondary target does appear, it usually happens only after the initial target has run. Thus, this method is useful for waiting on and getting and handle to that initial target.

      Parameters:
      timeoutMillis - the number of milliseconds to wait for the target
      Returns:
      the trace
      Throws:
      TimeoutException - if no trace is created after the given timeout. This usually indicates there was an error launching the initial target, e.g., the target's binary was not found on the target's host.

    • getLastSnapshot

      long getLastSnapshot(Trace trace)
      Get the last snapshot created by the back end for the given trace.

      Back ends that support timeless or time-travel debugging have not been integrated yet, but in those cases, we anticipate this method returning the current snapshot (however the back end defines that with respect to its own definition of time), whether or not it is the last snapshot it created. If the back end has not created a snapshot yet, 0 is returned.

      Parameters:
      trace -
      Returns:
      the snapshot number
      Throws:
      NoSuchElementException - if the given trace is not a target for this connection

    • forceCloseTrace

      void forceCloseTrace(Trace trace)
      Forcefully remove the given trace from the connection.

      This removes the back end's access to the given trace and removes this connection from the trace's list of consumers (thus, freeing it if this was the only remaining consumer.) For all intents and purposes, the given trace is no longer a target for this connection.

      NOTE: This method should only be used if gracefully killing the target has failed. In some cases, it may be better to terminate the entire connection (See close()) or to terminate the back end debugger. The back end gets no notification that its trace was forcefully removed. However, subsequent requests involving that trace will result in errors.

      Parameters:
      trace - the trace to remove

    • close

      void close() throws IOException
      Close the TraceRmi connection.

      Upon closing, all the connection's targets (there's usually only one) will be withdrawn and invalidated.

      Specified by:
      close in interface AutoCloseable
      Throws:
      IOException

    • isClosed

      boolean isClosed()
      Check if the connection has been closed
      Returns:
      true if closed, false if still open/valid

    • waitClosed

      void waitClosed()
      Wait for the connection to become closed.

      This is usually just for clean-up purposes during automated testing.

    • isTarget

      boolean isTarget(Trace trace)
      Check if the given trace represents one of this connection's targets.
      Parameters:
      trace - the trace
      Returns:
      true if the trace is a target, false otherwise.

    • getTargets

      Collection<Target> getTargets()
      Get all the valid targets created by this connection
      Returns:
      the collection of valid targets

    • isBusy

      boolean isBusy()
      Check if the connection has a transaction open on any of its targets

      This generally means the connection has an open transaction. If does not indicate the execution state of the target/debuggee.

      Returns:
      true if busy

    • isBusy

      boolean isBusy(Target target)
      Check if the given target has a transaction open
      Parameters:
      target - the target
      Returns:
      true if busy

    • forciblyCloseTransactions

      void forciblyCloseTransactions(Target target)
      Forcibly commit all transactions this connection has on the given trace

      This may cause undefined behavior in the back-end, especially if it still needs the transaction.

      Parameters:
      target - the the target