Add global_discovery_strategy.puml and a description of the global di…

…scovery to udf_discovery_and_communication.rst

doc/design/global_discovery/global_cluster_formation.puml

@@ -3,60 +3,60 @@
 
 !include ../legend.puml
 
-box Node1
+box Peer1
     participant "DiscoveryStrategy" as DiscoveryStrategy
-    participant "PeerCommunicator\n(Formation Leader)" as Peer1
+    participant "PeerCommunicator\n(Formation Leader)" as PeerCommunicator1
 end box
 
-box Node2
-    participant "PeerCommunicator" as Peer2
+box Peer2
+    participant "PeerCommunicator" as PeerCommunicator2
 end box
 
-box Node3
-    participant "PeerCommunicator" as Peer3
+box Peer3
+    participant "PeerCommunicator" as PeerCommunicator3
 end box
 
-box Node4
-    participant "PeerCommunicator" as Peer4
+box Peer4
+    participant "PeerCommunicator" as PeerCommunicator4
 end box
 
-DiscoveryStrategy -> Peer1: RegisterPeerMessage(Peer2)
+DiscoveryStrategy -> PeerCommunicator1: RegisterPeerMessage(Peer2)
 par
-    ref over Peer1, Peer2: Establish Connection\nbetween Peer1 and Peer2
+    ref over PeerCommunicator1, PeerCommunicator2: Establish Connection\nbetween Peer1 and Peer2
 else
-    DiscoveryStrategy -> Peer1: RegisterPeerMessage(Peer3)
+    DiscoveryStrategy -> PeerCommunicator1: RegisterPeerMessage(Peer3)
     par
         par
-            Peer1 -> Peer2: RegisterPeerMessage(Peer3)
+            PeerCommunicator1 -> PeerCommunicator2: RegisterPeerMessage(Peer3)
             par
-                Peer1 <- Peer2: AcknowledgeRegisterPeerMessage(Peer3)
-                Peer1 -> Peer2: RegisterPeerCompleteMessage(Peer3)
+                PeerCommunicator1 <- PeerCommunicator2: AcknowledgeRegisterPeerMessage(Peer3)
+                PeerCommunicator1 -> PeerCommunicator2: RegisterPeerCompleteMessage(Peer3)
             else
-                ref over Peer2, Peer3: Establish Connection\nbetween Peer2 and Peer3
+                ref over PeerCommunicator2, PeerCommunicator3: Establish Connection\nbetween Peer2 and Peer3
             end
         else
-            ref over Peer1, Peer3: Establish Connection\nbetween Peer1 and Peer3
+            ref over PeerCommunicator1, PeerCommunicator3: Establish Connection\nbetween Peer1 and Peer3
         end
     else
-        DiscoveryStrategy -> Peer1: RegisterPeerMessage(Peer4)
+        DiscoveryStrategy -> PeerCommunicator1: RegisterPeerMessage(Peer4)
         par
-            Peer1 -> Peer2: RegisterPeerMessage(Peer4)
+            PeerCommunicator1 -> PeerCommunicator2: RegisterPeerMessage(Peer4)
             par
-                Peer2 -> Peer3: RegisterPeerMessage(Peer4)
+                PeerCommunicator2 -> PeerCommunicator3: RegisterPeerMessage(Peer4)
                 par
-                    Peer2 <- Peer3: AcknowledgeRegisterPeerMessage(Peer4)
-                    Peer2 -> Peer3: RegisterPeerCompleteMessage(Peer4)
+                    PeerCommunicator2 <- PeerCommunicator3: AcknowledgeRegisterPeerMessage(Peer4)
+                    PeerCommunicator2 -> PeerCommunicator3: RegisterPeerCompleteMessage(Peer4)
                 else
-                    ref over Peer3, Peer4: Establish Connection\nbetween Peer3 and Peer4
+                    ref over PeerCommunicator3, PeerCommunicator4: Establish Connection\nbetween Peer3 and Peer4
                 end
             else
-                Peer1 <- Peer2: AcknowledgeRegisterPeerMessage(Peer4)
-                Peer1 -> Peer2: RegisterPeerCompleteMessage(Peer4)
+                PeerCommunicator1 <- PeerCommunicator2: AcknowledgeRegisterPeerMessage(Peer4)
+                PeerCommunicator1 -> PeerCommunicator2: RegisterPeerCompleteMessage(Peer4)
             else
-                ref over Peer2, Peer4: Establish Connection\nbetween Peer2 and Peer4
+                ref over PeerCommunicator2, PeerCommunicator4: Establish Connection\nbetween Peer2 and Peer4
             end
         else
-            ref over Peer1, Peer4: Establish Connection\nbetween Peer1 and Peer4
+            ref over PeerCommunicator1, PeerCommunicator4: Establish Connection\nbetween Peer1 and Peer4
         end
     end
 end

doc/design/global_discovery/global_discovery_strategy.puml

@@ -0,0 +1,47 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+
+!include ../legend.puml
+
+box Peer1
+    participant "DiscoveryStrategy" as DiscoveryStrategy1
+    participant "PeerCommunicator\n(Formation Leader)" as PeerCommunicator1
+end box
+
+box Peer2
+    participant "DiscoveryStrategy" as DiscoveryStrategy2
+    participant "PeerCommunicator" as PeerCommunicator2
+end box
+
+box Peer3
+    participant "DiscoveryStrategy" as DiscoveryStrategy3
+    participant "PeerCommunicator" as PeerCommunicator3
+end box
+
+box Peer4
+    participant "DiscoveryStrategy" as DiscoveryStrategy4
+    participant "PeerCommunicator" as PeerCommunicator4
+end box
+par
+    loop all_peers_are_connected
+        DiscoveryStrategy1 <- DiscoveryStrategy2: PingMessage
+        DiscoveryStrategy1 -> PeerCommunicator1: register_peer(Peer2)
+        ref over PeerCommunicator1, PeerCommunicator4: Global Cluster Formation
+        DiscoveryStrategy2 -> PeerCommunicator2: are_all_peers_connected()
+    end
+else
+    loop all_peers_are_connected
+        DiscoveryStrategy1 <- DiscoveryStrategy3: PingMessage
+        DiscoveryStrategy1 -> PeerCommunicator1: register_peer(Peer3)
+        ref over PeerCommunicator1, PeerCommunicator4: Global Cluster Formation
+        DiscoveryStrategy3 -> PeerCommunicator3: are_all_peers_connected()
+    end
+else
+    loop all_peers_are_connected
+        DiscoveryStrategy1 <- DiscoveryStrategy4: PingMessage
+        DiscoveryStrategy1 -> PeerCommunicator1: register_peer(Peer4)
+        ref over PeerCommunicator1, PeerCommunicator4: Global Cluster Formation
+        DiscoveryStrategy4 -> PeerCommunicator4: are_all_peers_connected()
+    end
+end
+@enduml

doc/design/udf_discovery_and_communication.rst

@@ -49,11 +49,39 @@ Local Discovery Strategy
   it registers the other peer and treis to establish a connection
 - The strategy sends and receives UDP Broadcast messages until all other peers are connected
 
-* Both peers receive `PingMessage`:
+- Both peers receive `PingMessage`:
 
-.. image:: establish_connection/both_peer_receive_ping.png
+.. image:: local_discovery_strategy/both_peer_receive_ping.png
 
-* One peer receive `PingMessage`:
+- One peer receive `PingMessage`:
 
-.. image:: establish_connection/one_peer_receives_ping.png
+.. image:: local_discovery_strategy/one_peer_receives_ping.png
 
+=========================
+Global Discovery Strategy
+=========================
+
+The Global Discovery Strategy is more complex, because we can't use UDP Broadcast between nodes. Cloud provider and
+other data centers often block UDP Broadcast between different servers. For that reason, we choose a different
+mechanism. Before, we start the UDFs we choose one data node by random to be the global cluster formation leader.
+Further, we choose a random port on which the local leader on the designated node will listen for `PingMessge`'s
+from the other data nodes.
+We need first the local discovery and cluster formation to reduce the number of Peer's for the global cluster discovery,
+because otherwise too many Peer's would try to connect designated node. Furthermore, we wouldn't know which UDF instance
+should listen for the `PingMessage`'s on the designated node.
+
+.. image:: global_discovery/global_discovery_strategy.png
+
+
+========================
+Global Cluster Formation
+========================
+
+After, the Global Cluster Formation Leader received a `PingMessage` of a Peer it needs to forward this information
+to all other Peer's. The simplest but most inefficient way to do it, is when the Leader waits for the PingMessage
+of each Peer and sends the list of all the other Peer's to each Peer. This causes higher load on the Leader and
+all other Peer's are more or less idling.
+For that reason, we chose a more distributed algorithm where the Peer's form a chain with the Leader in the beginning.
+Each Peer forwards the received `RegisterPeerMessage`'s to the next Peer in the chain.
+
+.. image:: global_discovery/global_cluster_formation.png