Package ghidra.trace.model.time

# Interface TraceSnapshot

All Known Implementing Classes:
  `DBTraceSnapshot`

public interface TraceSnapshot
A "snapshot in time" in a trace This is not so much a snapshot as it is simply a marker in time. Each manager handles time on its own, using the keys from these snapshots. Snapshot keys are called "snaps" for short. While a snapshot need not exist for another manager to use its numeric key, it is proper convention to create a snapshot before populating any other manager with corresponding entries. NOTE: There is a transitional phase here where some managers may still use "tick" instead of "snap".

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `delete()`
  Delete this snapshot This does not delete any entries in other managers associated with this snapshot.
  `String`
  `getDescription()`
  Get the description of the snapshot
  `TraceThread`
  `getEventThread()`
  If this snapshot was created because of an event, get the thread that caused it
  `long`
  `getKey()`
  Get a key which orders the snapshot chronologically
  `long`
  `getRealTime()`
  Get the real creation time of this snapshot in milliseconds since the epoch
  `TraceSchedule`
  `getSchedule()`
  Get the schedule, if applicable and known, relating this snapshot to a previous one
  `String`
  `getScheduleString()`
  Get the string representation of the schedule
  `Trace`
  `getTrace()`
  `long`
  `getVersion()`
  Get the snapshot's version, esp., when it represents a cache entry
  `boolean`
  `isSnapOnly(boolean whenInconsistent)`
  Check if a snapshot involves any steps of emulation
  `boolean`
  `isStale(boolean whenInconsistent)`
  For an emulated snapshot, check if re-emulation is necessary to produce an up-to-date snapshot.
  `void`
  `setDescription(String description)`
  Set the human-consumable description of the snapshot
  `void`
  `setEventThread(TraceThread thread)`
  If this snapshot was create because of an event, set the thread that caused it
  `void`
  `setRealTime(long millisSinceEpoch)`
  Set the real creation time of this snapshot in milliseconds since Jan 1, 1970 12:00 AM (UTC)
  `void`
  `setSchedule(TraceSchedule schedule)`
  Set the schedule from some previous snapshot to this one
  `void`
  `setVersion(long version)`
  Set the snapshot's version, esp., when it represents a cache entry

- ## Method Details

  - ### getTrace

    Trace getTrace()

  - ### getKey

    long getKey()
    Get a key which orders the snapshot chronologically
    Returns:
      the database key

  - ### getDescription

    String getDescription()
    Get the description of the snapshot
    Returns:
      the description

  - ### setDescription

    void setDescription(String description)
    Set the human-consumable description of the snapshot
    Parameters:
      `description` - the description

  - ### getRealTime

    long getRealTime()
    Get the real creation time of this snapshot in milliseconds since the epoch
    Returns:
      the real time

  - ### setRealTime

    void setRealTime(long millisSinceEpoch)
    Set the real creation time of this snapshot in milliseconds since Jan 1, 1970 12:00 AM (UTC)
    Parameters:
      `millisSinceEpoch` - the real time

  - ### getEventThread

    TraceThread getEventThread()
    If this snapshot was created because of an event, get the thread that caused it
    Returns:
      the event thread, if applicable

  - ### setEventThread

    void setEventThread(TraceThread thread)
    If this snapshot was create because of an event, set the thread that caused it
    Parameters:
      `thread` - the event thread, if applicable

  - ### getSchedule

    TraceSchedule getSchedule()
    Get the schedule, if applicable and known, relating this snapshot to a previous one

    This information is not always known, or even applicable. If recording a single step, ideally, this is simply the previous snap plus one step of the event thread, e.g., for snap 6, the schedule would be "5:1". For an emulated machine cached in scratch space, this should be the schedule that would recover the same machine state.

    The object managers in the trace pay no heed to this schedule. In particular, when retrieving the "most-recent" information from a snapshot with a known schedule, the "previous snap" part of that schedule is not taken into account. In other words, the managers still interpret time linearly, even though this schedule field might imply built-in forking.

    Returns:
      the (possibly null) schedule

  - ### getScheduleString

    String getScheduleString()
    Get the string representation of the schedule
    Returns:
      the (possibly empty) string representation of the schedule

  - ### setSchedule

    void setSchedule(TraceSchedule schedule)
    Set the schedule from some previous snapshot to this one
    Parameters:
      `schedule` - the schedule

  - ### getVersion

    long getVersion()
    Get the snapshot's version, esp., when it represents a cache entry
    Returns:
      the version
    See Also:
      - `Trace.getEmulatorCacheVersion()`

  - ### setVersion

    void setVersion(long version)
    Set the snapshot's version, esp., when it represents a cache entry
    Parameters:
      `version` - the version
    See Also:
      - `Trace.getEmulatorCacheVersion()`

  - ### isSnapOnly

    boolean isSnapOnly(boolean whenInconsistent)
    Check if a snapshot involves any steps of emulation

    A scratch snapshot, i.e., whose key is negative, without a schedule set is considered inconsistent.

    Parameters:
      `whenInconsistent` - the value to return for a scratch snapshot without a set schedule
    Returns:
      true if no emulation is involved

  - ### isStale

    boolean isStale(boolean whenInconsistent)
    For an emulated snapshot, check if re-emulation is necessary to produce an up-to-date snapshot.

    For non-emulated snapshots, this always returns false. A non-emulated snapshot is a snapshot whose schedule includes no emulation steps. An emulation snapshot is stale when its version is less than the trace's emulator cache version. A scratch snapshot, i.e., whose key is negative, without a schedule set is considered inconsistent.

    Parameters:
      `whenInconsistent` - the value to return for a scratch snapshot without a set schedule
    Returns:
      true if re-emulation is needed
    See Also:
      - `getVersion()`
      - `setVersion(long)`
      - `Trace.getEmulatorCacheVersion()`

  - ### delete

    void delete()
    Delete this snapshot This does not delete any entries in other managers associated with this snapshot. This simply deletes the marker and accompanying metadata. However, entries associated with deleted or otherwise non-existent snapshot keys may cause interesting behavior, especially for keys which exceed the latest snapshot key.