opendaylight/md-sal/sal-distributed-datastore/src/main/java/org/opendaylight/controller/cluster/datastore/ShardCommitCoordinator.java

   1 /*
   2  * Copyright (c) 2014 Brocade Communications Systems, Inc. and others.  All rights reserved.
   3  *
   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
   7  */
   8 package org.opendaylight.controller.cluster.datastore;
   9
  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;
  24 import java.util.Map;
  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;
  42
  43 /**
  44  * Coordinates commits for a shard ensuring only one concurrent 3-phase commit.
  45  *
  46  * @author Thomas Pantelis
  47  */
  48 final class ShardCommitCoordinator {
  49
  50     // Interface hook for unit tests to replace or decorate the ShardDataTreeCohorts.
  51     @VisibleForTesting
  52     public interface CohortDecorator {
  53         ShardDataTreeCohort decorate(Identifier transactionID, ShardDataTreeCohort actual);
  54     }
  55
  56     private final Map<Identifier, CohortEntry> cohortCache = new HashMap<>();
  57
  58     private final ShardDataTree dataTree;
  59
  60     private final Logger log;
  61
  62     private final String name;
  63
  64     // This is a hook for unit tests to replace or decorate the ShardDataTreeCohorts.
  65     @VisibleForTesting
  66     private CohortDecorator cohortDecorator;
  67
  68     private ReadyTransactionReply readyTransactionReply;
  69
  70     ShardCommitCoordinator(final ShardDataTree dataTree, final Logger log, final String name) {
  71         this.log = log;
  72         this.name = name;
  73         this.dataTree = Preconditions.checkNotNull(dataTree);
  74     }
  75
  76     int getCohortCacheSize() {
  77         return cohortCache.size();
  78     }
  79
  80     private String persistenceId() {
  81         return dataTree.logContext();
  82     }
  83
  84     private ReadyTransactionReply readyTransactionReply(final ActorRef cohort) {
  85         if (readyTransactionReply == null) {
  86             readyTransactionReply = new ReadyTransactionReply(Serialization.serializedActorPath(cohort));
  87         }
  88
  89         return readyTransactionReply;
  90     }
  91
  92     /**
  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.
  95      *
  96      * @param ready the ForwardedReadyTransaction message to process
  97      * @param sender the sender of the message
  98      * @param shard the transaction's shard actor
  99      */
 100     void handleForwardedReadyTransaction(final ForwardedReadyTransaction ready, final ActorRef sender,
 101             final Shard shard) {
 102         log.debug("{}: Readying transaction {}, client version {}", name,
 103                 ready.getTransactionId(), ready.getTxnClientVersion());
 104
 105         final ShardDataTreeCohort cohort = ready.getTransaction().ready(ready.getParticipatingShardNames());
 106         final CohortEntry cohortEntry = CohortEntry.createReady(cohort, ready.getTxnClientVersion());
 107         cohortCache.put(cohortEntry.getTransactionId(), cohortEntry);
 108
 109         if (ready.isDoImmediateCommit()) {
 110             cohortEntry.setDoImmediateCommit(true);
 111             cohortEntry.setReplySender(sender);
 112             cohortEntry.setShard(shard);
 113             handleCanCommit(cohortEntry);
 114         } else {
 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());
 118         }
 119     }
 120
 121     /**
 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.
 126      *
 127      * @param batched the BatchedModifications message to process
 128      * @param sender the sender of the message
 129      */
 130     void handleBatchedModifications(final BatchedModifications batched, final ActorRef sender, final Shard shard) {
 131         CohortEntry cohortEntry = cohortCache.get(batched.getTransactionId());
 132         if (cohortEntry == null) {
 133             cohortEntry = CohortEntry.createOpen(dataTree.newReadWriteTransaction(batched.getTransactionId()),
 134                 batched.getVersion());
 135             cohortCache.put(cohortEntry.getTransactionId(), cohortEntry);
 136         }
 137
 138         if (log.isDebugEnabled()) {
 139             log.debug("{}: Applying {} batched modifications for Tx {}", name,
 140                     batched.getModifications().size(), batched.getTransactionId());
 141         }
 142
 143         cohortEntry.applyModifications(batched.getModifications());
 144
 145         if (batched.isReady()) {
 146             if (cohortEntry.getLastBatchedModificationsException() != null) {
 147                 cohortCache.remove(cohortEntry.getTransactionId());
 148                 throw cohortEntry.getLastBatchedModificationsException();
 149             }
 150
 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()));
 156             }
 157
 158             if (log.isDebugEnabled()) {
 159                 log.debug("{}: Readying Tx {}, client version {}", name,
 160                         batched.getTransactionId(), batched.getVersion());
 161             }
 162
 163             cohortEntry.setDoImmediateCommit(batched.isDoCommitOnReady());
 164             cohortEntry.ready(batched.getParticipatingShardNames(), cohortDecorator);
 165
 166             if (batched.isDoCommitOnReady()) {
 167                 cohortEntry.setReplySender(sender);
 168                 cohortEntry.setShard(shard);
 169                 handleCanCommit(cohortEntry);
 170             } else {
 171                 sender.tell(readyTransactionReply(shard.self()), shard.self());
 172             }
 173         } else {
 174             sender.tell(new BatchedModificationsReply(batched.getModifications().size()), shard.self());
 175         }
 176     }
 177
 178     /**
 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
 181      * dataTree.
 182      *
 183      * @param message the ReadyLocalTransaction message to process
 184      * @param sender the sender of the message
 185      * @param shard the transaction's shard actor
 186      */
 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());
 194
 195         log.debug("{}: Applying local modifications for Tx {}", name, txId);
 196
 197         if (message.isDoCommitOnReady()) {
 198             cohortEntry.setReplySender(sender);
 199             cohortEntry.setShard(shard);
 200             handleCanCommit(cohortEntry);
 201         } else {
 202             sender.tell(readyTransactionReply(shard.self()), shard.self());
 203         }
 204     }
 205
 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);
 211         }
 212
 213         cohortEntry.applyModifications(from.getModifications());
 214
 215         final LinkedList<BatchedModifications> newModifications = new LinkedList<>();
 216         cohortEntry.getTransaction().getSnapshot().applyToCursor(new AbstractBatchedModificationsCursor() {
 217             @Override
 218             protected BatchedModifications getModifications() {
 219                 if (newModifications.isEmpty()
 220                         || newModifications.getLast().getModifications().size() >= maxModificationsPerBatch) {
 221                     newModifications.add(new BatchedModifications(from.getTransactionId(), from.getVersion()));
 222                 }
 223
 224                 return newModifications.getLast();
 225             }
 226         });
 227
 228         BatchedModifications last = newModifications.getLast();
 229         last.setDoCommitOnReady(from.isDoCommitOnReady());
 230         if (from.isReady()) {
 231             last.setReady(from.getParticipatingShardNames());
 232         }
 233         last.setTotalMessagesSent(newModifications.size());
 234         return newModifications;
 235     }
 236
 237     private void handleCanCommit(final CohortEntry cohortEntry) {
 238         cohortEntry.canCommit(new FutureCallback<Void>() {
 239             @Override
 240             public void onSuccess(final Void result) {
 241                 log.debug("{}: canCommit for {}: success", name, cohortEntry.getTransactionId());
 242
 243                 if (cohortEntry.isDoImmediateCommit()) {
 244                     doCommit(cohortEntry);
 245                 } else {
 246                     cohortEntry.getReplySender().tell(
 247                         CanCommitTransactionReply.yes(cohortEntry.getClientVersion()).toSerializable(),
 248                         cohortEntry.getShard().self());
 249                 }
 250             }
 251
 252             @Override
 253             public void onFailure(final Throwable failure) {
 254                 log.debug("{}: An exception occurred during canCommit for {}", name, cohortEntry.getTransactionId(),
 255                     failure);
 256
 257                 cohortCache.remove(cohortEntry.getTransactionId());
 258                 cohortEntry.getReplySender().tell(new Failure(failure), cohortEntry.getShard().self());
 259             }
 260         });
 261     }
 262
 263     /**
 264      * This method handles the canCommit phase for a transaction.
 265      *
 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
 269      */
 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());
 281             return;
 282         }
 283
 284         cohortEntry.setReplySender(sender);
 285         cohortEntry.setShard(shard);
 286
 287         handleCanCommit(cohortEntry);
 288     }
 289
 290     void doCommit(final CohortEntry cohortEntry) {
 291         log.debug("{}: Committing transaction {}", name, cohortEntry.getTransactionId());
 292
 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>() {
 298             @Override
 299             public void onSuccess(final DataTreeCandidate candidate) {
 300                 finishCommit(cohortEntry.getReplySender(), cohortEntry);
 301             }
 302
 303             @Override
 304             public void onFailure(final Throwable failure) {
 305                 log.error("{} An exception occurred while preCommitting transaction {}", name,
 306                         cohortEntry.getTransactionId(), failure);
 307
 308                 cohortCache.remove(cohortEntry.getTransactionId());
 309                 cohortEntry.getReplySender().tell(new Failure(failure), cohortEntry.getShard().self());
 310             }
 311         });
 312     }
 313
 314     void finishCommit(final @NonNull ActorRef sender, final @NonNull CohortEntry cohortEntry) {
 315         log.debug("{}: Finishing commit for transaction {}", persistenceId(), cohortEntry.getTransactionId());
 316
 317         cohortEntry.commit(new FutureCallback<UnsignedLong>() {
 318             @Override
 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,
 322                     sender);
 323                 cohortEntry.getShard().getDataStore().purgeTransaction(txId, null);
 324
 325                 cohortCache.remove(cohortEntry.getTransactionId());
 326                 sender.tell(CommitTransactionReply.instance(cohortEntry.getClientVersion()).toSerializable(),
 327                     cohortEntry.getShard().self());
 328             }
 329
 330             @Override
 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);
 335
 336                 cohortCache.remove(cohortEntry.getTransactionId());
 337                 sender.tell(new Failure(failure), cohortEntry.getShard().self());
 338             }
 339         });
 340     }
 341
 342     /**
 343      * This method handles the preCommit and commit phases for a transaction.
 344      *
 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
 348      */
 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());
 358             return;
 359         }
 360
 361         cohortEntry.setReplySender(sender);
 362         doCommit(cohortEntry);
 363     }
 364
 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) {
 369             return;
 370         }
 371
 372         log.debug("{}: Aborting transaction {}", name, transactionID);
 373
 374         final ActorRef self = shard.getSelf();
 375         cohortEntry.abort(new FutureCallback<Void>() {
 376             @Override
 377             public void onSuccess(final Void result) {
 378                 shard.getDataStore().purgeTransaction(cohortEntry.getTransactionId(), null);
 379
 380                 if (sender != null) {
 381                     sender.tell(AbortTransactionReply.instance(cohortEntry.getClientVersion()).toSerializable(), self);
 382                 }
 383             }
 384
 385             @Override
 386             public void onFailure(final Throwable failure) {
 387                 log.error("{}: An exception happened during abort", name, failure);
 388                 shard.getDataStore().purgeTransaction(cohortEntry.getTransactionId(), null);
 389
 390                 if (sender != null) {
 391                     sender.tell(new Failure(failure), self);
 392                 }
 393             }
 394         });
 395
 396         shard.getShardMBean().incrementAbortTransactionsCount();
 397     }
 398
 399     void checkForExpiredTransactions(final long timeout, final Shard shard) {
 400         cohortCache.values().removeIf(CohortEntry::isFailed);
 401     }
 402
 403     void abortPendingTransactions(final String reason, final Shard shard) {
 404         final Failure failure = new Failure(new RuntimeException(reason));
 405         Collection<ShardDataTreeCohort> pending = dataTree.getAndClearPendingTransactions();
 406
 407         log.debug("{}: Aborting {} pending queued transactions", name, pending.size());
 408
 409         for (ShardDataTreeCohort cohort : pending) {
 410             CohortEntry cohortEntry = cohortCache.remove(cohort.getIdentifier());
 411             if (cohortEntry == null) {
 412                 continue;
 413             }
 414
 415             if (cohortEntry.getReplySender() != null) {
 416                 cohortEntry.getReplySender().tell(failure, shard.self());
 417             }
 418         }
 419
 420         cohortCache.clear();
 421     }
 422
 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) {
 428                 continue;
 429             }
 430
 431             final Deque<BatchedModifications> newMessages = new ArrayDeque<>();
 432             cohortEntry.getDataTreeModification().applyToCursor(new AbstractBatchedModificationsCursor() {
 433                 @Override
 434                 protected BatchedModifications getModifications() {
 435                     final BatchedModifications lastBatch = newMessages.peekLast();
 436
 437                     if (lastBatch != null && lastBatch.getModifications().size() >= maxModificationsPerBatch) {
 438                         return lastBatch;
 439                     }
 440
 441                     // Allocate a new message
 442                     final BatchedModifications ret = new BatchedModifications(cohortEntry.getTransactionId(),
 443                         cohortEntry.getClientVersion());
 444                     newMessages.add(ret);
 445                     return ret;
 446                 }
 447             });
 448
 449             final BatchedModifications last = newMessages.peekLast();
 450             if (last != null) {
 451                 final boolean immediate = cohortEntry.isDoImmediateCommit();
 452                 last.setDoCommitOnReady(immediate);
 453                 last.setReady(cohortEntry.getParticipatingShardNames());
 454                 last.setTotalMessagesSent(newMessages.size());
 455
 456                 messages.addAll(newMessages);
 457
 458                 if (!immediate) {
 459                     switch (cohort.getState()) {
 460                         case CAN_COMMIT_COMPLETE:
 461                         case CAN_COMMIT_PENDING:
 462                             messages.add(new CanCommitTransaction(cohortEntry.getTransactionId(),
 463                                 cohortEntry.getClientVersion()));
 464                             break;
 465                         case PRE_COMMIT_COMPLETE:
 466                         case PRE_COMMIT_PENDING:
 467                             messages.add(new CommitTransaction(cohortEntry.getTransactionId(),
 468                                 cohortEntry.getClientVersion()));
 469                             break;
 470                         default:
 471                             break;
 472                     }
 473                 }
 474             }
 475         }
 476
 477         return messages;
 478     }
 479
 480     @VisibleForTesting
 481     void setCohortDecorator(final CohortDecorator cohortDecorator) {
 482         this.cohortDecorator = cohortDecorator;
 483     }
 484 }