svn commit: r1716480 - /sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext

[st...@apache.org]

Author: stefanegli
Date: Wed Nov 25 16:43:10 2015
New Revision: 1716480

URL: http://svn.apache.org/viewvc?rev=1716480&view=rev
Log:
SLING-5021 :  Description of the Voting process added

Modified:
    sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext

Modified: sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext?rev=1716480&r1=1716479&r2=1716480&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext Wed Nov 25 16:43:10 2015
@@ -142,6 +142,28 @@ Administrative note: All the information
 
 	/var/discovery/impl
 
+### Heartbeats, Voting and Intra-Cluster Discovery
+
+`discovery.impl` uses the fact that all instance of a cluster are connected to the same repository as the
+basis for discovering those instances. It does so by using a heartbeat and voting mechanism:
+
+* each instance periodically stores a 'heartbeat' into the repository in a well-known location.
+This is done by setting a corresponding `lastHeartbeat` property to the current timestamp
+* a 'heartbeat' that has not yet timed out is considered a signal that the instance is alive
+* as soon as a 'heartbeat' is timed out, the assumption is that the corresponding instance is dead/shutdown
+
+To avoid having each instance make it's own, perhaps differing conclusions as to which instance/heartbeat is dead or not,
+there is an explicit, unanimous voting mechanism that agrees upon a list of alive instances. This list of alive
+instances is called cluster view.  
+* as soon as any instance notices a change in the list of active instances, it is free to calculate a new
+such list and start a voting in the cluster - each voting carries a unique votingId
+* since any instance can do this, you can have concurrent creation of new votings
+* each instance has one 'yes' vote - and if there are multiple concurrent votings the lowest one wins
+* when a voting receives a 'yes' from all instances that it enlists it is considered as 'winning'
+and is promoted to be the new, valid view from now on.
+* a promoted view is stored in `/var/discovery/impl/establishedView` and any change therein is
+passed on in a TopologyEvent to all registered listeners.
+
 ### Topology Connectors for Cross-Cluster Discovery
 
 From a discovery API's point of view a cluster consists of all instances that are connected to the same repository.