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

## Class Network

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

-     public class Network
      extends java.lang.Object

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.util.ArrayList<ReteContainer>` | `containers`
    `protected java.util.Map<ReteContainer,java.lang.Long>` | `globalTerminationCriteria`
    `protected InputConnector` | `inputConnector`
    `protected org.eclipse.viatra.query.runtime.rete.network.NodeFactory` | `nodeFactory`
    `protected java.util.Map<ReteContainer,java.lang.Long>` | `reportedClocks`
    `protected java.util.concurrent.locks.Lock` | `structuralChangeLock`
    `protected java.util.concurrent.locks.Lock` | `updateLock`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Network(int threads, ReteEngine engine)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `connectRemoteNodes(Address<? extends Supplier> supplier, Address<? extends Receiver> receiver, boolean synchronise)` Establishes connection between a supplier and a receiver node, regardless which container they are in.
    `void` | `disconnectRemoteNodes(Address<? extends Supplier> supplier, Address<? extends Receiver> receiver, boolean desynchronise)` Severs connection between a supplier and a receiver node, regardless which container they are in.
    `java.util.List<ReteContainer>` | `getContainers()`
    `ReteEngine` | `getEngine()`
    `Address<? extends Node>` | `getExistingNodeByRecipe(ReteNodeRecipe recipe)`
    `ReteContainer` | `getHeadContainer()` Returns the head container, that is guaranteed to reside in the same JVM as the Network object.
    `InputConnector` | `getInputConnector()`
    `ReteContainer` | `getNextContainer()` Returns the next container in round-robin fashion.
    `Address<? extends Node>` | `getNodeByRecipeIfExists(ReteNodeRecipe recipe)`
    `org.eclipse.viatra.query.runtime.rete.network.NodeFactory` | `getNodeFactory()`
    `java.util.Set<RecipeTraceInfo>` | `getRecipeTraces()`
    `java.util.concurrent.locks.Lock` | `getStructuralChangeLock()`
    `void` | `kill()` Kills this Network along with all containers and message consumption cycles.
    `void` | `sendConstructionUpdate(Address<? extends Receiver> receiver, Direction direction, Tuple updateElement)` Sends an update message to the receiver node, indicating a newly found or lost partial matching.
    `void` | `sendConstructionUpdates(Address<? extends Receiver> receiver, Direction direction, java.util.Collection<Tuple> updateElements)` Sends multiple update messages atomically to the receiver node, indicating a newly found or lost partial matching.
    `void` | `sendExternalUpdate(Address<? extends Receiver> receiver, Direction direction, Tuple updateElement)` Sends an update message to the receiver node, indicating a newly found or lost partial matching.
    `void` | `waitForReteTermination()` Waits until all rete update operations are settled in all containers.
    `void` | `waitForReteTermination(java.lang.Runnable action)` Waits to execute action until all rete update operations are settled in all containers.

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

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

- - ### Field Detail

    - #### containers

          protected java.util.ArrayList<ReteContainer> containers

    - #### globalTerminationCriteria

          protected java.util.Map<ReteContainer,java.lang.Long> globalTerminationCriteria

    - #### reportedClocks

          protected java.util.Map<ReteContainer,java.lang.Long> reportedClocks

    - #### updateLock

          protected java.util.concurrent.locks.Lock updateLock

    - #### structuralChangeLock

          protected java.util.concurrent.locks.Lock structuralChangeLock

    - #### nodeFactory

          protected org.eclipse.viatra.query.runtime.rete.network.NodeFactory nodeFactory

    - #### inputConnector

          protected InputConnector inputConnector

  - ### Constructor Detail

    - #### Network

          public Network(int threads,
                         ReteEngine engine)

      Parameters:
        `threads` - the number of threads to operate the network with; 0 means single-threaded operation, 1 starts an asynchronous thread to operate the RETE net, >1 uses multiple RETE containers.

  - ### Method Detail

    - #### getExistingNodeByRecipe

          public Address<? extends Node> getExistingNodeByRecipe(ReteNodeRecipe recipe)

      Throws:
        `java.lang.IllegalStateException` - if no node has been constructed for the recipe

    - #### getNodeByRecipeIfExists

          public Address<? extends Node> getNodeByRecipeIfExists(ReteNodeRecipe recipe)

      Returns:
        null if no node has been constructed for the recipe

    - #### kill

          public void kill()

      Kills this Network along with all containers and message consumption cycles.

    - #### getHeadContainer

          public ReteContainer getHeadContainer()

      Returns the head container, that is guaranteed to reside in the same JVM as the Network object.

    - #### getNextContainer

          public ReteContainer getNextContainer()

      Returns the next container in round-robin fashion. Configurable not to yield head container.

    - #### sendExternalUpdate

          public void sendExternalUpdate(Address<? extends Receiver> receiver,
                                         Direction direction,
                                         Tuple updateElement)

      Sends an update message to the receiver node, indicating a newly found or lost partial matching. The node may reside in any of the containers associated with this network. To be called from a user thread during normal operation, NOT during construction.
      Since:
        2.4

    - #### sendConstructionUpdate

          public void sendConstructionUpdate(Address<? extends Receiver> receiver,
                                             Direction direction,
                                             Tuple updateElement)

      Sends an update message to the receiver node, indicating a newly found or lost partial matching. The node may reside in any of the containers associated with this network. To be called from a user thread during construction.
      Since:
        2.4

    - #### sendConstructionUpdates

          public void sendConstructionUpdates(Address<? extends Receiver> receiver,
                                              Direction direction,
                                              java.util.Collection<Tuple> updateElements)

      Sends multiple update messages atomically to the receiver node, indicating a newly found or lost partial matching. The node may reside in any of the containers associated with this network. To be called from a user thread during construction.
      Since:
        2.4

    - #### connectRemoteNodes

          public void connectRemoteNodes(Address<? extends Supplier> supplier,
                                         Address<? extends Receiver> receiver,
                                         boolean synchronise)

      Establishes connection between a supplier and a receiver node, regardless which container they are in. Not to be called remotely, because this method enforces the structural lock.
      Parameters:
        `supplier` -
        `receiver` -
        `synchronise` - indicates whether the receiver should be synchronised to the current contents of the supplier

    - #### disconnectRemoteNodes

          public void disconnectRemoteNodes(Address<? extends Supplier> supplier,
                                            Address<? extends Receiver> receiver,
                                            boolean desynchronise)

      Severs connection between a supplier and a receiver node, regardless which container they are in. Not to be called remotely, because this method enforces the structural lock.
      Parameters:
        `supplier` -
        `receiver` -
        `desynchronise` - indicates whether the current contents of the supplier should be subtracted from the receiver

    - #### waitForReteTermination

          public void waitForReteTermination()

      Waits until all rete update operations are settled in all containers. Returns immediately, if no updates are pending. To be called from any user thread.

    - #### waitForReteTermination

          public void waitForReteTermination(java.lang.Runnable action)

      Waits to execute action until all rete update operations are settled in all containers. Runs action and returns immediately, if no updates are pending. The given action is guaranteed to be run when the terminated state still persists.
      Parameters:
        `action` - the action to be run when reaching the steady-state. To be called from any user thread.

    - #### getRecipeTraces

          public java.util.Set<RecipeTraceInfo> getRecipeTraces()

      Returns:
        an unmodifiable set of known recipe traces

    - #### getContainers

          public java.util.List<ReteContainer> getContainers()

      Returns:
        an unmodifiable list of containers

    - #### getStructuralChangeLock

          public java.util.concurrent.locks.Lock getStructuralChangeLock()

    - #### getNodeFactory

          public org.eclipse.viatra.query.runtime.rete.network.NodeFactory getNodeFactory()

    - #### getInputConnector

          public InputConnector getInputConnector()

    - #### getEngine

          public ReteEngine getEngine()