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.Iterator;
  24 import java.util.LinkedList;
  25 import java.util.Map;
  26 import javax.annotation.Nonnull;
  27 import org.opendaylight.controller.cluster.access.concepts.TransactionIdentifier;
  28 import org.opendaylight.controller.cluster.datastore.messages.AbortTransactionReply;
  29 import org.opendaylight.controller.cluster.datastore.messages.BatchedModifications;
  30 import org.opendaylight.controller.cluster.datastore.messages.BatchedModificationsReply;
  31 import org.opendaylight.controller.cluster.datastore.messages.CanCommitTransaction;
  32 import org.opendaylight.controller.cluster.datastore.messages.CanCommitTransactionReply;
  33 import org.opendaylight.controller.cluster.datastore.messages.CommitTransaction;
  34 import org.opendaylight.controller.cluster.datastore.messages.CommitTransactionReply;
  35 import org.opendaylight.controller.cluster.datastore.messages.ForwardedReadyTransaction;
  36 import org.opendaylight.controller.cluster.datastore.messages.ReadyLocalTransaction;
  37 import org.opendaylight.controller.cluster.datastore.messages.ReadyTransactionReply;
  38 import org.opendaylight.controller.cluster.datastore.messages.VersionedExternalizableMessage;
  39 import org.opendaylight.controller.cluster.datastore.utils.AbstractBatchedModificationsCursor;
  40 import org.opendaylight.yangtools.concepts.Identifier;
  41 import org.opendaylight.yangtools.yang.data.api.schema.tree.DataTreeCandidate;
  42 import org.slf4j.Logger;
  43
  44 /**
  45  * Coordinates commits for a shard ensuring only one concurrent 3-phase commit.
  46  *
  47  * @author Thomas Pantelis
  48  */
  49 final class ShardCommitCoordinator {
  50
  51     // Interface hook for unit tests to replace or decorate the ShardDataTreeCohorts.
  52     @VisibleForTesting
  53     public interface CohortDecorator {
  54         ShardDataTreeCohort decorate(Identifier transactionID, ShardDataTreeCohort actual);
  55     }
  56
  57     private final Map<Identifier, CohortEntry> cohortCache = new HashMap<>();
  58
  59     private final ShardDataTree dataTree;
  60
  61     private final Logger log;
  62
  63     private final String name;
  64
  65     // This is a hook for unit tests to replace or decorate the ShardDataTreeCohorts.
  66     @VisibleForTesting
  67     private CohortDecorator cohortDecorator;
  68
  69     private ReadyTransactionReply readyTransactionReply;
  70
  71     ShardCommitCoordinator(final ShardDataTree dataTree, final Logger log, final String name) {
  72         this.log = log;
  73         this.name = name;
  74         this.dataTree = Preconditions.checkNotNull(dataTree);
  75     }
  76
  77     int getCohortCacheSize() {
  78         return cohortCache.size();
  79     }
  80
  81     private String persistenceId() {
  82         return dataTree.logContext();
  83     }
  84
  85     private ReadyTransactionReply readyTransactionReply(final ActorRef cohort) {
  86         if (readyTransactionReply == null) {
  87             readyTransactionReply = new ReadyTransactionReply(Serialization.serializedActorPath(cohort));
  88         }
  89
  90         return readyTransactionReply;
  91     }
  92
  93     /**
  94      * This method is called to ready a transaction that was prepared by ShardTransaction actor. It caches
  95      * the prepared cohort entry for the given transactions ID in preparation for the subsequent 3-phase commit.
  96      *
  97      * @param ready the ForwardedReadyTransaction message to process
  98      * @param sender the sender of the message
  99      * @param shard the transaction's shard actor
 100      */
 101     void handleForwardedReadyTransaction(final ForwardedReadyTransaction ready, final ActorRef sender,
 102             final Shard shard) {
 103         log.debug("{}: Readying transaction {}, client version {}", name,
 104                 ready.getTransactionId(), ready.getTxnClientVersion());
 105
 106         final ShardDataTreeCohort cohort = ready.getTransaction().ready(ready.getParticipatingShardNames());
 107         final CohortEntry cohortEntry = CohortEntry.createReady(cohort, ready.getTxnClientVersion());
 108         cohortCache.put(cohortEntry.getTransactionId(), cohortEntry);
 109
 110         if (ready.isDoImmediateCommit()) {
 111             cohortEntry.setDoImmediateCommit(true);
 112             cohortEntry.setReplySender(sender);
 113             cohortEntry.setShard(shard);
 114             handleCanCommit(cohortEntry);
 115         } else {
 116             // The caller does not want immediate commit - the 3-phase commit will be coordinated by the
 117             // front-end so send back a ReadyTransactionReply with our actor path.
 118             sender.tell(readyTransactionReply(shard.self()), shard.self());
 119         }
 120     }
 121
 122     /**
 123      * This method handles a BatchedModifications message for a transaction being prepared directly on the
 124      * Shard actor instead of via a ShardTransaction actor. If there's no currently cached
 125      * DOMStoreWriteTransaction, one is created. The batched modifications are applied to the write Tx. If
 126      * the BatchedModifications is ready to commit then a DOMStoreThreePhaseCommitCohort is created.
 127      *
 128      * @param batched the BatchedModifications message to process
 129      * @param sender the sender of the message
 130      */
 131     void handleBatchedModifications(final BatchedModifications batched, final ActorRef sender, final Shard shard) {
 132         CohortEntry cohortEntry = cohortCache.get(batched.getTransactionId());
 133         if (cohortEntry == null) {
 134             cohortEntry = CohortEntry.createOpen(dataTree.newReadWriteTransaction(batched.getTransactionId()),
 135                 batched.getVersion());
 136             cohortCache.put(cohortEntry.getTransactionId(), cohortEntry);
 137         }
 138
 139         if (log.isDebugEnabled()) {
 140             log.debug("{}: Applying {} batched modifications for Tx {}", name,
 141                     batched.getModifications().size(), batched.getTransactionId());
 142         }
 143
 144         cohortEntry.applyModifications(batched.getModifications());
 145
 146         if (batched.isReady()) {
 147             if (cohortEntry.getLastBatchedModificationsException() != null) {
 148                 cohortCache.remove(cohortEntry.getTransactionId());
 149                 throw cohortEntry.getLastBatchedModificationsException();
 150             }
 151
 152             if (cohortEntry.getTotalBatchedModificationsReceived() != batched.getTotalMessagesSent()) {
 153                 cohortCache.remove(cohortEntry.getTransactionId());
 154                 throw new IllegalStateException(String.format(
 155                         "The total number of batched messages received %d does not match the number sent %d",
 156                         cohortEntry.getTotalBatchedModificationsReceived(), batched.getTotalMessagesSent()));
 157             }
 158
 159             if (log.isDebugEnabled()) {
 160                 log.debug("{}: Readying Tx {}, client version {}", name,
 161                         batched.getTransactionId(), batched.getVersion());
 162             }
 163
 164             cohortEntry.setDoImmediateCommit(batched.isDoCommitOnReady());
 165             cohortEntry.ready(batched.getParticipatingShardNames(), cohortDecorator);
 166
 167             if (batched.isDoCommitOnReady()) {
 168                 cohortEntry.setReplySender(sender);
 169                 cohortEntry.setShard(shard);
 170                 handleCanCommit(cohortEntry);
 171             } else {
 172                 sender.tell(readyTransactionReply(shard.self()), shard.self());
 173             }
 174         } else {
 175             sender.tell(new BatchedModificationsReply(batched.getModifications().size()), shard.self());
 176         }
 177     }
 178
 179     /**
 180      * This method handles {@link ReadyLocalTransaction} message. All transaction modifications have
 181      * been prepared beforehand by the sender and we just need to drive them through into the
 182      * dataTree.
 183      *
 184      * @param message the ReadyLocalTransaction message to process
 185      * @param sender the sender of the message
 186      * @param shard the transaction's shard actor
 187      */
 188     void handleReadyLocalTransaction(final ReadyLocalTransaction message, final ActorRef sender, final Shard shard) {
 189         final TransactionIdentifier txId = message.getTransactionId();
 190         final ShardDataTreeCohort cohort = dataTree.newReadyCohort(txId, message.getModification(),
 191                 message.getParticipatingShardNames());
 192         final CohortEntry cohortEntry = CohortEntry.createReady(cohort, DataStoreVersions.CURRENT_VERSION);
 193         cohortCache.put(cohortEntry.getTransactionId(), cohortEntry);
 194         cohortEntry.setDoImmediateCommit(message.isDoCommitOnReady());
 195
 196         log.debug("{}: Applying local modifications for Tx {}", name, txId);
 197
 198         if (message.isDoCommitOnReady()) {
 199             cohortEntry.setReplySender(sender);
 200             cohortEntry.setShard(shard);
 201             handleCanCommit(cohortEntry);
 202         } else {
 203             sender.tell(readyTransactionReply(shard.self()), shard.self());
 204         }
 205     }
 206
 207     Collection<BatchedModifications> createForwardedBatchedModifications(final BatchedModifications from,
 208             final int maxModificationsPerBatch) {
 209         CohortEntry cohortEntry = cohortCache.remove(from.getTransactionId());
 210         if (cohortEntry == null || cohortEntry.getTransaction() == null) {
 211             return Collections.singletonList(from);
 212         }
 213
 214         cohortEntry.applyModifications(from.getModifications());
 215
 216         final LinkedList<BatchedModifications> newModifications = new LinkedList<>();
 217         cohortEntry.getTransaction().getSnapshot().applyToCursor(new AbstractBatchedModificationsCursor() {
 218             @Override
 219             protected BatchedModifications getModifications() {
 220                 if (newModifications.isEmpty()
 221                         || newModifications.getLast().getModifications().size() >= maxModificationsPerBatch) {
 222                     newModifications.add(new BatchedModifications(from.getTransactionId(), from.getVersion()));
 223                 }
 224
 225                 return newModifications.getLast();
 226             }
 227         });
 228
 229         BatchedModifications last = newModifications.getLast();
 230         last.setDoCommitOnReady(from.isDoCommitOnReady());
 231         if (from.isReady()) {
 232             last.setReady(from.getParticipatingShardNames());
 233         }
 234         last.setTotalMessagesSent(newModifications.size());
 235         return newModifications;
 236     }
 237
 238     private void handleCanCommit(final CohortEntry cohortEntry) {
 239         cohortEntry.canCommit(new FutureCallback<Void>() {
 240             @Override
 241             public void onSuccess(final Void result) {
 242                 log.debug("{}: canCommit for {}: success", name, cohortEntry.getTransactionId());
 243
 244                 if (cohortEntry.isDoImmediateCommit()) {
 245                     doCommit(cohortEntry);
 246                 } else {
 247                     cohortEntry.getReplySender().tell(
 248                         CanCommitTransactionReply.yes(cohortEntry.getClientVersion()).toSerializable(),
 249                         cohortEntry.getShard().self());
 250                 }
 251             }
 252
 253             @Override
 254             public void onFailure(final Throwable failure) {
 255                 log.debug("{}: An exception occurred during canCommit for {}: {}", name,
 256                         cohortEntry.getTransactionId(), failure);
 257
 258                 cohortCache.remove(cohortEntry.getTransactionId());
 259                 cohortEntry.getReplySender().tell(new Failure(failure), cohortEntry.getShard().self());
 260             }
 261         });
 262     }
 263
 264     /**
 265      * This method handles the canCommit phase for a transaction.
 266      *
 267      * @param transactionID the ID of the transaction to canCommit
 268      * @param sender the actor to which to send the response
 269      * @param shard the transaction's shard actor
 270      */
 271     void handleCanCommit(final Identifier transactionID, final ActorRef sender, final Shard shard) {
 272         // Lookup the cohort entry that was cached previously (or should have been) by
 273         // transactionReady (via the ForwardedReadyTransaction message).
 274         final CohortEntry cohortEntry = cohortCache.get(transactionID);
 275         if (cohortEntry == null) {
 276             // Either canCommit was invoked before ready (shouldn't happen) or a long time passed
 277             // between canCommit and ready and the entry was expired from the cache or it was aborted.
 278             IllegalStateException ex = new IllegalStateException(
 279                     String.format("%s: Cannot canCommit transaction %s - no cohort entry found", name, transactionID));
 280             log.error(ex.getMessage());
 281             sender.tell(new Failure(ex), shard.self());
 282             return;
 283         }
 284
 285         cohortEntry.setReplySender(sender);
 286         cohortEntry.setShard(shard);
 287
 288         handleCanCommit(cohortEntry);
 289     }
 290
 291     void doCommit(final CohortEntry cohortEntry) {
 292         log.debug("{}: Committing transaction {}", name, cohortEntry.getTransactionId());
 293
 294         // We perform the preCommit phase here atomically with the commit phase. This is an
 295         // optimization to eliminate the overhead of an extra preCommit message. We lose front-end
 296         // coordination of preCommit across shards in case of failure but preCommit should not
 297         // normally fail since we ensure only one concurrent 3-phase commit.
 298         cohortEntry.preCommit(new FutureCallback<DataTreeCandidate>() {
 299             @Override
 300             public void onSuccess(final DataTreeCandidate candidate) {
 301                 finishCommit(cohortEntry.getReplySender(), cohortEntry);
 302             }
 303
 304             @Override
 305             public void onFailure(final Throwable failure) {
 306                 log.error("{} An exception occurred while preCommitting transaction {}", name,
 307                         cohortEntry.getTransactionId(), failure);
 308
 309                 cohortCache.remove(cohortEntry.getTransactionId());
 310                 cohortEntry.getReplySender().tell(new Failure(failure), cohortEntry.getShard().self());
 311             }
 312         });
 313     }
 314
 315     void finishCommit(@Nonnull final ActorRef sender, @Nonnull final CohortEntry cohortEntry) {
 316         log.debug("{}: Finishing commit for transaction {}", persistenceId(), cohortEntry.getTransactionId());
 317
 318         cohortEntry.commit(new FutureCallback<UnsignedLong>() {
 319             @Override
 320             public void onSuccess(final UnsignedLong result) {
 321                 final TransactionIdentifier txId = cohortEntry.getTransactionId();
 322                 log.debug("{}: Transaction {} committed as {}, sending response to {}", persistenceId(), txId, result,
 323                     sender);
 324                 cohortEntry.getShard().getDataStore().purgeTransaction(txId, null);
 325
 326                 cohortCache.remove(cohortEntry.getTransactionId());
 327                 sender.tell(CommitTransactionReply.instance(cohortEntry.getClientVersion()).toSerializable(),
 328                     cohortEntry.getShard().self());
 329             }
 330
 331             @Override
 332             public void onFailure(final Throwable failure) {
 333                 final TransactionIdentifier txId = cohortEntry.getTransactionId();
 334                 log.error("{}, An exception occurred while committing transaction {}", persistenceId(), txId, failure);
 335                 cohortEntry.getShard().getDataStore().purgeTransaction(txId, null);
 336
 337                 cohortCache.remove(cohortEntry.getTransactionId());
 338                 sender.tell(new Failure(failure), cohortEntry.getShard().self());
 339             }
 340         });
 341     }
 342
 343     /**
 344      * This method handles the preCommit and commit phases for a transaction.
 345      *
 346      * @param transactionID the ID of the transaction to commit
 347      * @param sender the actor to which to send the response
 348      * @param shard the transaction's shard actor
 349      */
 350     void handleCommit(final Identifier transactionID, final ActorRef sender, final Shard shard) {
 351         final CohortEntry cohortEntry = cohortCache.get(transactionID);
 352         if (cohortEntry == null) {
 353             // Either a long time passed between canCommit and commit and the entry was expired from the cache
 354             // or it was aborted.
 355             IllegalStateException ex = new IllegalStateException(
 356                     String.format("%s: Cannot commit transaction %s - no cohort entry found", name, transactionID));
 357             log.error(ex.getMessage());
 358             sender.tell(new Failure(ex), shard.self());
 359             return;
 360         }
 361
 362         cohortEntry.setReplySender(sender);
 363         doCommit(cohortEntry);
 364     }
 365
 366     @SuppressWarnings("checkstyle:IllegalCatch")
 367     void handleAbort(final Identifier transactionID, final ActorRef sender, final Shard shard) {
 368         CohortEntry cohortEntry = cohortCache.remove(transactionID);
 369         if (cohortEntry == null) {
 370             return;
 371         }
 372
 373         log.debug("{}: Aborting transaction {}", name, transactionID);
 374
 375         final ActorRef self = shard.getSelf();
 376         cohortEntry.abort(new FutureCallback<Void>() {
 377             @Override
 378             public void onSuccess(final Void result) {
 379                 shard.getDataStore().purgeTransaction(cohortEntry.getTransactionId(), null);
 380
 381                 if (sender != null) {
 382                     sender.tell(AbortTransactionReply.instance(cohortEntry.getClientVersion()).toSerializable(), self);
 383                 }
 384             }
 385
 386             @Override
 387             public void onFailure(final Throwable failure) {
 388                 log.error("{}: An exception happened during abort", name, failure);
 389                 shard.getDataStore().purgeTransaction(cohortEntry.getTransactionId(), null);
 390
 391                 if (sender != null) {
 392                     sender.tell(new Failure(failure), self);
 393                 }
 394             }
 395         });
 396
 397         shard.getShardMBean().incrementAbortTransactionsCount();
 398     }
 399
 400     void checkForExpiredTransactions(final long timeout, final Shard shard) {
 401         Iterator<CohortEntry> iter = cohortCache.values().iterator();
 402         while (iter.hasNext()) {
 403             CohortEntry cohortEntry = iter.next();
 404             if (cohortEntry.isFailed()) {
 405                 iter.remove();
 406             }
 407         }
 408     }
 409
 410     void abortPendingTransactions(final String reason, final Shard shard) {
 411         final Failure failure = new Failure(new RuntimeException(reason));
 412         Collection<ShardDataTreeCohort> pending = dataTree.getAndClearPendingTransactions();
 413
 414         log.debug("{}: Aborting {} pending queued transactions", name, pending.size());
 415
 416         for (ShardDataTreeCohort cohort : pending) {
 417             CohortEntry cohortEntry = cohortCache.remove(cohort.getIdentifier());
 418             if (cohortEntry == null) {
 419                 continue;
 420             }
 421
 422             if (cohortEntry.getReplySender() != null) {
 423                 cohortEntry.getReplySender().tell(failure, shard.self());
 424             }
 425         }
 426
 427         cohortCache.clear();
 428     }
 429
 430     Collection<?> convertPendingTransactionsToMessages(final int maxModificationsPerBatch) {
 431         final Collection<VersionedExternalizableMessage> messages = new ArrayList<>();
 432         for (ShardDataTreeCohort cohort : dataTree.getAndClearPendingTransactions()) {
 433             CohortEntry cohortEntry = cohortCache.remove(cohort.getIdentifier());
 434             if (cohortEntry == null) {
 435                 continue;
 436             }
 437
 438             final Deque<BatchedModifications> newMessages = new ArrayDeque<>();
 439             cohortEntry.getDataTreeModification().applyToCursor(new AbstractBatchedModificationsCursor() {
 440                 @Override
 441                 protected BatchedModifications getModifications() {
 442                     final BatchedModifications lastBatch = newMessages.peekLast();
 443
 444                     if (lastBatch != null && lastBatch.getModifications().size() >= maxModificationsPerBatch) {
 445                         return lastBatch;
 446                     }
 447
 448                     // Allocate a new message
 449                     final BatchedModifications ret = new BatchedModifications(cohortEntry.getTransactionId(),
 450                         cohortEntry.getClientVersion());
 451                     newMessages.add(ret);
 452                     return ret;
 453                 }
 454             });
 455
 456             final BatchedModifications last = newMessages.peekLast();
 457             if (last != null) {
 458                 final boolean immediate = cohortEntry.isDoImmediateCommit();
 459                 last.setDoCommitOnReady(immediate);
 460                 last.setReady(cohortEntry.getParticipatingShardNames());
 461                 last.setTotalMessagesSent(newMessages.size());
 462
 463                 messages.addAll(newMessages);
 464
 465                 if (!immediate) {
 466                     switch (cohort.getState()) {
 467                         case CAN_COMMIT_COMPLETE:
 468                         case CAN_COMMIT_PENDING:
 469                             messages.add(new CanCommitTransaction(cohortEntry.getTransactionId(),
 470                                 cohortEntry.getClientVersion()));
 471                             break;
 472                         case PRE_COMMIT_COMPLETE:
 473                         case PRE_COMMIT_PENDING:
 474                             messages.add(new CommitTransaction(cohortEntry.getTransactionId(),
 475                                 cohortEntry.getClientVersion()));
 476                             break;
 477                         default:
 478                             break;
 479                     }
 480                 }
 481             }
 482         }
 483
 484         return messages;
 485     }
 486
 487     @VisibleForTesting
 488     void setCohortDecorator(final CohortDecorator cohortDecorator) {
 489         this.cohortDecorator = cohortDecorator;
 490     }
 491 }