org.eclipse.viatra.query.runtime.matchers.util

## Class TimelyMemory<Timestamp extends java.lang.Comparable<Timestamp>>

- java.lang.Object
- - org.eclipse.viatra.query.runtime.matchers.util.TimelyMemory<Timestamp>

- All Implemented Interfaces:
    Clearable, Resumable<Timestamp>, UnmaskedResumable<Timestamp>

      public class TimelyMemory<Timestamp extends java.lang.Comparable<Timestamp>>
      extends java.lang.Object
      implements Clearable, UnmaskedResumable<Timestamp>

  A timely memory implementation that incrementally maintains the `Timeline`s of tuples. The memory is capable of lazy folding (see `Resumable`).
  Since:
    2.3

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `TimelyMemory.CumulativeCounter`
    `protected static class` | `TimelyMemory.FoldingState`
    `protected static class` | `TimelyMemory.SignChange`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.util.Map<Tuple,java.util.TreeMap<Timestamp,TimelyMemory.CumulativeCounter>>` | `counters`
    `protected Diff<Timestamp>` | `EMPTY_DIFF`
    `java.util.TreeMap<Timestamp,java.util.Map<Tuple,TimelyMemory.FoldingState>>` | `foldingState`
    `protected boolean` | `isLazy`
    `protected java.util.Set<Tuple>` | `presentAtInfinity`
    `protected java.util.Map<Tuple,Timeline<Timestamp>>` | `timelines`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TimelyMemory()`
    `TimelyMemory(boolean isLazy)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `addFoldingState(Tuple tuple, TimelyMemory.FoldingState state, Timestamp timestamp)` Registers the given folding state for the specified timestamp and tuple.
    `java.util.Map<Tuple,Timeline<Timestamp>>` | `asMap()`
    `void` | `clear()` Clear all partial matchings stored in memory
    `protected TimelyMemory.SignChange` | `computeDiffsEager(Direction direction, TimelyMemory.CumulativeCounter counter, TimelyMemory.SignChange signChangeAtPrevious, Timestamp timestamp, Diff<Timestamp> diffs)` Utility method that computes the timeline diffs in case of eager memories.
    `protected void` | `computeDiffsLazy(Direction direction, int oldCumulative, int newCumulative, Timestamp timestamp, Timestamp nextTimestamp, Diff<Timestamp> diffs)` Utility method that computes the timeline diffs in case of lazy memories.
    `boolean` | `containsKey(ITuple tuple)`
    `protected Diff<Timestamp>` | `doFoldingStep(Tuple tuple, TimelyMemory.FoldingState state, Timestamp timestamp)`
    `protected void` | `gcCounters(TimelyMemory.CumulativeCounter counter, Tuple tuple, Timestamp timestamp)` Garbage collects the counter of the given tuple and timestamp if the new diff is zero.
    `Timeline<Timestamp>` | `get(ITuple tuple)`
    `int` | `getCountAtInfinity()` Returns the number of tuples that are present at the moment 'infinity'.
    `protected TimelyMemory.CumulativeCounter` | `getCounter(Tuple tuple, Timestamp timestamp)` On-demand initializes and returns the counter for the given tuple and timestamp.
    `Timestamp` | `getResumableTimestamp()` Returns the smallest timestamp where lazy folding shall be resumed, or null if there is no more folding to do in this resumable.
    `java.util.Set<Tuple>` | `getResumableTuples()` Returns the set of tuples for which lazy folding shall be resumed at the next timestamp.
    `java.util.Collection<Tuple>` | `getTuplesAtInfinity()`
    `boolean` | `isEmpty()`
    `boolean` | `isPresentAtInfinity(Tuple tuple)` Returns true if the given tuple is present at the moment 'infinity'.
    `java.util.Set<Tuple>` | `keySet()`
    `Diff<Timestamp>` | `put(Tuple tuple, Timestamp timestamp)`
    `protected Diff<Timestamp>` | `putEager(Tuple tuple, Timestamp timestamp)`
    `protected Diff<Timestamp>` | `putLazy(Tuple tuple, Timestamp timestamp)`
    `Diff<Timestamp>` | `remove(Tuple tuple, Timestamp timestamp)`
    `protected Diff<Timestamp>` | `removeEager(Tuple tuple, Timestamp timestamp)`
    `protected Diff<Timestamp>` | `removeLazy(Tuple tuple, Timestamp timestamp)`
    `java.util.Map<Tuple,Diff<Timestamp>>` | `resumeAt(Timestamp timestamp)` When called, the folding of the state shall be resumed at the given timestamp.
    `int` | `size()`
    `java.lang.String` | `toString()`
    `protected void` | `updateTimeline(Tuple tuple, Diff<Timestamp> diff)` Updates and garbage collects the timeline of the given tuple based on the given timeline diff.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### counters

          protected final java.util.Map<Tuple,java.util.TreeMap<Timestamp extends java.lang.Comparable<Timestamp>,TimelyMemory.CumulativeCounter>> counters

    - #### timelines

          protected final java.util.Map<Tuple,Timeline<Timestamp extends java.lang.Comparable<Timestamp>>> timelines

    - #### foldingState

          public final java.util.TreeMap<Timestamp extends java.lang.Comparable<Timestamp>,java.util.Map<Tuple,TimelyMemory.FoldingState>> foldingState

    - #### presentAtInfinity

          protected final java.util.Set<Tuple> presentAtInfinity

    - #### isLazy

          protected final boolean isLazy

    - #### EMPTY_DIFF

          protected final Diff<Timestamp extends java.lang.Comparable<Timestamp>> EMPTY_DIFF

  - ### Constructor Detail

    - #### TimelyMemory

          public TimelyMemory()

    - #### TimelyMemory

          public TimelyMemory(boolean isLazy)

  - ### Method Detail

    - #### getResumableTuples

          public java.util.Set<Tuple> getResumableTuples()

      Description copied from interface: `UnmaskedResumable`
      Returns the set of tuples for which lazy folding shall be resumed at the next timestamp.
      Specified by:
        `getResumableTuples` in interface `UnmaskedResumable<Timestamp extends java.lang.Comparable<Timestamp>>`

    - #### getResumableTimestamp

          public Timestamp getResumableTimestamp()

      Description copied from interface: `Resumable`
      Returns the smallest timestamp where lazy folding shall be resumed, or null if there is no more folding to do in this resumable.
      Specified by:
        `getResumableTimestamp` in interface `Resumable<Timestamp extends java.lang.Comparable<Timestamp>>`

    - #### addFoldingState

          protected void addFoldingState(Tuple tuple,
                                         TimelyMemory.FoldingState state,
                                         Timestamp timestamp)

      Registers the given folding state for the specified timestamp and tuple. If there is already a state stored, the two states will be merged together.

    - #### resumeAt

          public java.util.Map<Tuple,Diff<Timestamp>> resumeAt(Timestamp timestamp)

      Description copied from interface: `UnmaskedResumable`
      When called, the folding of the state shall be resumed at the given timestamp. The resumable is expected to do a folding step at the given timestamp only. Afterwards, folding shall be interrupted, even if there is more folding to do towards higher timestamps.
      Specified by:
        `resumeAt` in interface `UnmaskedResumable<Timestamp extends java.lang.Comparable<Timestamp>>`

    - #### doFoldingStep

          protected Diff<Timestamp> doFoldingStep(Tuple tuple,
                                                  TimelyMemory.FoldingState state,
                                                  Timestamp timestamp)

    - #### getCounter

          protected TimelyMemory.CumulativeCounter getCounter(Tuple tuple,
                                                              Timestamp timestamp)

      On-demand initializes and returns the counter for the given tuple and timestamp.

    - #### gcCounters

          protected void gcCounters(TimelyMemory.CumulativeCounter counter,
                                    Tuple tuple,
                                    Timestamp timestamp)

      Garbage collects the counter of the given tuple and timestamp if the new diff is zero.

    - #### computeDiffsLazy

          protected void computeDiffsLazy(Direction direction,
                                          int oldCumulative,
                                          int newCumulative,
                                          Timestamp timestamp,
                                          Timestamp nextTimestamp,
                                          Diff<Timestamp> diffs)

      Utility method that computes the timeline diffs in case of lazy memories. The diffs will be inserted into the input parameter. This method computes diffs for entire plateaus that spans from timestamp to nextTimestamp. Compared to the eager version of this method, the lazy version makes use of both the old and the new cumulative values because it can happen that the cumulative is incremented by a value that is larger than 1 (as folding states are merged together). This means that we cant decide whether the cumulative became positive by comparing the new value to 1.

    - #### computeDiffsEager

          protected TimelyMemory.SignChange computeDiffsEager(Direction direction,
                                                              TimelyMemory.CumulativeCounter counter,
                                                              TimelyMemory.SignChange signChangeAtPrevious,
                                                              Timestamp timestamp,
                                                              Diff<Timestamp> diffs)

      Utility method that computes the timeline diffs in case of eager memories. The diffs will be inserted into the input parameter. This method computes diffs that describe momentary changes instead of plateaus. Returns a `TimelyMemory.SignChange` that describes how the sign has changed at the given timestamp.

    - #### put

          public Diff<Timestamp> put(Tuple tuple,
                                     Timestamp timestamp)

    - #### remove

          public Diff<Timestamp> remove(Tuple tuple,
                                        Timestamp timestamp)

    - #### putEager

          protected Diff<Timestamp> putEager(Tuple tuple,
                                             Timestamp timestamp)

    - #### putLazy

          protected Diff<Timestamp> putLazy(Tuple tuple,
                                            Timestamp timestamp)

    - #### removeEager

          protected Diff<Timestamp> removeEager(Tuple tuple,
                                                Timestamp timestamp)

    - #### removeLazy

          protected Diff<Timestamp> removeLazy(Tuple tuple,
                                               Timestamp timestamp)

    - #### updateTimeline

          protected void updateTimeline(Tuple tuple,
                                        Diff<Timestamp> diff)

      Updates and garbage collects the timeline of the given tuple based on the given timeline diff.

    - #### getTuplesAtInfinity

          public java.util.Collection<Tuple> getTuplesAtInfinity()

    - #### getCountAtInfinity

          public int getCountAtInfinity()

      Returns the number of tuples that are present at the moment 'infinity'.

    - #### isPresentAtInfinity

          public boolean isPresentAtInfinity(Tuple tuple)

      Returns true if the given tuple is present at the moment 'infinity'.

    - #### isEmpty

          public boolean isEmpty()

    - #### size

          public int size()

    - #### keySet

          public java.util.Set<Tuple> keySet()

    - #### asMap

          public java.util.Map<Tuple,Timeline<Timestamp>> asMap()

    - #### get

          public Timeline<Timestamp> get(ITuple tuple)

    - #### clear

          public void clear()

      Description copied from interface: `Clearable`
      Clear all partial matchings stored in memory
      Specified by:
        `clear` in interface `Clearable`

    - #### containsKey

          public boolean containsKey(ITuple tuple)

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`