org.eclipse.viatra.query.runtime.matchers.memories

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

- java.lang.Object
- - org.eclipse.viatra.query.runtime.matchers.memories.MaskedTupleMemory<Timestamp>

- All Implemented Interfaces:
    Clearable, MaskedResumable<Timestamp>, Resumable<Timestamp>
  Direct Known Subclasses:
    DefaultMaskedTupleMemory, IdentityMaskedTupleMemory, NullaryMaskedTupleMemory, UnaryMaskedTupleMemory

      public abstract class MaskedTupleMemory<Timestamp extends java.lang.Comparable<Timestamp>>
      extends java.lang.Object
      implements Clearable, MaskedResumable<Timestamp>

  Indexes a collection of tuples by their signature (i.e. footprint, projection) obtained according to a mask. May belong to an "owner" (for documentation / traceability purposes).

  There are timeless and timely versions of the different memories. Timely versions associate `Timeline`s with the stored tuples.

  Since:
    2.0
  No Extend:
    This class is not intended to be subclassed by clients.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected TupleMask` | `mask` The mask by which the tuples are indexed.
    `protected java.lang.Object` | `owner` The object "owning" this memory.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `MaskedTupleMemory(TupleMask mask, java.lang.Object owner)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `add(Tuple tuple)` Adds a tuple occurrence to the memory.
    `boolean` | `add(Tuple tuple, Tuple signature)` Adds a tuple occurrence to the memory with the given signature.
    `Diff<Timestamp>` | `addWithTimestamp(Tuple tuple, Timestamp timestamp)` Adds a tuple occurrence to the memory with the given timestamp.
    `Diff<Timestamp>` | `addWithTimestamp(Tuple tuple, Tuple signature, Timestamp timestamp)` Adds a tuple occurrence to the memory with the given signature and timestamp.
    `static <T extends java.lang.Comparable<T>> MaskedTupleMemory<T>` | `create(TupleMask mask, CollectionsFactory.MemoryType bucketType, java.lang.Object owner)` Creates a new memory for the given owner that indexes tuples according to the given mask.
    `static <T extends java.lang.Comparable<T>> MaskedTupleMemory<T>` | `create(TupleMask mask, CollectionsFactory.MemoryType bucketType, java.lang.Object owner, boolean isTimely)` Creates a new memory for the given owner that indexes tuples according to the given mask.
    `static <T extends java.lang.Comparable<T>> MaskedTupleMemory<T>` | `create(TupleMask mask, CollectionsFactory.MemoryType bucketType, java.lang.Object owner, boolean isTimely, boolean isLazy)` Creates a new memory for the given owner that indexes tuples according to the given mask.
    `abstract java.util.Collection<Tuple>` | `get(ITuple signature)` Retrieves tuples that have the specified signature
    `abstract int` | `getKeysetSize()`
    `TupleMask` | `getMask()` The mask according to which tuples are projected and indexed.
    `java.util.Collection<Tuple>` | `getOrEmpty(ITuple signature)` Retrieves tuples that have the specified signature.
    `java.util.Map<Tuple,Timeline<Timestamp>>` | `getOrEmptyWithTimeline(ITuple signature)` Retrieves tuples with their associated timelines that have the specified signature.
    `java.lang.Object` | `getOwner()` The node owning this memory.
    `java.lang.Iterable<Tuple>` | `getResumableSignatures()` Returns the set of signatures for which lazy folding shall be resumed at the next 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.
    `abstract java.lang.Iterable<Tuple>` | `getSignatures()` Retrieves a read-only view of exactly those signatures for which at least one tuple is stored
    `abstract int` | `getTotalSize()`
    `abstract java.util.Map<Tuple,Timeline<Timestamp>>` | `getWithTimeline(ITuple signature)` Retrieves the tuples and their associated timelines that have the specified signature.
    `void` | `initializeWith(MaskedTupleMemory<Timestamp> other, Timestamp defaultValue)` Initializes the contents of this memory based on the contents of another memory.
    `boolean` | `isPresentAtInfinity(ITuple signature)` Returns true if there is any tuple with the given signature that is present at the timestamp +inf, false otherwise.
    `boolean` | `isTimely()` Returns true of this memory is timely, false otherwise.
    `abstract java.util.Iterator<Tuple>` | `iterator()` Iterates over distinct tuples stored in the memory, regardless of their signatures.
    `protected java.lang.IllegalStateException` | `raiseDuplicateDeletion(Tuple tuple)`
    `protected java.lang.IllegalStateException` | `raiseDuplicateInsertion(Tuple tuple)`
    `boolean` | `remove(Tuple tuple)` Removes a tuple occurrence from the memory.
    `boolean` | `remove(Tuple tuple, Tuple signature)` Removes a tuple occurrence from the memory with the given signature.
    `Diff<Timestamp>` | `removeWithTimestamp(Tuple tuple, Timestamp timestamp)` Removes a tuple occurrence from the memory with the given timestamp.
    `Diff<Timestamp>` | `removeWithTimestamp(Tuple tuple, Tuple signature, Timestamp timestamp)` Removes a tuple occurrence from the memory with the given signature and timestamp.
    `java.util.Map<Tuple,java.util.Map<Tuple,Diff<Timestamp>>>` | `resumeAt(Timestamp timestamp)` When called, the folding of the state shall be resumed at the given timestamp.
    `java.lang.String` | `toString()`

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

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

    - ### Methods inherited from interface org.eclipse.viatra.query.runtime.matchers.util.Clearable

      `clear`

- - ### Field Detail

    - #### mask

          protected final TupleMask mask

      The mask by which the tuples are indexed.

    - #### owner

          protected final java.lang.Object owner

      The object "owning" this memory. May be null.
      Since:
        1.7

  - ### Constructor Detail

    - #### MaskedTupleMemory

          protected MaskedTupleMemory(TupleMask mask,
                                      java.lang.Object owner)

  - ### Method Detail

    - #### create

          public static <T extends java.lang.Comparable<T>> MaskedTupleMemory<T> create(TupleMask mask,
                                                                                        CollectionsFactory.MemoryType bucketType,
                                                                                        java.lang.Object owner)

      Creates a new memory for the given owner that indexes tuples according to the given mask.

    - #### create

          public static <T extends java.lang.Comparable<T>> MaskedTupleMemory<T> create(TupleMask mask,
                                                                                        CollectionsFactory.MemoryType bucketType,
                                                                                        java.lang.Object owner,
                                                                                        boolean isTimely)

      Creates a new memory for the given owner that indexes tuples according to the given mask. Clients can specify if the created memory should be timely or not.
      Timely means that tuples are associated with a timeline.
      Since:
        2.3

    - #### create

          public static <T extends java.lang.Comparable<T>> MaskedTupleMemory<T> create(TupleMask mask,
                                                                                        CollectionsFactory.MemoryType bucketType,
                                                                                        java.lang.Object owner,
                                                                                        boolean isTimely,
                                                                                        boolean isLazy)

      Creates a new memory for the given owner that indexes tuples according to the given mask. Clients can specify if the created memory should be timely or not. In case of timely memory, clients can also specify if the memory is lazy or not.
      Timely means that tuples are associated with a timeline.
      Lazyness can only be used together with timely memories. It means that the maintenance of the timelines is lazy, that is, the memory only updates its internal data structures at the timestamp affected by an update, and can be instructed later to resume the maintenance at higher timestamps, as well.
      Since:
        2.4

    - #### resumeAt

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

      Description copied from interface: `MaskedResumable`
      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 `MaskedResumable<Timestamp extends java.lang.Comparable<Timestamp>>`

    - #### getResumableSignatures

          public java.lang.Iterable<Tuple> getResumableSignatures()

      Description copied from interface: `MaskedResumable`
      Returns the set of signatures for which lazy folding shall be resumed at the next timestamp.
      Specified by:
        `getResumableSignatures` in interface `MaskedResumable<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>>`

    - #### initializeWith

          public void initializeWith(MaskedTupleMemory<Timestamp> other,
                                     Timestamp defaultValue)

      Initializes the contents of this memory based on the contents of another memory. The default value is associated with each tuple in the timely memories.
      Since:
        2.3

    - #### isPresentAtInfinity

          public boolean isPresentAtInfinity(ITuple signature)

      Returns true if there is any tuple with the given signature that is present at the timestamp +inf, false otherwise.
      Since:
        2.4

    - #### isTimely

          public boolean isTimely()

      Returns true of this memory is timely, false otherwise.
      Since:
        2.3

    - #### getOwner

          public java.lang.Object getOwner()

      The node owning this memory. May be null.
      Since:
        2.0

    - #### getMask

          public TupleMask getMask()

      The mask according to which tuples are projected and indexed.
      Since:
        2.0

    - #### getKeysetSize

          public abstract int getKeysetSize()

      Returns:
        the number of distinct signatures of all stored tuples.

    - #### getTotalSize

          public abstract int getTotalSize()

      Returns:
        the total number of distinct tuples stored. Multiple copies of the same tuple, if allowed, are counted as one.

        This is currently not cached but computed on demand. It is therefore not efficient, and shall only be used for debug / profiling purposes.

    - #### iterator

          public abstract java.util.Iterator<Tuple> iterator()

      Iterates over distinct tuples stored in the memory, regardless of their signatures.

    - #### getSignatures

          public abstract java.lang.Iterable<Tuple> getSignatures()

      Retrieves a read-only view of exactly those signatures for which at least one tuple is stored
      Since:
        2.0

    - #### get

          public abstract java.util.Collection<Tuple> get(ITuple signature)

      Retrieves tuples that have the specified signature
      Returns:
        collection of tuples found, null if none

    - #### getWithTimeline

          public abstract java.util.Map<Tuple,Timeline<Timestamp>> getWithTimeline(ITuple signature)

      Retrieves the tuples and their associated timelines that have the specified signature.
      Returns:
        the mappings from tuples to timelines, null if there is no mapping for the signature
      Since:
        2.4

    - #### getOrEmpty

          public java.util.Collection<Tuple> getOrEmpty(ITuple signature)

      Retrieves tuples that have the specified signature.
      Returns:
        collection of tuples found, never null
      Since:
        2.1

    - #### getOrEmptyWithTimeline

          public java.util.Map<Tuple,Timeline<Timestamp>> getOrEmptyWithTimeline(ITuple signature)

      Retrieves tuples with their associated timelines that have the specified signature.
      Returns:
        map of tuples and timelines found, never null
      Since:
        2.4

    - #### remove

          public boolean remove(Tuple tuple,
                                Tuple signature)

      Removes a tuple occurrence from the memory with the given signature.
      Parameters:
        `tuple` - the tuple to be removed from the memory
        `signature` - precomputed footprint of the tuple according to the mask
      Returns:
        true if this was the the last occurrence of the signature (according to the mask)

    - #### removeWithTimestamp

          public Diff<Timestamp> removeWithTimestamp(Tuple tuple,
                                                     Tuple signature,
                                                     Timestamp timestamp)

      Removes a tuple occurrence from the memory with the given signature and timestamp.
      Parameters:
        `tuple` - the tuple to be removed from the memory
        `signature` - precomputed footprint of the tuple according to the mask
        `timestamp` - the timestamp associated with the tuple
      Returns:
        A `Diff` describing how the timeline of the given tuple changed.
      Since:
        2.4

    - #### remove

          public boolean remove(Tuple tuple)

      Removes a tuple occurrence from the memory.
      Parameters:
        `tuple` - the tuple to be removed from the memory
      Returns:
        true if this was the the last occurrence of the signature (according to the mask)

    - #### removeWithTimestamp

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

      Removes a tuple occurrence from the memory with the given timestamp.
      Parameters:
        `tuple` - the tuple to be removed from the memory
        `timestamp` - the timestamp associated with the tuple
      Returns:
        A `Diff` describing how the timeline of the given tuple changed.
      Since:
        2.4

    - #### add

          public boolean add(Tuple tuple,
                             Tuple signature)

      Adds a tuple occurrence to the memory with the given signature.
      Parameters:
        `tuple` - the tuple to be added to the memory
        `signature` - precomputed footprint of the tuple according to the mask
      Returns:
        true if new signature encountered (according to the mask)

    - #### addWithTimestamp

          public Diff<Timestamp> addWithTimestamp(Tuple tuple,
                                                  Tuple signature,
                                                  Timestamp timestamp)

      Adds a tuple occurrence to the memory with the given signature and timestamp.
      Parameters:
        `tuple` - the tuple to be added to the memory
        `signature` - precomputed footprint of the tuple according to the mask
        `timestamp` - the timestamp associated with the tuple
      Returns:
        A `Diff` describing how the timeline of the given tuple changed.
      Since:
        2.4

    - #### add

          public boolean add(Tuple tuple)

      Adds a tuple occurrence to the memory.
      Parameters:
        `tuple` - the tuple to be added to the memory
      Returns:
        true if new signature encountered (according to the mask)

    - #### addWithTimestamp

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

      Adds a tuple occurrence to the memory with the given timestamp.
      Parameters:
        `tuple` - the tuple to be added to the memory
        `timestamp` - the timestamp associated with the tuple
      Returns:
        A `Diff` describing how the timeline of the given tuple changed.
      Since:
        2.4

    - #### raiseDuplicateInsertion

          protected java.lang.IllegalStateException raiseDuplicateInsertion(Tuple tuple)

    - #### raiseDuplicateDeletion

          protected java.lang.IllegalStateException raiseDuplicateDeletion(Tuple tuple)

    - #### toString

          public java.lang.String toString()

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