Package tools.refinery.interpreter.matchers.memories

Class MaskedTupleMemory<Timestamp extends Comparable<Timestamp>>

java.lang.Object
tools.refinery.interpreter.matchers.memories.MaskedTupleMemory<Timestamp>
All Implemented Interfaces:
Clearable, MaskedResumable<Timestamp>, Resumable<Timestamp>
Direct Known Subclasses:
DefaultMaskedTupleMemory, IdentityMaskedTupleMemory, NullaryMaskedTupleMemory, TimelyDefaultMaskedTupleMemory, TimelyIdentityMaskedTupleMemory, TimelyNullaryMaskedTupleMemory, TimelyUnaryMaskedTupleMemory, UnaryMaskedTupleMemory
public abstract class MaskedTupleMemory<Timestamp extends Comparable<Timestamp>> extends 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 Timelines with the stored tuples.

Since:
2.0

  • Field Details

    • mask

      protected final TupleMask mask
      The mask by which the tuples are indexed.

    • owner

      protected final Object owner
      The object "owning" this memory. May be null.
      Since:
      1.7

  • Constructor Details

    • MaskedTupleMemory

      protected MaskedTupleMemory(TupleMask mask, Object owner)

  • Method Details

    • create

      public static <T extends Comparable<T>> MaskedTupleMemory<T> create(TupleMask mask, CollectionsFactory.MemoryType bucketType, Object owner)
      Creates a new memory for the given owner that indexes tuples according to the given mask.

    • create

      public static <T extends Comparable<T>> MaskedTupleMemory<T> create(TupleMask mask, CollectionsFactory.MemoryType bucketType, 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 Comparable<T>> MaskedTupleMemory<T> create(TupleMask mask, CollectionsFactory.MemoryType bucketType, 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 Map<Tuple,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 Comparable<Timestamp>>

    • getResumableSignatures

      public 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 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 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 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 Iterator<Tuple> iterator()
      Iterates over distinct tuples stored in the memory, regardless of their signatures.

    • getSignatures

      public abstract 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 Collection<Tuple> get(ITuple signature)
      Retrieves tuples that have the specified signature
      Returns:
      collection of tuples found, null if none

    • getWithTimeline

      public abstract 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 Collection<Tuple> getOrEmpty(ITuple signature)
      Retrieves tuples that have the specified signature.
      Returns:
      collection of tuples found, never null
      Since:
      2.1

    • getOrEmptyWithTimeline

      public 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 IllegalStateException raiseDuplicateInsertion(Tuple tuple)

    • raiseDuplicateDeletion

      protected IllegalStateException raiseDuplicateDeletion(Tuple tuple)

    • toString

      public String toString()
      Overrides:
      toString in class Object