Package ghidra.trace.model.time

# Interface TraceTimeManager

All Known Implementing Classes:
  `DBTraceTimeManager`

public interface TraceTimeManager

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `KEY_TIME_RADIX`
  The attribute key for controlling the time radix

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TraceSnapshot`
  `createSnapshot(String description)`
  Create a new snapshot after the latest
  `TraceSnapshot`
  `findScratchSnapshot(TraceSchedule schedule)`
  Find or create a the snapshot with the given schedule
  `TraceSnapshot`
  `findSnapshotWithNearestPrefix(TraceSchedule schedule)`
  Find the nearest related snapshot whose schedule is a prefix of the given schedule
  `Collection<? extends TraceSnapshot>`
  `getAllSnapshots()`
  List all snapshots in the trace
  `Long`
  `getMaxSnap()`
  Get maximum snapshot key that has ever existed, usually that of the latest snapshot Note, the corresponding snapshot need not exist, as it may have been deleted.
  `TraceSnapshot`
  `getMostRecentSnapshot(long snap)`
  Get the most recent snapshot since a given key
  `TraceSnapshot`
  `getSnapshot(long snap, boolean createIfAbsent)`
  Get the snapshot with the given key, optionally creating it
  `long`
  `getSnapshotCount()`
  Get the number of snapshots
  `Collection<? extends TraceSnapshot>`
  `getSnapshots(long fromSnap, boolean fromInclusive, long toSnap, boolean toInclusive)`
  List all snapshots between two given snaps in the trace
  `Collection<? extends TraceSnapshot>`
  `getSnapshotsWithSchedule(TraceSchedule schedule)`
  Get all snapshots with the given schedule
  `TraceSchedule.TimeRadix`
  `getTimeRadix()`
  Get the radix for displaying and parsing time (snapshots and step counts)
  `void`
  `setTimeRadix(TraceSchedule.TimeRadix radix)`
  Set the radix for displaying and parsing time (snapshots and step counts)

- ## Field Details

  - ### KEY_TIME_RADIX

    static final String KEY_TIME_RADIX
    The attribute key for controlling the time radix
    See Also:
      - Constant Field Values

- ## Method Details

  - ### createSnapshot

    TraceSnapshot createSnapshot(String description)
    Create a new snapshot after the latest
    Parameters:
      `description` - a description of the new snapshot, i.e., the reason for advancing
    Returns:
      the created snapshot

  - ### getSnapshot

    TraceSnapshot getSnapshot(long snap, boolean createIfAbsent)
    Get the snapshot with the given key, optionally creating it
    Parameters:
      `snap` - the snapshot key
      `createIfAbsent` - create the snapshot if it's missing
    Returns:
      the snapshot or `null`

  - ### getMostRecentSnapshot

    TraceSnapshot getMostRecentSnapshot(long snap)
    Get the most recent snapshot since a given key
    Parameters:
      `snap` - the snapshot key
    Returns:
      the snapshot or `null`

  - ### getSnapshotsWithSchedule

    Collection<? extends TraceSnapshot> getSnapshotsWithSchedule(TraceSchedule schedule)
    Get all snapshots with the given schedule

    Ideally, the snapshot schedules should be managed such that the returned collection contains at most one snapshot.

    Parameters:
      `schedule` - the schedule to find
    Returns:
      the snapshots

  - ### findScratchSnapshot

    TraceSnapshot findScratchSnapshot(TraceSchedule schedule)
    Find or create a the snapshot with the given schedule

    If a snapshot with the given schedule already exists, this returns the first such snapshot found. Ideally, there is exactly one. If this method is consistently used for creating scratch snapshots, then that should always be the case. If no such snapshot exists, this creates a snapshot with the minimum available negative snapshot key, that is starting at `Long.MIN_VALUE` and increasing from there.

    Parameters:
      `schedule` - the schedule to find
    Returns:
      the snapshot

  - ### findSnapshotWithNearestPrefix

    TraceSnapshot findSnapshotWithNearestPrefix(TraceSchedule schedule)
    Find the nearest related snapshot whose schedule is a prefix of the given schedule

    This finds a snapshot that can be used as the initial state of an emulator to materialize the state at the given schedule. The one it returns is the one that would require the fewest instruction steps. Note that since an emulator cannot be initialized into the middle of an instruction, snapshots whose schedules contain p-code op steps are ignored. Additionally, this will ignore any snapshots whose version is less than the emulator cache version.

    Parameters:
      `schedule` - the desired schedule
    Returns:
      the found snapshot, or null
    See Also:
      - `Trace.getEmulatorCacheVersion()`

  - ### getAllSnapshots

    Collection<? extends TraceSnapshot> getAllSnapshots()
    List all snapshots in the trace
    Returns:
      the set of snapshots

  - ### getSnapshots

    Collection<? extends TraceSnapshot> getSnapshots(long fromSnap, boolean fromInclusive, long toSnap, boolean toInclusive)
    List all snapshots between two given snaps in the trace
    Parameters:
      `fromSnap` - the starting snap
      `fromInclusive` - whether to include the from snap
      `toSnap` - the ending snap
      `toInclusive` - when to include the to snap
    Returns:
      the set of snapshots

  - ### getMaxSnap

    Long getMaxSnap()
    Get maximum snapshot key that has ever existed, usually that of the latest snapshot Note, the corresponding snapshot need not exist, as it may have been deleted.
    Returns:
      the key, or `null` if no snapshots have existed

  - ### getSnapshotCount

    long getSnapshotCount()
    Get the number of snapshots
    Returns:
      the count

  - ### setTimeRadix

    void setTimeRadix(TraceSchedule.TimeRadix radix)
    Set the radix for displaying and parsing time (snapshots and step counts)

    This only affects the GUI, but storing it in the trace gives the back end a means of controlling it.

    Parameters:
      `radix` - the radix

  - ### getTimeRadix

    TraceSchedule.TimeRadix getTimeRadix()
    Get the radix for displaying and parsing time (snapshots and step counts)
    Returns:
      radix the radix
    See Also:
      - `setTimeRadix(TimeRadix)`