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