Package org.eclipse.viatra.query.runtime.rete.network.communication

## Class CommunicationTracker

- java.lang.Object
- - org.eclipse.viatra.query.runtime.rete.network.communication.CommunicationTracker

-     public abstract class CommunicationTracker
      extends java.lang.Object

  An instance of this class is associated with every `ReteContainer`. The tracker serves two purposes:
  (1) It allows RETE nodes to register their communication dependencies on-the-fly. These dependencies can be registered or unregistered when nodes are disposed of.
  (2) It allows RETE nodes to register their mailboxes as dirty, that is, they can tell the tracker that they have something to send to other nodes in the network. The tracker is then responsible for ordering these messages (more precisely, the mailboxes that contain the messages) for the associated `ReteContainer`. The ordering is governed by the strongly connected components in the dependency network and follows a topological sorting scheme; those mailboxes will be emptied first whose owner nodes do not depend on other undelivered messages.
  Since:
    1.6

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected Graph<Node>` | `dependencyGraph` | The dependency graph of the communications in the RETE network
    `protected java.util.Map<Node,​CommunicationGroup>` | `groupMap` | Precomputed node -> communication group map
    `protected java.util.Queue<CommunicationGroup>` | `groupQueue` | Priority queue of active communication groups
    `protected int` | `maxGroupId` | The maximum group id assigned so far
    `protected int` | `minGroupId` | The minimum group id assigned so far
    `protected IncSCCAlg<Node>` | `sccInformationProvider` | Incremental SCC information about the dependency graph

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `CommunicationTracker()` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `activateUnenqueued​(CommunicationGroup group)` |
    `boolean` | `areInSameGroup​(Node left, Node right)` | Returns true if the given two `Node`s are in the same `CommunicationGroup`.
    `protected CommunicationGroup` | `createAndStoreGroup​(Node representative, int index)` |
    `protected abstract CommunicationGroup` | `createGroup​(Node representative, int index)` |
    `void` | `deactivate​(CommunicationGroup group)` |
    `CommunicationGroup` | `getAndRemoveFirstGroup()` |
    `Graph<Node>` | `getDependencyGraph()` |
    `CommunicationGroup` | `getGroup​(Node node)` |
    `boolean` | `isEmpty()` |
    `boolean` | `isInRecursiveGroup​(Node node)` | Returns true if the given `Node` is in a recursive `CommunicationGroup`, false otherwise.
    `protected boolean` | `isRecursionCutPoint​(Node source, Node target)` | Returns true if the given source-target edge in the communication network acts as a recursion cut point.
    `protected abstract void` | `postProcessGroup​(CommunicationGroup group)` | This hook allows concrete tracker implementations to perform tracker-specific post processing on groups.
    `protected abstract void` | `postProcessNode​(Node node)` | This hook allows concrete tracker implementations to perform tracker-specific post processing on nodes (cf.
    `abstract IndexerListener` | `proxifyIndexerListener​(Node requester, IndexerListener original)` | Creates a proxy for the given `IndexerListener` for the given requester `Node`.
    `abstract Mailbox` | `proxifyMailbox​(Node requester, Mailbox original)` | Creates a proxy for the given `Mailbox` for the given requester `Node`.
    `protected abstract void` | `reconstructQueueContents​(java.util.Set<CommunicationGroup> oldActiveGroups)` | This method is responsible for reconstructing the active queue contents after the network structure has changed.
    `void` | `registerDependency​(Node source, Node target)` | Registers the dependency that the target `Node` depends on the source `Node`.
    `void` | `unregisterDependency​(Node source, Node target)` | Unregisters a dependency between source and target.

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

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

- - ### Field Detail

    - #### minGroupId

          protected int minGroupId

      The minimum group id assigned so far

    - #### maxGroupId

          protected int maxGroupId

      The maximum group id assigned so far

    - #### dependencyGraph

          protected final Graph<Node> dependencyGraph

      The dependency graph of the communications in the RETE network

    - #### sccInformationProvider

          protected final IncSCCAlg<Node> sccInformationProvider

      Incremental SCC information about the dependency graph

    - #### groupMap

          protected final java.util.Map<Node,​CommunicationGroup> groupMap

      Precomputed node -> communication group map

    - #### groupQueue

          protected final java.util.Queue<CommunicationGroup> groupQueue

      Priority queue of active communication groups

  - ### Constructor Detail

    - #### CommunicationTracker

          public CommunicationTracker()

  - ### Method Detail

    - #### getDependencyGraph

          public Graph<Node> getDependencyGraph()

    - #### getGroup

          public CommunicationGroup getGroup​(Node node)

    - #### reconstructQueueContents

          protected abstract void reconstructQueueContents​(java.util.Set<CommunicationGroup> oldActiveGroups)

      This method is responsible for reconstructing the active queue contents after the network structure has changed. It it defined as abstract because the reconstruction logic is specific to each `CommunicationTracker`.
      Since:
        2.4

    - #### activateUnenqueued

          public void activateUnenqueued​(CommunicationGroup group)

    - #### deactivate

          public void deactivate​(CommunicationGroup group)

    - #### getAndRemoveFirstGroup

          public CommunicationGroup getAndRemoveFirstGroup()

    - #### isEmpty

          public boolean isEmpty()

    - #### createGroup

          protected abstract CommunicationGroup createGroup​(Node representative,
                                                            int index)

    - #### createAndStoreGroup

          protected CommunicationGroup createAndStoreGroup​(Node representative,
                                                           int index)

    - #### registerDependency

          public void registerDependency​(Node source,
                                         Node target)

      Registers the dependency that the target `Node` depends on the source `Node`. In other words, source may send messages to target in the RETE network. If the dependency edge is already present, this method call is a noop.
      Parameters:
        `source` - the source node
        `target` - the target node

    - #### isInRecursiveGroup

          public boolean isInRecursiveGroup​(Node node)

      Returns true if the given `Node` is in a recursive `CommunicationGroup`, false otherwise.

    - #### areInSameGroup

          public boolean areInSameGroup​(Node left,
                                        Node right)

      Returns true if the given two `Node`s are in the same `CommunicationGroup`.

    - #### unregisterDependency

          public void unregisterDependency​(Node source,
                                           Node target)

      Unregisters a dependency between source and target.
      Parameters:
        `source` - the source node
        `target` - the target node

    - #### isRecursionCutPoint

          protected boolean isRecursionCutPoint​(Node source,
                                                Node target)

      Returns true if the given source-target edge in the communication network acts as a recursion cut point. The current implementation considers edges leading into `ProductionNode`s as cut point iff both source and target belong to the same group.
      Parameters:
        `source` - the source node
        `target` - the target node
      Returns:
        true if the edge is a cut point, false otherwise
      Since:
        2.4

    - #### postProcessNode

          protected abstract void postProcessNode​(Node node)

      This hook allows concrete tracker implementations to perform tracker-specific post processing on nodes (cf. `NetworkStructureChangeSensitiveNode` and `BehaviorChangingMailbox`). At the time of the invocation, the network topology has already been updated.

    - #### postProcessGroup

          protected abstract void postProcessGroup​(CommunicationGroup group)

      This hook allows concrete tracker implementations to perform tracker-specific post processing on groups. At the time of the invocation, the network topology has already been updated.
      Since:
        2.4

    - #### proxifyMailbox

          public abstract Mailbox proxifyMailbox​(Node requester,
                                                 Mailbox original)

      Creates a proxy for the given `Mailbox` for the given requester `Node`. The proxy creation is `CommunicationTracker`-specific and depends on the identity of the requester. This method is primarily used to create `TimelyMailboxProxy`s depending on the network topology. There is no guarantee that the same proxy instance is returned when this method is called multiple times with the same arguments.

    - #### proxifyIndexerListener

          public abstract IndexerListener proxifyIndexerListener​(Node requester,
                                                                 IndexerListener original)

      Creates a proxy for the given `IndexerListener` for the given requester `Node`. The proxy creation is `CommunicationTracker`-specific and depends on the identity of the requester. This method is primarily used to create `TimelyIndexerListenerProxy`s depending on the network topology. There is no guarantee that the same proxy instance is returned when this method is called multiple times with the same arguments.