Package ghidra.app.services

# Interface DebuggerLogicalBreakpointService

public interface DebuggerLogicalBreakpointService

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addChangeListener(LogicalBreakpointsChangeListener l)`
  Add a listener for logical breakpoint changes.
  `static Address`
  `addressFromLocation(ProgramLocation loc)`
  Get the address most likely intended by the user for a given location
  `default boolean`
  `anyMapped(Collection<LogicalBreakpoint> col)`
  `default boolean`
  `anyMapped(Collection<LogicalBreakpoint> col, Trace trace)`
  `CompletableFuture<Void>`
  `changesSettled()`
  Get a future which completes after pending changes have been processed
  `default LogicalBreakpoint.State`
  `computeState(ProgramLocation loc)`
  Compute the state for a given address and program or trace view
  `default LogicalBreakpoint.State`
  `computeState(Collection<LogicalBreakpoint> col)`
  `default LogicalBreakpoint.State`
  `computeState(Collection<LogicalBreakpoint> col, Program program)`
  `default LogicalBreakpoint.State`
  `computeState(Collection<LogicalBreakpoint> col, ProgramLocation loc)`
  `default LogicalBreakpoint.State`
  `computeState(Collection<LogicalBreakpoint> col, Trace trace)`
  `CompletableFuture<Void>`
  `deleteAll(Collection<LogicalBreakpoint> col, Trace trace)`
  Delete, if possible, a collection of logical breakpoints on target, if applicable
  `CompletableFuture<Void>`
  `deleteLocs(Collection<TraceBreakpointLocation> col)`
  Delete the given locations
  `CompletableFuture<Void>`
  `disableAll(Collection<LogicalBreakpoint> col, Trace trace)`
  Disable a collection of logical breakpoints on target, if applicable
  `CompletableFuture<Void>`
  `disableLocs(Collection<TraceBreakpointLocation> col)`
  Disable the given locations
  `CompletableFuture<Void>`
  `enableAll(Collection<LogicalBreakpoint> col, Trace trace)`
  Enable a collection of logical breakpoints on target, if applicable
  `CompletableFuture<Void>`
  `enableLocs(Collection<TraceBreakpointLocation> col)`
  Enable the given locations
  `String`
  `generateStatusEnable(Collection<LogicalBreakpoint> col, Trace trace)`
  Generate an informational status message when enabling the selected breakpoints
  `default String`
  `generateStatusToggleAt(ProgramLocation loc)`
  Generate an informational message when toggling the breakpoints at the given location
  `String`
  `generateStatusToggleAt(Set<LogicalBreakpoint> bs, ProgramLocation loc)`
  Generate an informational message when toggling the breakpoints
  `Set<LogicalBreakpoint>`
  `getAllBreakpoints()`
  Get all logical breakpoints known to the tool.
  `LogicalBreakpoint`
  `getBreakpoint(TraceBreakpointLocation loc)`
  Get the logical breakpoint of which the given trace breakpoint is a part
  `NavigableMap<Address,Set<LogicalBreakpoint>>`
  `getBreakpoints(Program program)`
  Get a map of addresses to collected logical breakpoints for a given program.
  `NavigableMap<Address,Set<LogicalBreakpoint>>`
  `getBreakpoints(Trace trace)`
  Get a map of addresses to collected logical breakpoints for a given trace.
  `Set<LogicalBreakpoint>`
  `getBreakpointsAt(Program program, Address address)`
  Get the collected logical breakpoints at the given program location.
  `Set<LogicalBreakpoint>`
  `getBreakpointsAt(ProgramLocation loc)`
  Get the collected logical breakpoints (at present) at the given location.
  `Set<LogicalBreakpoint>`
  `getBreakpointsAt(Trace trace, Address address)`
  Get the collected logical breakpoints at the given trace location.
  `CompletableFuture<Void>`
  `placeBreakpointAt(Program program, Address address, long length, Collection<TraceBreakpointKind> kinds, String name)`
  Create an enabled breakpoint at the given program location and each mapped trace location.
  `CompletableFuture<Void>`
  `placeBreakpointAt(ProgramLocation loc, long length, Collection<TraceBreakpointKind> kinds, String name)`
  Create an enabled breakpoint at the given location.
  `CompletableFuture<Void>`
  `placeBreakpointAt(Trace trace, Address address, long length, Collection<TraceBreakpointKind> kinds, String name)`
  Create an enabled breakpoint at the given trace location and its mapped program location.
  `static <T> T`
  `programOrTrace(ProgramLocation loc, BiFunction<? super Program,? super Address,? extends T> progFunc, BiFunction<? super Trace,? super Address,? extends T> traceFunc)`
  `void`
  `removeChangeListener(LogicalBreakpointsChangeListener l)`
  Remove a listener for logical breakpoint changes.
  `default CompletableFuture<Set<LogicalBreakpoint>>`
  `toggleBreakpointsAt(ProgramLocation location, Supplier<CompletableFuture<Set<LogicalBreakpoint>>> placer)`
  Toggle the breakpoints at the given location
  `CompletableFuture<Set<LogicalBreakpoint>>`
  `toggleBreakpointsAt(Set<LogicalBreakpoint> bs, ProgramLocation location, Supplier<CompletableFuture<Set<LogicalBreakpoint>>> placer)`
  Toggle the breakpoints at the given location

- ## Method Details

  - ### getAllBreakpoints

    Set<LogicalBreakpoint> getAllBreakpoints()
    Get all logical breakpoints known to the tool.
    Returns:
      the set of all logical breakpoints

  - ### getBreakpoints

    NavigableMap<Address,Set<LogicalBreakpoint>> getBreakpoints(Program program)
    Get a map of addresses to collected logical breakpoints for a given program.

    The program ought to be a program database, not a view of a trace.

    Parameters:
      `program` - the program database
    Returns:
      the map of logical breakpoints

  - ### getBreakpoints

    NavigableMap<Address,Set<LogicalBreakpoint>> getBreakpoints(Trace trace)
    Get a map of addresses to collected logical breakpoints for a given trace.

    The map only includes breakpoints visible in the trace's primary view. Visibility depends on the view's snapshot.

    Parameters:
      `trace` - the trace database
    Returns:
      the map of logical breakpoints

  - ### getBreakpointsAt

    Set<LogicalBreakpoint> getBreakpointsAt(Program program, Address address)
    Get the collected logical breakpoints at the given program location.

    The program ought to be a program database, not a view of a trace.

    Parameters:
      `program` - the program database
      `address` - the address
    Returns:
      the set of logical breakpoints

  - ### getBreakpointsAt

    Set<LogicalBreakpoint> getBreakpointsAt(Trace trace, Address address)
    Get the collected logical breakpoints at the given trace location.

    The set only includes breakpoints visible in the trace's primary view. Visibility depends on the view's snapshot.

    Parameters:
      `trace` - the trace database
      `address` - the address
    Returns:
      the set of logical breakpoints

  - ### getBreakpoint

    LogicalBreakpoint getBreakpoint(TraceBreakpointLocation loc)
    Get the logical breakpoint of which the given trace breakpoint is a part

    If the given trace breakpoint is not part of any logical breakpoint, e.g., because the trace is not opened in the tool or events are still being processed, then null is returned.

    Parameters:
      `loc` - the trace breakpoint location
    Returns:
      the logical breakpoint, or null

  - ### getBreakpointsAt

    Set<LogicalBreakpoint> getBreakpointsAt(ProgramLocation loc)
    Get the collected logical breakpoints (at present) at the given location.

    The `program` field for the location may be either a program database (static image) or a view for a trace. If it is the latter, the view's snapshot is ignored in favor of the trace's primary view's snapshot.

    If `program` is a static image, this is equivalent to using `getBreakpointsAt(Program, Address)`. If `program` is a trace view, this is equivalent to using `getBreakpointsAt(Trace, Address)`.

    Parameters:
      `loc` - the location
    Returns:
      the set of logical breakpoints

  - ### addChangeListener

    void addChangeListener(LogicalBreakpointsChangeListener l)
    Add a listener for logical breakpoint changes.

    Logical breakpoints may change from time to time for a variety of reasons: A new trace is started; a static image is opened; the user adds or removes breakpoints; mappings change; etc. The service reacts to these events, reconciles the breakpoints, and invokes callbacks for the changes, allowing other UI components and services to update accordingly.

    The listening component must maintain a strong reference to the listener, otherwise it will be removed and garbage collected. Automatic removal is merely a resource-management protection; the listening component should politely remove its listener (see `removeChangeListener(LogicalBreakpointsChangeListener)` when no longer needed.

    Parameters:
      `l` - the listener

  - ### removeChangeListener

    void removeChangeListener(LogicalBreakpointsChangeListener l)
    Remove a listener for logical breakpoint changes.
    Parameters:
      `l` - the listener to remove
    See Also:
      - `addChangeListener(LogicalBreakpointsChangeListener)`

  - ### changesSettled

    CompletableFuture<Void> changesSettled()
    Get a future which completes after pending changes have been processed

    The returned future completes after all change listeners have been invoked

    Returns:
      the future

  - ### addressFromLocation

    static Address addressFromLocation(ProgramLocation loc)
    Get the address most likely intended by the user for a given location

    Program locations always have addresses at the start of a code unit, no matter how the location was produced. This attempts to interpret the context a bit deeper to discern the user's intent. At the moment, it seems reasonable to check if the location includes a code unit. If so, take its min address, i.e., the location's address. If not, take the location's byte address.

    Parameters:
      `loc` - the location
    Returns:
      the address

  - ### programOrTrace

    static <T> T programOrTrace(ProgramLocation loc, BiFunction<? super Program,? super Address,? extends T> progFunc, BiFunction<? super Trace,? super Address,? extends T> traceFunc)

  - ### computeState

    default LogicalBreakpoint.State computeState(Collection<LogicalBreakpoint> col)

  - ### computeState

    default LogicalBreakpoint.State computeState(Collection<LogicalBreakpoint> col, Program program)

  - ### computeState

    default LogicalBreakpoint.State computeState(Collection<LogicalBreakpoint> col, Trace trace)

  - ### computeState

    default LogicalBreakpoint.State computeState(Collection<LogicalBreakpoint> col, ProgramLocation loc)

  - ### computeState

    default LogicalBreakpoint.State computeState(ProgramLocation loc)
    Compute the state for a given address and program or trace view
    Parameters:
      `loc` - the location
    Returns:
      the breakpoint state

  - ### anyMapped

    default boolean anyMapped(Collection<LogicalBreakpoint> col, Trace trace)

  - ### anyMapped

    default boolean anyMapped(Collection<LogicalBreakpoint> col)

  - ### placeBreakpointAt

    CompletableFuture<Void> placeBreakpointAt(Program program, Address address, long length, Collection<TraceBreakpointKind> kinds, String name)
    Create an enabled breakpoint at the given program location and each mapped trace location.

    The implementation should take care not to create the same breakpoint multiple times. The risk of this happening derives from the possibility of one module mapped to multiple targets which are all managed by the same debugger, having a single breakpoint container.

    Parameters:
      `program` - the static module image
      `address` - the address in the image
      `length` - size of the breakpoint, may be ignored by debugger
      `kinds` - the kinds of breakpoint
      `name` - a name for the breakpoint. For no name, use the empty string
    Returns:
      a future which completes when all relevant breakpoints have been placed

  - ### placeBreakpointAt

    CompletableFuture<Void> placeBreakpointAt(Trace trace, Address address, long length, Collection<TraceBreakpointKind> kinds, String name)
    Create an enabled breakpoint at the given trace location and its mapped program location.

    If the breakpoint has no static location, then only the trace location is placed. Note, if this is the case, the breakpoint will have no name.

    Note for live targets, the debugger ultimately determines the placement behavior. If it is managing multiple targets, it is possible the breakpoint will be effective in another trace. This fact should be reflected correctly in the resulting logical markings once all resulting events have been processed.

    Parameters:
      `trace` - the given trace
      `address` - the address in the trace (as viewed in the present)
      `length` - size of the breakpoint, may be ignored by debugger
      `kinds` - the kinds of breakpoint
      `name` - a name for the breakpoint
    Returns:
      a future which completes when the breakpoint has been placed

  - ### placeBreakpointAt

    CompletableFuture<Void> placeBreakpointAt(ProgramLocation loc, long length, Collection<TraceBreakpointKind> kinds, String name)
    Create an enabled breakpoint at the given location.

    If the given location refers to a static image, this behaves as in `placeBreakpointAt(Program, Address, long, Collection, String)`. If it refers to a trace view, this behaves as in * `placeBreakpointAt(Trace, Address, long, Collection, String)`, ignoring the view's current snapshot in favor of the present. The name is only saved for a program breakpoint.

    Parameters:
      `loc` - the location
      `length` - size of the breakpoint, may be ignored by debugger
      `kinds` - the kinds of breakpoint
      `name` - an optional name for the breakpoint (null becomes the empty string)
    Returns:
      a future which completes when the breakpoints have been placed

  - ### generateStatusEnable

    String generateStatusEnable(Collection<LogicalBreakpoint> col, Trace trace)
    Generate an informational status message when enabling the selected breakpoints

    Breakpoint enabling may fail for a variety of reasons. Some of those reasons deal with the trace database and GUI rather than with the target. When enabling will not likely behave in the manner expected by the user, this should provide a message explaining why. For example, if a breakpoint has no locations on a target, then we already know "enable" will not work. This should explain the situation to the user. If enabling is expected to work, then this should return null.

    Parameters:
      `col` - the collection we're about to enable
      `trace` - a trace, if the command will be limited to the given trace
    Returns:
      the status message, or null

  - ### enableAll

    CompletableFuture<Void> enableAll(Collection<LogicalBreakpoint> col, Trace trace)
    Enable a collection of logical breakpoints on target, if applicable

    This method is preferable to calling `LogicalBreakpoint.enable()` on each logical breakpoint, because depending on the debugger, a single breakpoint specification may produce several effective breakpoints, perhaps spanning multiple targets. While not terribly critical, this method will prevent multiple requests (which a debugger may consider erroneous) to enable the same specification, if that specification happens to be involved in more than one logical breakpoint in the given collection.

    Parameters:
      `col` - the collection
      `trace` - a trace, if the command should be limited to the given trace
    Returns:
      a future which completes when all associated specifications have been enabled

  - ### disableAll

    CompletableFuture<Void> disableAll(Collection<LogicalBreakpoint> col, Trace trace)
    Disable a collection of logical breakpoints on target, if applicable
    Parameters:
      `col` - the collection
      `trace` - a trace, if the command should be limited to the given trace
    Returns:
      a future which completes when all associated specifications have been disabled
    See Also:
      - `enableAll(Collection, Trace)`

  - ### deleteAll

    CompletableFuture<Void> deleteAll(Collection<LogicalBreakpoint> col, Trace trace)
    Delete, if possible, a collection of logical breakpoints on target, if applicable
    Parameters:
      `col` - the collection
      `trace` - a trace, if the command should be limited to the given trace
    Returns:
      a future which completes when all associated specifications have been deleted
    See Also:
      - `enableAll(Collection, Trace)`

  - ### enableLocs

    CompletableFuture<Void> enableLocs(Collection<TraceBreakpointLocation> col)
    Enable the given locations
    Parameters:
      `col` - the trace breakpoints
    Returns:
      a future which completes when the command has been processed

  - ### disableLocs

    CompletableFuture<Void> disableLocs(Collection<TraceBreakpointLocation> col)
    Disable the given locations
    Parameters:
      `col` - the trace breakpoints
    Returns:
      a future which completes when the command has been processed

  - ### deleteLocs

    CompletableFuture<Void> deleteLocs(Collection<TraceBreakpointLocation> col)
    Delete the given locations
    Parameters:
      `col` - the trace breakpoints
    Returns:
      a future which completes when the command has been processed

  - ### generateStatusToggleAt

    String generateStatusToggleAt(Set<LogicalBreakpoint> bs, ProgramLocation loc)
    Generate an informational message when toggling the breakpoints

    This works in the same manner as `generateStatusEnable(Collection, Trace)`, except it is for toggling breakpoints. If the breakpoint set is empty, this should return null, since the usual behavior in that case is to prompt to place a new breakpoint.

    Parameters:
      `bs` - the set of logical breakpoints
      `loc` - a representative location
    Returns:
      the status message, or null
    See Also:
      - `generateStatusEnable(Collection, Trace)`

  - ### generateStatusToggleAt

    default String generateStatusToggleAt(ProgramLocation loc)
    Generate an informational message when toggling the breakpoints at the given location

    This works in the same manner as `generateStatusEnable(Collection, Trace)`, except it is for toggling breakpoints at a given location. If there are no breakpoints at the location, this should return null, since the usual behavior in that case is to prompt to place a new breakpoint.

    Parameters:
      `loc` - the location
    Returns:
      the status message, or null
    See Also:
      - `generateStatusEnable(Collection, Trace)`

  - ### toggleBreakpointsAt

    CompletableFuture<Set<LogicalBreakpoint>> toggleBreakpointsAt(Set<LogicalBreakpoint> bs, ProgramLocation location, Supplier<CompletableFuture<Set<LogicalBreakpoint>>> placer)
    Toggle the breakpoints at the given location
    Parameters:
      `bs` - the set of breakpoints to toggle
      `location` - the location
      `placer` - if the breakpoint set is empty, a routine for placing a breakpoint
    Returns:
      a future which completes when the command has been processed

  - ### toggleBreakpointsAt

    default CompletableFuture<Set<LogicalBreakpoint>> toggleBreakpointsAt(ProgramLocation location, Supplier<CompletableFuture<Set<LogicalBreakpoint>>> placer)
    Toggle the breakpoints at the given location
    Parameters:
      `location` - the location
      `placer` - if there are no breakpoints, a routine for placing a breakpoint
    Returns:
      a future which completes when the command has been processed