BUG-5280: expand design documentation 88/38588/4
authorRobert Varga <rovarga@cisco.com>
Mon, 9 May 2016 09:44:52 +0000 (11:44 +0200)
committerTom Pantelis <tpanteli@brocade.com>
Mon, 20 Mar 2017 10:30:58 +0000 (10:30 +0000)
Add some more documentation on how actors communicate on the backend.

Change-Id: I1d4e39d1cff508ed0ef10901e8a09fd8d89580d1
Signed-off-by: Robert Varga <rovarga@cisco.com>
opendaylight/md-sal/sal-distributed-datastore/src/site/asciidoc/distributed-data-store.adoc

index 43f44ff..f19155f 100644 (file)
@@ -304,9 +304,34 @@ state and recovery strategies taken.
   actor.
 
   It maintains a relationship to its Backend counterpart and routes operations
-  (remote) and transactions (local) towards it. Should a request time out, it
-  transitions to idle state and informs FrontendActor, which will resume it once
-  the leader location information is refreshed.
+  (remote) and transactions (local) towards it.
+
+  Requests sent from the frontend to the local history actor are subjects to timeouts.
+  If a timeout occurs, the frontend is expected to perform full backend leader
+  discovery, contact the leader and reconcile transaction state with it.
+
+  In order to minimize messaging latency while maintaining resiliency to message
+  loss (due to TCP connectivity issues), there are two messaging patterns:
+
+  -- Frontend talks to the Shard. This is used during instantiation of a local
+     history, as well as state reconciliation after a retriable failure has
+     occurred (such as a request timeout).
+
+  -- Frontend talks to the Local History Actor. This is used during transaction
+     operation, e.g. when a transaction is being built up. Once the transaction
+     is readied, the LHA will send a message to the Shard, which takes ownership
+     of that transaction's state. Since this handoff is not observable by
+     the frontend (which would require additional round-trip), the Shard
+     replicates its responses to the LHA. In case a timeout occurs, the frontend
+     will contact the LHA (as that's the last endpoint it knows about), which
+     will replay the Shard message.
+
+  Messaging between a Local History Actor and its associated Shard is expected
+  to be reliable. This is guaranteed by the parent/child relationship, where 
+  Shard is the parent. If a Shard fails, all of its children will be restarted,
+  losing all state. If an LHA fails, Shard will be notified with Akka DeathWatch
+  pattern.
+
 
 ==== SingleTransactionActor
   A SingleTransactionActor takes care of transactions which are not tied to a

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.