2 * Copyright (c) 2014 Brocade Communications Systems, Inc. and others. All rights reserved.
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
6 * and is available at http://www.eclipse.org/legal/epl-v10.html
8 package org.opendaylight.controller.cluster.datastore;
10 import akka.actor.ActorRef;
11 import akka.actor.Status.Failure;
12 import akka.serialization.Serialization;
13 import com.google.common.annotations.VisibleForTesting;
14 import com.google.common.base.Preconditions;
15 import com.google.common.primitives.UnsignedLong;
16 import com.google.common.util.concurrent.FutureCallback;
17 import java.util.ArrayDeque;
18 import java.util.ArrayList;
19 import java.util.Collection;
20 import java.util.Collections;
21 import java.util.Deque;
22 import java.util.HashMap;
23 import java.util.LinkedList;
25 import org.eclipse.jdt.annotation.NonNull;
26 import org.opendaylight.controller.cluster.access.concepts.TransactionIdentifier;
27 import org.opendaylight.controller.cluster.datastore.messages.AbortTransactionReply;
28 import org.opendaylight.controller.cluster.datastore.messages.BatchedModifications;
29 import org.opendaylight.controller.cluster.datastore.messages.BatchedModificationsReply;
30 import org.opendaylight.controller.cluster.datastore.messages.CanCommitTransaction;
31 import org.opendaylight.controller.cluster.datastore.messages.CanCommitTransactionReply;
32 import org.opendaylight.controller.cluster.datastore.messages.CommitTransaction;
33 import org.opendaylight.controller.cluster.datastore.messages.CommitTransactionReply;
34 import org.opendaylight.controller.cluster.datastore.messages.ForwardedReadyTransaction;
35 import org.opendaylight.controller.cluster.datastore.messages.ReadyLocalTransaction;
36 import org.opendaylight.controller.cluster.datastore.messages.ReadyTransactionReply;
37 import org.opendaylight.controller.cluster.datastore.messages.VersionedExternalizableMessage;
38 import org.opendaylight.controller.cluster.datastore.utils.AbstractBatchedModificationsCursor;
39 import org.opendaylight.yangtools.concepts.Identifier;
40 import org.opendaylight.yangtools.yang.data.api.schema.tree.DataTreeCandidate;
41 import org.slf4j.Logger;
44 * Coordinates commits for a shard ensuring only one concurrent 3-phase commit.
46 * @author Thomas Pantelis
48 final class ShardCommitCoordinator {
50 // Interface hook for unit tests to replace or decorate the ShardDataTreeCohorts.
52 public interface CohortDecorator {
53 ShardDataTreeCohort decorate(Identifier transactionID, ShardDataTreeCohort actual);
56 private final Map<Identifier, CohortEntry> cohortCache = new HashMap<>();
58 private final ShardDataTree dataTree;
60 private final Logger log;
62 private final String name;
64 // This is a hook for unit tests to replace or decorate the ShardDataTreeCohorts.
66 private CohortDecorator cohortDecorator;
68 private ReadyTransactionReply readyTransactionReply;
70 ShardCommitCoordinator(final ShardDataTree dataTree, final Logger log, final String name) {
73 this.dataTree = Preconditions.checkNotNull(dataTree);
76 int getCohortCacheSize() {
77 return cohortCache.size();
80 private String persistenceId() {
81 return dataTree.logContext();
84 private ReadyTransactionReply readyTransactionReply(final ActorRef cohort) {
85 if (readyTransactionReply == null) {
86 readyTransactionReply = new ReadyTransactionReply(Serialization.serializedActorPath(cohort));
89 return readyTransactionReply;
93 * This method is called to ready a transaction that was prepared by ShardTransaction actor. It caches
94 * the prepared cohort entry for the given transactions ID in preparation for the subsequent 3-phase commit.
96 * @param ready the ForwardedReadyTransaction message to process
97 * @param sender the sender of the message
98 * @param shard the transaction's shard actor
100 void handleForwardedReadyTransaction(final ForwardedReadyTransaction ready, final ActorRef sender,
102 log.debug("{}: Readying transaction {}, client version {}", name,
103 ready.getTransactionId(), ready.getTxnClientVersion());
105 final ShardDataTreeCohort cohort = ready.getTransaction().ready(ready.getParticipatingShardNames());
106 final CohortEntry cohortEntry = CohortEntry.createReady(cohort, ready.getTxnClientVersion());
107 cohortCache.put(cohortEntry.getTransactionId(), cohortEntry);
109 if (ready.isDoImmediateCommit()) {
110 cohortEntry.setDoImmediateCommit(true);
111 cohortEntry.setReplySender(sender);
112 cohortEntry.setShard(shard);
113 handleCanCommit(cohortEntry);
115 // The caller does not want immediate commit - the 3-phase commit will be coordinated by the
116 // front-end so send back a ReadyTransactionReply with our actor path.
117 sender.tell(readyTransactionReply(shard.self()), shard.self());
122 * This method handles a BatchedModifications message for a transaction being prepared directly on the
123 * Shard actor instead of via a ShardTransaction actor. If there's no currently cached
124 * DOMStoreWriteTransaction, one is created. The batched modifications are applied to the write Tx. If
125 * the BatchedModifications is ready to commit then a DOMStoreThreePhaseCommitCohort is created.
127 * @param batched the BatchedModifications message to process
128 * @param sender the sender of the message
130 void handleBatchedModifications(final BatchedModifications batched, final ActorRef sender, final Shard shard) {
131 CohortEntry cohortEntry = cohortCache.get(batched.getTransactionId());
132 if (cohortEntry == null || cohortEntry.isSealed()) {
133 cohortEntry = CohortEntry.createOpen(dataTree.newReadWriteTransaction(batched.getTransactionId()),
134 batched.getVersion());
135 cohortCache.put(cohortEntry.getTransactionId(), cohortEntry);
138 if (log.isDebugEnabled()) {
139 log.debug("{}: Applying {} batched modifications for Tx {}", name,
140 batched.getModifications().size(), batched.getTransactionId());
143 cohortEntry.applyModifications(batched.getModifications());
145 if (batched.isReady()) {
146 if (cohortEntry.getLastBatchedModificationsException() != null) {
147 cohortCache.remove(cohortEntry.getTransactionId());
148 throw cohortEntry.getLastBatchedModificationsException();
151 if (cohortEntry.getTotalBatchedModificationsReceived() != batched.getTotalMessagesSent()) {
152 cohortCache.remove(cohortEntry.getTransactionId());
153 throw new IllegalStateException(String.format(
154 "The total number of batched messages received %d does not match the number sent %d",
155 cohortEntry.getTotalBatchedModificationsReceived(), batched.getTotalMessagesSent()));
158 if (log.isDebugEnabled()) {
159 log.debug("{}: Readying Tx {}, client version {}", name,
160 batched.getTransactionId(), batched.getVersion());
163 cohortEntry.setDoImmediateCommit(batched.isDoCommitOnReady());
164 cohortEntry.ready(batched.getParticipatingShardNames(), cohortDecorator);
166 if (batched.isDoCommitOnReady()) {
167 cohortEntry.setReplySender(sender);
168 cohortEntry.setShard(shard);
169 handleCanCommit(cohortEntry);
171 sender.tell(readyTransactionReply(shard.self()), shard.self());
174 sender.tell(new BatchedModificationsReply(batched.getModifications().size()), shard.self());
179 * This method handles {@link ReadyLocalTransaction} message. All transaction modifications have
180 * been prepared beforehand by the sender and we just need to drive them through into the
183 * @param message the ReadyLocalTransaction message to process
184 * @param sender the sender of the message
185 * @param shard the transaction's shard actor
187 void handleReadyLocalTransaction(final ReadyLocalTransaction message, final ActorRef sender, final Shard shard) {
188 final TransactionIdentifier txId = message.getTransactionId();
189 final ShardDataTreeCohort cohort = dataTree.newReadyCohort(txId, message.getModification(),
190 message.getParticipatingShardNames());
191 final CohortEntry cohortEntry = CohortEntry.createReady(cohort, DataStoreVersions.CURRENT_VERSION);
192 cohortCache.put(cohortEntry.getTransactionId(), cohortEntry);
193 cohortEntry.setDoImmediateCommit(message.isDoCommitOnReady());
195 log.debug("{}: Applying local modifications for Tx {}", name, txId);
197 if (message.isDoCommitOnReady()) {
198 cohortEntry.setReplySender(sender);
199 cohortEntry.setShard(shard);
200 handleCanCommit(cohortEntry);
202 sender.tell(readyTransactionReply(shard.self()), shard.self());
206 Collection<BatchedModifications> createForwardedBatchedModifications(final BatchedModifications from,
207 final int maxModificationsPerBatch) {
208 CohortEntry cohortEntry = cohortCache.remove(from.getTransactionId());
209 if (cohortEntry == null || cohortEntry.getTransaction() == null) {
210 return Collections.singletonList(from);
213 cohortEntry.applyModifications(from.getModifications());
215 final LinkedList<BatchedModifications> newModifications = new LinkedList<>();
216 cohortEntry.getTransaction().getSnapshot().applyToCursor(new AbstractBatchedModificationsCursor() {
218 protected BatchedModifications getModifications() {
219 if (newModifications.isEmpty()
220 || newModifications.getLast().getModifications().size() >= maxModificationsPerBatch) {
221 newModifications.add(new BatchedModifications(from.getTransactionId(), from.getVersion()));
224 return newModifications.getLast();
228 BatchedModifications last = newModifications.getLast();
229 last.setDoCommitOnReady(from.isDoCommitOnReady());
230 if (from.isReady()) {
231 last.setReady(from.getParticipatingShardNames());
233 last.setTotalMessagesSent(newModifications.size());
234 return newModifications;
237 private void handleCanCommit(final CohortEntry cohortEntry) {
238 cohortEntry.canCommit(new FutureCallback<Void>() {
240 public void onSuccess(final Void result) {
241 log.debug("{}: canCommit for {}: success", name, cohortEntry.getTransactionId());
243 if (cohortEntry.isDoImmediateCommit()) {
244 doCommit(cohortEntry);
246 cohortEntry.getReplySender().tell(
247 CanCommitTransactionReply.yes(cohortEntry.getClientVersion()).toSerializable(),
248 cohortEntry.getShard().self());
253 public void onFailure(final Throwable failure) {
254 log.debug("{}: An exception occurred during canCommit for {}", name, cohortEntry.getTransactionId(),
257 cohortCache.remove(cohortEntry.getTransactionId());
258 cohortEntry.getReplySender().tell(new Failure(failure), cohortEntry.getShard().self());
264 * This method handles the canCommit phase for a transaction.
266 * @param transactionID the ID of the transaction to canCommit
267 * @param sender the actor to which to send the response
268 * @param shard the transaction's shard actor
270 void handleCanCommit(final Identifier transactionID, final ActorRef sender, final Shard shard) {
271 // Lookup the cohort entry that was cached previously (or should have been) by
272 // transactionReady (via the ForwardedReadyTransaction message).
273 final CohortEntry cohortEntry = cohortCache.get(transactionID);
274 if (cohortEntry == null) {
275 // Either canCommit was invoked before ready (shouldn't happen) or a long time passed
276 // between canCommit and ready and the entry was expired from the cache or it was aborted.
277 IllegalStateException ex = new IllegalStateException(
278 String.format("%s: Cannot canCommit transaction %s - no cohort entry found", name, transactionID));
279 log.error("{}: Inconsistency during transaction {} canCommit", name, transactionID, ex);
280 sender.tell(new Failure(ex), shard.self());
284 cohortEntry.setReplySender(sender);
285 cohortEntry.setShard(shard);
287 handleCanCommit(cohortEntry);
290 void doCommit(final CohortEntry cohortEntry) {
291 log.debug("{}: Committing transaction {}", name, cohortEntry.getTransactionId());
293 // We perform the preCommit phase here atomically with the commit phase. This is an
294 // optimization to eliminate the overhead of an extra preCommit message. We lose front-end
295 // coordination of preCommit across shards in case of failure but preCommit should not
296 // normally fail since we ensure only one concurrent 3-phase commit.
297 cohortEntry.preCommit(new FutureCallback<DataTreeCandidate>() {
299 public void onSuccess(final DataTreeCandidate candidate) {
300 finishCommit(cohortEntry.getReplySender(), cohortEntry);
304 public void onFailure(final Throwable failure) {
305 log.error("{} An exception occurred while preCommitting transaction {}", name,
306 cohortEntry.getTransactionId(), failure);
308 cohortCache.remove(cohortEntry.getTransactionId());
309 cohortEntry.getReplySender().tell(new Failure(failure), cohortEntry.getShard().self());
314 void finishCommit(final @NonNull ActorRef sender, final @NonNull CohortEntry cohortEntry) {
315 log.debug("{}: Finishing commit for transaction {}", persistenceId(), cohortEntry.getTransactionId());
317 cohortEntry.commit(new FutureCallback<UnsignedLong>() {
319 public void onSuccess(final UnsignedLong result) {
320 final TransactionIdentifier txId = cohortEntry.getTransactionId();
321 log.debug("{}: Transaction {} committed as {}, sending response to {}", persistenceId(), txId, result,
323 cohortEntry.getShard().getDataStore().purgeTransaction(txId, null);
325 cohortCache.remove(cohortEntry.getTransactionId());
326 sender.tell(CommitTransactionReply.instance(cohortEntry.getClientVersion()).toSerializable(),
327 cohortEntry.getShard().self());
331 public void onFailure(final Throwable failure) {
332 final TransactionIdentifier txId = cohortEntry.getTransactionId();
333 log.error("{}, An exception occurred while committing transaction {}", persistenceId(), txId, failure);
334 cohortEntry.getShard().getDataStore().purgeTransaction(txId, null);
336 cohortCache.remove(cohortEntry.getTransactionId());
337 sender.tell(new Failure(failure), cohortEntry.getShard().self());
343 * This method handles the preCommit and commit phases for a transaction.
345 * @param transactionID the ID of the transaction to commit
346 * @param sender the actor to which to send the response
347 * @param shard the transaction's shard actor
349 void handleCommit(final Identifier transactionID, final ActorRef sender, final Shard shard) {
350 final CohortEntry cohortEntry = cohortCache.get(transactionID);
351 if (cohortEntry == null) {
352 // Either a long time passed between canCommit and commit and the entry was expired from the cache
353 // or it was aborted.
354 IllegalStateException ex = new IllegalStateException(
355 String.format("%s: Cannot commit transaction %s - no cohort entry found", name, transactionID));
356 log.error("{}: Inconsistency during transaction {} commit", name, transactionID, ex);
357 sender.tell(new Failure(ex), shard.self());
361 cohortEntry.setReplySender(sender);
362 doCommit(cohortEntry);
365 @SuppressWarnings("checkstyle:IllegalCatch")
366 void handleAbort(final Identifier transactionID, final ActorRef sender, final Shard shard) {
367 CohortEntry cohortEntry = cohortCache.remove(transactionID);
368 if (cohortEntry == null) {
372 log.debug("{}: Aborting transaction {}", name, transactionID);
374 final ActorRef self = shard.getSelf();
375 cohortEntry.abort(new FutureCallback<Void>() {
377 public void onSuccess(final Void result) {
378 shard.getDataStore().purgeTransaction(cohortEntry.getTransactionId(), null);
380 if (sender != null) {
381 sender.tell(AbortTransactionReply.instance(cohortEntry.getClientVersion()).toSerializable(), self);
386 public void onFailure(final Throwable failure) {
387 log.error("{}: An exception happened during abort", name, failure);
388 shard.getDataStore().purgeTransaction(cohortEntry.getTransactionId(), null);
390 if (sender != null) {
391 sender.tell(new Failure(failure), self);
396 shard.getShardMBean().incrementAbortTransactionsCount();
399 void checkForExpiredTransactions(final long timeout, final Shard shard) {
400 cohortCache.values().removeIf(CohortEntry::isFailed);
403 void abortPendingTransactions(final String reason, final Shard shard) {
404 final Failure failure = new Failure(new RuntimeException(reason));
405 Collection<ShardDataTreeCohort> pending = dataTree.getAndClearPendingTransactions();
407 log.debug("{}: Aborting {} pending queued transactions", name, pending.size());
409 for (ShardDataTreeCohort cohort : pending) {
410 CohortEntry cohortEntry = cohortCache.remove(cohort.getIdentifier());
411 if (cohortEntry == null) {
415 if (cohortEntry.getReplySender() != null) {
416 cohortEntry.getReplySender().tell(failure, shard.self());
423 Collection<?> convertPendingTransactionsToMessages(final int maxModificationsPerBatch) {
424 final Collection<VersionedExternalizableMessage> messages = new ArrayList<>();
425 for (ShardDataTreeCohort cohort : dataTree.getAndClearPendingTransactions()) {
426 CohortEntry cohortEntry = cohortCache.remove(cohort.getIdentifier());
427 if (cohortEntry == null) {
431 final Deque<BatchedModifications> newMessages = new ArrayDeque<>();
432 cohortEntry.getDataTreeModification().applyToCursor(new AbstractBatchedModificationsCursor() {
434 protected BatchedModifications getModifications() {
435 final BatchedModifications lastBatch = newMessages.peekLast();
437 if (lastBatch != null && lastBatch.getModifications().size() >= maxModificationsPerBatch) {
441 // Allocate a new message
442 final BatchedModifications ret = new BatchedModifications(cohortEntry.getTransactionId(),
443 cohortEntry.getClientVersion());
444 newMessages.add(ret);
449 final BatchedModifications last = newMessages.peekLast();
451 final boolean immediate = cohortEntry.isDoImmediateCommit();
452 last.setDoCommitOnReady(immediate);
453 last.setReady(cohortEntry.getParticipatingShardNames());
454 last.setTotalMessagesSent(newMessages.size());
456 messages.addAll(newMessages);
459 switch (cohort.getState()) {
460 case CAN_COMMIT_COMPLETE:
461 case CAN_COMMIT_PENDING:
462 messages.add(new CanCommitTransaction(cohortEntry.getTransactionId(),
463 cohortEntry.getClientVersion()));
465 case PRE_COMMIT_COMPLETE:
466 case PRE_COMMIT_PENDING:
467 messages.add(new CommitTransaction(cohortEntry.getTransactionId(),
468 cohortEntry.getClientVersion()));
481 void setCohortDecorator(final CohortDecorator cohortDecorator) {
482 this.cohortDecorator = cohortDecorator;