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:

    • setVersion

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

    • 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:

    • 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.