Package ghidra.app.services

# Interface DebuggerTraceManagerService

public interface DebuggerTraceManagerService
The interface for managing open traces and navigating among them and their contents

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static enum`
  `DebuggerTraceManagerService.ActivationCause`
  The reason coordinates were activated
  `static interface`
  `DebuggerTraceManagerService.BooleanChangeAdapter`
  An adapter that works nicely with an `AsyncReference`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default void`
  `activate(DebuggerCoordinates coordinates)`
  Activate the given coordinates, caused by the user
  `void`
  `activate(DebuggerCoordinates coordinates, DebuggerTraceManagerService.ActivationCause cause)`
  Activate the given coordinates, synchronizing the current target, if possible
  `CompletableFuture<Void>`
  `activateAndNotify(DebuggerCoordinates coordinates, DebuggerTraceManagerService.ActivationCause cause)`
  Activate the given coordinates with future notification
  `default void`
  `activateFrame(int frameLevel)`
  Activate the given stack frame
  `default void`
  `activateObject(TraceObject object)`
  Activate the given object
  `default void`
  `activatePath(KeyPath path)`
  Activate the given canonical object path
  `default void`
  `activatePlatform(TracePlatform platform)`
  Activate the given platform
  `default void`
  `activateSnap(long snap)`
  Activate the given snapshot key
  `default void`
  `activateTarget(Target target)`
  Activate the given target
  `default void`
  `activateThread(TraceThread thread)`
  Activate the given thread
  `default void`
  `activateTime(TraceSchedule time)`
  Activate the given point in time, possibly invoking emulation
  `default void`
  `activateTrace(Trace trace)`
  Activate the given trace
  `void`
  `addAutoCloseOnTerminateChangeListener(DebuggerTraceManagerService.BooleanChangeAdapter listener)`
  Add a listener for changes to close-on-terminate enablement
  `void`
  `addSaveTracesByDefaultChangeListener(DebuggerTraceManagerService.BooleanChangeAdapter listener)`
  Add a listener for changes to save-by-default enablement
  `void`
  `closeAllTraces()`
  Close all traces
  `void`
  `closeDeadTraces()`
  Close all traces which are not the destination of a live recording
  `void`
  `closeOtherTraces(Trace keep)`
  Close all traces except the given one
  `void`
  `closeTrace(Trace trace)`
  Close the given trace
  `void`
  `closeTraceNoConfirm(Trace trace)`
  Close the given trace without confirmation
  `Long`
  `findSnapshot(DebuggerCoordinates coordinates)`
  If the given coordinates are already materialized, get the snapshot
  `DebuggerCoordinates`
  `getCurrent()`
  Get the current coordinates
  `DebuggerCoordinates`
  `getCurrentFor(Trace trace)`
  Get the current coordinates for a given trace
  `int`
  `getCurrentFrame()`
  Get the active frame
  `TraceObject`
  `getCurrentObject()`
  Get the active object
  `TracePlatform`
  `getCurrentPlatform()`
  Get the active platform
  `long`
  `getCurrentSnap()`
  Get the active snap
  `TraceThread`
  `getCurrentThread()`
  Get the active thread
  `Trace`
  `getCurrentTrace()`
  Get the active trace
  `TraceProgramView`
  `getCurrentView()`
  Get the active view
  `Collection<Trace>`
  `getOpenTraces()`
  Get all the open traces
  `boolean`
  `isAutoCloseOnTerminate()`
  Check whether live traces are automatically closed upon target termination
  `boolean`
  `isSaveTracesByDefault()`
  Check whether traces should by saved by default
  `CompletableFuture<Long>`
  `materialize(DebuggerCoordinates coordinates)`
  Materialize the given coordinates to a snapshot in the same trace
  `Trace`
  `openTrace(DomainFile file, int version)`
  Open a trace from a domain file
  `void`
  `openTrace(Trace trace)`
  Open a trace
  `Collection<Trace>`
  `openTraces(Collection<DomainFile> files)`
  Open traces from a collection of domain files
  `void`
  `removeAutoCloseOnTerminateChangeListener(DebuggerTraceManagerService.BooleanChangeAdapter listener)`
  Remove a listener for changes to close-on-terminate enablement
  `void`
  `removeSaveTracesByDefaultChangeListener(DebuggerTraceManagerService.BooleanChangeAdapter listener)`
  Remove a listener for changes to save-by-default enablement
  `DebuggerCoordinates`
  `resolveFrame(int frameLevel)`
  Resolve coordinates for the given frame level using the manager's "best judgment"
  `DebuggerCoordinates`
  `resolveObject(TraceObject object)`
  Resolve coordinates for the given object using the manager's "best judgment"
  `DebuggerCoordinates`
  `resolvePath(KeyPath path)`
  Resolve coordinates for the given object path using the manager's "best judgment"
  `DebuggerCoordinates`
  `resolvePlatform(TracePlatform platform)`
  Resolve coordinates for the given platform using the manager's "best judgment"
  `DebuggerCoordinates`
  `resolveSnap(long snap)`
  Resolve coordinates for the given snap using the manager's "best judgment"
  `DebuggerCoordinates`
  `resolveTarget(Target target)`
  Resolve coordinates for the given target using the manager's "best judgment"
  `DebuggerCoordinates`
  `resolveThread(TraceThread thread)`
  Resolve coordinates for the given thread using the manager's "best judgment"
  `DebuggerCoordinates`
  `resolveTime(TraceSchedule time)`
  Resolve coordinates for the given time using the manager's "best judgment"
  `DebuggerCoordinates`
  `resolveTrace(Trace trace)`
  Resolve coordinates for the given trace using the manager's "best judgment"
  `DebuggerCoordinates`
  `resolveView(TraceProgramView view)`
  Resolve coordinates for the given view using the manager's "best judgment"
  `CompletableFuture<Void>`
  `saveTrace(Trace trace)`
  Save the trace to the "New Traces" folder of the project
  `void`
  `setAutoCloseOnTerminate(boolean enabled)`
  Control whether live traces are automatically closed upon target termination
  `void`
  `setSaveTracesByDefault(boolean enabled)`
  Control whether traces should be saved by default

- ## Method Details

  - ### getOpenTraces

    Collection<Trace> getOpenTraces()
    Get all the open traces
    Returns:
      all open traces

  - ### getCurrent

    DebuggerCoordinates getCurrent()
    Get the current coordinates

    This entails everything except the current address.

    Returns:
      the current coordinates

  - ### getCurrentFor

    DebuggerCoordinates getCurrentFor(Trace trace)
    Get the current coordinates for a given trace
    Parameters:
      `trace` - the trace
    Returns:
      the current coordinates for the trace

  - ### getCurrentTrace

    Trace getCurrentTrace()
    Get the active trace
    Returns:
      the active trace, or null

  - ### getCurrentPlatform

    TracePlatform getCurrentPlatform()
    Get the active platform
    Returns:
      the active platform, or null

  - ### getCurrentView

    TraceProgramView getCurrentView()
    Get the active view

    Every trace has an associated variable-snap view. When the manager navigates to a new point in time, it is accomplished by changing the snap of this view. This view is suitable for use in most places where a `Program` is ordinarily required.

    Returns:
      the active view, or null

  - ### getCurrentThread

    TraceThread getCurrentThread()
    Get the active thread

    It is possible to have an active trace, but no active thread.

    Returns:
      the active thread, or null

  - ### getCurrentSnap

    long getCurrentSnap()
    Get the active snap

    Note that if emulation was used to materialize the current coordinates, then the current snap will differ from the view's snap.

    Returns:
      the active snap, or 0

  - ### getCurrentFrame

    int getCurrentFrame()
    Get the active frame
    Returns:
      the active frame, or 0

  - ### getCurrentObject

    TraceObject getCurrentObject()
    Get the active object
    Returns:
      the active object, or null

  - ### openTrace

    void openTrace(Trace trace)
    Open a trace

    This does not activate the trace. Use `activateTrace(Trace)` or `activateThread(TraceThread)` if necessary.

    Parameters:
      `trace` - the trace to open

  - ### openTrace

    Trace openTrace(DomainFile file, int version)
    Open a trace from a domain file
    Parameters:
      `file` - the domain file to open
      `version` - the version (read-only if non-default)
    Returns:
      the trace
    Throws:
      `ClassCastException` - if the domain object contains a non-trace object

  - ### openTraces

    Collection<Trace> openTraces(Collection<DomainFile> files)
    Open traces from a collection of domain files

    Iterating the returned trace collection orders each trace by position of its file in the input file collection.

    Parameters:
      `files` - the domain files
    Returns:
      the traces opened

  - ### saveTrace

    CompletableFuture<Void> saveTrace(Trace trace)
    Save the trace to the "New Traces" folder of the project

    If a different domain file of the trace's name already exists, an incrementing integer is appended. Errors are handled in the same fashion as saving a program, so there is little/no need to invoke `CompletableFuture.exceptionally(java.util.function.Function)` on the returned future. The future is returned as a means of registering follow-up actions.

    TODO: Support save-as, prompting to overwrite, etc?

    Parameters:
      `trace` - the trace to save
    Returns:
      a future which completes when the save is finished

  - ### closeTrace

    void closeTrace(Trace trace)
    Close the given trace
    Parameters:
      `trace` - the trace to close

  - ### closeTraceNoConfirm

    void closeTraceNoConfirm(Trace trace)
    Close the given trace without confirmation

    Ordinarily, `closeTrace(Trace)` will prompt the user to confirm termination of live targets associated with traces to be closed. Such prompts can cause issues during automated tests.

    Parameters:
      `trace` - the trace to close

  - ### closeAllTraces

    void closeAllTraces()
    Close all traces

  - ### closeOtherTraces

    void closeOtherTraces(Trace keep)
    Close all traces except the given one
    Parameters:
      `keep` - the trace to keep open

  - ### closeDeadTraces

    void closeDeadTraces()
    Close all traces which are not the destination of a live recording

    Operation of this method depends on the model service. If that service is not present, this method performs no operation at all.

  - ### activateAndNotify

    CompletableFuture<Void> activateAndNotify(DebuggerCoordinates coordinates, DebuggerTraceManagerService.ActivationCause cause)
    Activate the given coordinates with future notification

    This operation may be completed asynchronously, esp., if emulation is required to materialize the coordinates. The returned future is completed when the coordinates are actually materialized and active. The coordinates are "resolved" as a means of filling in missing parts. For example, if the thread is not specified, the manager may activate the last-active thread for the desired trace.

    Parameters:
      `coordinates` - the desired coordinates
      `cause` - the cause of the activation
    Returns:
      a future which completes when emulation and navigation is complete

  - ### activate

    default void activate(DebuggerCoordinates coordinates)
    Activate the given coordinates, caused by the user
    Parameters:
      `coordinates` - the desired coordinates
    See Also:
      - `activate(DebuggerCoordinates, ActivationCause)`

  - ### activate

    void activate(DebuggerCoordinates coordinates, DebuggerTraceManagerService.ActivationCause cause)
    Activate the given coordinates, synchronizing the current target, if possible

    If asynchronous notification is needed, use `activateAndNotify(DebuggerCoordinates, ActivationCause)`.

    Parameters:
      `coordinates` - the desired coordinates
      `cause` - the cause of activation

  - ### resolveTrace

    DebuggerCoordinates resolveTrace(Trace trace)
    Resolve coordinates for the given trace using the manager's "best judgment"

    The manager may use a variety of sources of context including the current trace, the last coordinates for a trace, the target's last/current activation, the list of live threads, etc.

    Parameters:
      `trace` - the trace
    Returns:
      the best coordinates

  - ### activateTrace

    default void activateTrace(Trace trace)
    Activate the given trace
    Parameters:
      `trace` - the desired trace

  - ### resolveTarget

    DebuggerCoordinates resolveTarget(Target target)
    Resolve coordinates for the given target using the manager's "best judgment"
    Parameters:
      `target` - the target
    Returns:
      the best coordinates
    See Also:
      - `resolveTrace(Trace)`

  - ### activateTarget

    default void activateTarget(Target target)
    Activate the given target
    Parameters:
      `target` - the desired target

  - ### resolvePlatform

    DebuggerCoordinates resolvePlatform(TracePlatform platform)
    Resolve coordinates for the given platform using the manager's "best judgment"
    Parameters:
      `platform` - the platform
    Returns:
      the best coordinates
    See Also:
      - `resolveTrace(Trace)`

  - ### activatePlatform

    default void activatePlatform(TracePlatform platform)
    Activate the given platform
    Parameters:
      `platform` - the desired platform

  - ### resolveThread

    DebuggerCoordinates resolveThread(TraceThread thread)
    Resolve coordinates for the given thread using the manager's "best judgment"
    Parameters:
      `thread` - the thread
    Returns:
      the best coordinates
    See Also:
      - `resolveTrace(Trace)`

  - ### activateThread

    default void activateThread(TraceThread thread)
    Activate the given thread
    Parameters:
      `thread` - the desired thread

  - ### resolveSnap

    DebuggerCoordinates resolveSnap(long snap)
    Resolve coordinates for the given snap using the manager's "best judgment"
    Parameters:
      `snap` - the snapshot key
    Returns:
      the best coordinates
    See Also:
      - `resolveTrace(Trace)`

  - ### activateSnap

    default void activateSnap(long snap)
    Activate the given snapshot key
    Parameters:
      `snap` - the desired snapshot key

  - ### resolveTime

    DebuggerCoordinates resolveTime(TraceSchedule time)
    Resolve coordinates for the given time using the manager's "best judgment"
    Parameters:
      `time` - the time
    Returns:
      the best coordinates
    See Also:
      - `resolveTrace(Trace)`

  - ### activateTime

    default void activateTime(TraceSchedule time)
    Activate the given point in time, possibly invoking emulation
    Parameters:
      `time` - the desired schedule

  - ### resolveView

    DebuggerCoordinates resolveView(TraceProgramView view)
    Resolve coordinates for the given view using the manager's "best judgment"
    Parameters:
      `view` - the view
    Returns:
      the best coordinates
    See Also:
      - `resolveTrace(Trace)`

  - ### resolveFrame

    DebuggerCoordinates resolveFrame(int frameLevel)
    Resolve coordinates for the given frame level using the manager's "best judgment"
    Parameters:
      `frameLevel` - the frame level, 0 being the innermost
    Returns:
      the best coordinates
    See Also:
      - `resolveTrace(Trace)`

  - ### activateFrame

    default void activateFrame(int frameLevel)
    Activate the given stack frame
    Parameters:
      `frameLevel` - the level of the desired frame, 0 being innermost

  - ### resolvePath

    DebuggerCoordinates resolvePath(KeyPath path)
    Resolve coordinates for the given object path using the manager's "best judgment"
    Parameters:
      `path` - the path
    Returns:
      the best coordinates
    See Also:
      - `resolveTrace(Trace)`

  - ### activatePath

    default void activatePath(KeyPath path)
    Activate the given canonical object path
    Parameters:
      `path` - the desired path

  - ### resolveObject

    DebuggerCoordinates resolveObject(TraceObject object)
    Resolve coordinates for the given object using the manager's "best judgment"
    Parameters:
      `object` - the object
    Returns:
      the best coordinates
    See Also:
      - `resolveTrace(Trace)`

  - ### activateObject

    default void activateObject(TraceObject object)
    Activate the given object
    Parameters:
      `object` - the desired object

  - ### setSaveTracesByDefault

    void setSaveTracesByDefault(boolean enabled)
    Control whether traces should be saved by default
    Parameters:
      `enabled` - true to save by default, false otherwise

  - ### isSaveTracesByDefault

    boolean isSaveTracesByDefault()
    Check whether traces should by saved by default
    Returns:
      true if saved by default, false otherwise

  - ### addSaveTracesByDefaultChangeListener

    void addSaveTracesByDefaultChangeListener(DebuggerTraceManagerService.BooleanChangeAdapter listener)
    Add a listener for changes to save-by-default enablement
    Parameters:
      `listener` - the listener to receive change notifications

  - ### removeSaveTracesByDefaultChangeListener

    void removeSaveTracesByDefaultChangeListener(DebuggerTraceManagerService.BooleanChangeAdapter listener)
    Remove a listener for changes to save-by-default enablement
    Parameters:
      `listener` - the listener receiving change notifications

  - ### setAutoCloseOnTerminate

    void setAutoCloseOnTerminate(boolean enabled)
    Control whether live traces are automatically closed upon target termination
    Parameters:
      `enabled` - true to automatically close, false to leave open

  - ### isAutoCloseOnTerminate

    boolean isAutoCloseOnTerminate()
    Check whether live traces are automatically closed upon target termination
    Returns:
      true if automatically closed, false if left open

  - ### addAutoCloseOnTerminateChangeListener

    void addAutoCloseOnTerminateChangeListener(DebuggerTraceManagerService.BooleanChangeAdapter listener)
    Add a listener for changes to close-on-terminate enablement
    Parameters:
      `listener` - the listener to receive change notifications

  - ### removeAutoCloseOnTerminateChangeListener

    void removeAutoCloseOnTerminateChangeListener(DebuggerTraceManagerService.BooleanChangeAdapter listener)
    Remove a listener for changes to close-on-terminate enablement
    Parameters:
      `listener` - the listener receiving change notifications

  - ### findSnapshot

    Long findSnapshot(DebuggerCoordinates coordinates)
    If the given coordinates are already materialized, get the snapshot

    If the coordinates do not include a schedule, this simply returns the coordinates' snapshot. Otherwise, it searches for the first snapshot whose schedule is the coordinates' schedule.

    Parameters:
      `coordinates` - the coordinates
    Returns:
      the materialized snapshot key, or null if not materialized.

  - ### materialize

    CompletableFuture<Long> materialize(DebuggerCoordinates coordinates)
    Materialize the given coordinates to a snapshot in the same trace

    If the given coordinates do not require emulation, then this must complete immediately with the snapshot key given by the coordinates. If the given schedule is already materialized in the trace, then this may complete immediately with the previously-materialized snapshot key. Otherwise, this must invoke emulation, store the result into a chosen snapshot, and complete with its key.

    Parameters:
      `coordinates` - the coordinates to materialize
    Returns:
      a future that completes with the snapshot key of the materialized coordinates