Package ghidra.trace.model.time.schedule

Class Sequence

java.lang.Object
ghidra.trace.model.time.schedule.Sequence
All Implemented Interfaces:
Comparable<Sequence>
public class Sequence extends Object implements Comparable<Sequence>
A sequence of thread steps, each repeated some number of times

  • Constructor Details

    • Sequence

      protected Sequence()

    • Sequence

      protected Sequence(List<Step> steps)

  • Method Details

    • parse

      public static Sequence parse(String seqSpec, TraceSchedule.TimeRadix radix)
      Parse (and normalize) a sequence of steps

      This takes a semicolon-separated list of steps in the form specified by Step.parse(String, TimeRadix). Each step may or may not specify a thread, but it's uncommon for any but the first step to omit the thread. The sequence is normalized as it is parsed, so any step after the first that omits a thread will be combined with the previous step. When the first step applies to the "last thread," it typically means the "event thread" of the source trace snapshot.

      Parameters:
      seqSpec - the string specification of the sequence
      radix - the radix
      Returns:
      the parsed sequence
      Throws:
      IllegalArgumentException - if the specification is of the wrong form

    • of

      public static Sequence of(Step... steps)
      Construct (and normalize) a sequence of the specified steps
      Parameters:
      steps - the desired steps in order
      Returns:
      the resulting sequence

    • of

      public static Sequence of(List<? extends Step> steps)
      Construct (and normalize) a sequence of the specified steps
      Parameters:
      steps - the desired steps in order
      Returns:
      the resulting sequence

    • catenate

      public static Sequence catenate(Sequence a, Sequence b)
      Construct (and normalize) a sequence formed by the steps in a followed by the steps in b
      Parameters:
      a - the first sequence
      b - the second (appended) sequence
      Returns:
      the resulting sequence

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toString

      public String toString(TraceSchedule.TimeRadix radix)

    • advance

      public void advance(Step step)
      Append the given step to this sequence
      Parameters:
      step - the step to append

    • advance

      public void advance(Sequence seq)
      Append the given sequence to this one
      Parameters:
      seq - the sequence to append

    • coalescePatches

      public void coalescePatches(Language language)

    • rewind

      public long rewind(long count)
      Rewind this sequence the given step count

      This modifies the sequence in place, removing the given count from the end of the sequence. Any step whose count is reduced to 0 as a result of rewinding is removed entirely from the sequence. Note that each sleigh step (modification) counts as one step when rewinding.

      Parameters:
      count - the step count to rewind
      Returns:
      if count exceeds the steps of this sequence, the (positive) difference remaining

    • clone

      public Sequence clone()
      Overrides:
      clone in class Object

    • getSteps

      public List<Step> getSteps()
      Obtain a clone of the steps

      Modifications to the returned steps have no effect on this sequence.

      Returns:
      the cloned steps

    • isNop

      public boolean isNop()
      Check if this sequence represents any actions
      Returns:
      true if the sequence is empty, false if not

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • compareSeq

      public CompareResult compareSeq(Sequence that)
      Richly compare two sequences

      The result indicates not only which is "less" or "greater" than the other, but also indicates whether the two are "related." Two sequences are considered related if one is the prefix to the other. More precisely, they are related if it's possible to transform one into the other solely by truncation (rewind) or solely by concatenation (advance). When related, the prefix is considered "less than" the other. Equal sequences are trivially related.

      Examples:

      • "" is related to and less than "10"
      • "10" is related and equal to "10"
      • "10" is related to and less than "11"
      • "t1-5" is related to and less than "t1-5;t2-4"
      • "t1-5" is un-related to and less than "t1-4;t2-4"

      The compareTo(Sequence) implementation defers to this method. Thus, in a sorted set of step sequences, the floor of a given sequence is will be the longest prefix in that set to the given sequence, assuming such a prefix is present.

      Parameters:
      that - the object of comparison (this being the subject)
      Returns:
      a result describing the relationship from subject to object

    • compareTo

      public int compareTo(Sequence that)
      Specified by:
      compareTo in interface Comparable<Sequence>

    • relativize

      public Sequence relativize(Sequence prefix)
      Compute the sequence which concatenated to the given prefix would result in this sequence

      The returned step sequence should not be manipulated, since it may just be this sequence.

      Parameters:
      prefix - the prefix
      Returns:
      the relative sequence from prefix to this
      Throws:
      IllegalArgumentException - if prefix is not a prefix of this sequence
      See Also:

    • totalTickCount

      public long totalTickCount()
      Compute to total number of ticks specified
      Returns:
      the total

    • totalSkipCount

      public long totalSkipCount()

    • totalPatchCount

      public long totalPatchCount()
      Compute to total number of patches specified
      Returns:
      the total

    • execute

      public TraceThread execute(Trace trace, TraceThread eventThread, PcodeMachine<?> machine, Stepper stepper, TaskMonitor monitor) throws CancelledException
      Execute this sequence upon the given machine

      Threads are retrieved from the database by key, then created in the machine (if not already present) named by TraceThread.getPath(). The caller should ensure the machine's state is bound to the given trace.

      Parameters:
      trace - the trace to which the machine is bound
      eventThread - the thread for the first step, if it applies to the "last thread"
      machine - the machine to step, or null to validate the sequence
      stepper - the actions to step each thread
      monitor - a monitor for cancellation and progress reports
      Returns:
      the last trace thread stepped during execution
      Throws:
      CancelledException - if execution is cancelled

    • validate

      public TraceThread validate(Trace trace, TraceThread eventThread)
      Validate this sequence for the given trace
      Parameters:
      trace - the trace
      eventThread - the thread for the first step, if it applies to the "last thread"
      Returns:
      the last trace thread that would be stepped by this sequence

    • getLastThreadKey

      public long getLastThreadKey()
      Get the key of the last thread stepped
      Returns:
      the key, or -1 if no step in the sequence specifies a thread

    • collectThreads

      public TraceThread collectThreads(Set<TraceThread> into, Trace trace, TraceThread eventThread)
      Collect all the threads involved in this sequence
      Parameters:
      into - a set to collect the threads
      trace - the trace whose threads to collect
      eventThread - the default starting thread
      Returns:
      the last thread named in the sequence

    • differsOnlyByPatch

      public boolean differsOnlyByPatch(Sequence that)