2 * Copyright (c) 2014 Cisco 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.md.sal.dom.broker.impl;
10 import com.google.common.base.Optional;
11 import com.google.common.base.Preconditions;
12 import com.google.common.base.Verify;
13 import com.google.common.util.concurrent.CheckedFuture;
14 import com.google.common.util.concurrent.FutureCallback;
15 import com.google.common.util.concurrent.Futures;
16 import com.google.common.util.concurrent.ListenableFuture;
17 import java.util.AbstractMap.SimpleImmutableEntry;
18 import java.util.Map.Entry;
19 import java.util.concurrent.CancellationException;
20 import java.util.concurrent.atomic.AtomicReferenceFieldUpdater;
21 import javax.annotation.Nonnull;
22 import javax.annotation.concurrent.GuardedBy;
23 import org.opendaylight.controller.md.sal.common.api.TransactionStatus;
24 import org.opendaylight.controller.md.sal.common.api.data.AsyncTransaction;
25 import org.opendaylight.controller.md.sal.common.api.data.LogicalDatastoreType;
26 import org.opendaylight.controller.md.sal.common.api.data.ReadFailedException;
27 import org.opendaylight.controller.md.sal.common.api.data.TransactionChain;
28 import org.opendaylight.controller.md.sal.common.api.data.TransactionChainListener;
29 import org.opendaylight.controller.md.sal.common.api.data.TransactionCommitFailedException;
30 import org.opendaylight.controller.md.sal.dom.api.DOMDataBroker;
31 import org.opendaylight.controller.md.sal.dom.api.DOMDataReadOnlyTransaction;
32 import org.opendaylight.controller.md.sal.dom.api.DOMDataReadWriteTransaction;
33 import org.opendaylight.controller.md.sal.dom.api.DOMDataWriteTransaction;
34 import org.opendaylight.controller.md.sal.dom.api.DOMTransactionChain;
35 import org.opendaylight.controller.md.sal.dom.spi.ForwardingDOMDataReadWriteTransaction;
36 import org.opendaylight.yangtools.yang.common.RpcResult;
37 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
38 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
39 import org.slf4j.Logger;
40 import org.slf4j.LoggerFactory;
43 * An implementation of {@link DOMTransactionChain}, which has a very specific
44 * behavior, which some users may find surprising. If keeps the general
45 * intent of the contract, but it makes sure there are never more than two
46 * transactions allocated at any given time: one of them is being committed,
47 * and while that is happening, the other one acts as the scratch pad. Once
48 * the committing transaction completes successfully, the scratch transaction
49 * is enqueued as soon as it is ready.
51 * This mode of operation means that there is no inherent isolation between
52 * the front-end transactions and transactions cannot be reasonably cancelled.
54 * It furthermore means that the transactions returned by {@link #newReadOnlyTransaction()}
55 * counts as an outstanding transaction and the user may not allocate multiple
56 * read-only transactions at the same time.
58 public final class PingPongTransactionChain implements DOMTransactionChain {
59 private static final Logger LOG = LoggerFactory.getLogger(PingPongTransactionChain.class);
60 private final TransactionChainListener listener;
61 private final DOMTransactionChain delegate;
64 private boolean failed;
66 private PingPongTransaction shutdownTx;
68 private Entry<PingPongTransaction, Throwable> deadTx;
71 * This updater is used to manipulate the "ready" transaction. We perform only atomic
74 private static final AtomicReferenceFieldUpdater<PingPongTransactionChain, PingPongTransaction> READY_UPDATER =
75 AtomicReferenceFieldUpdater.newUpdater(PingPongTransactionChain.class, PingPongTransaction.class, "readyTx");
76 private volatile PingPongTransaction readyTx;
79 * This updater is used to manipulate the "locked" transaction. A locked transaction
80 * means we know that the user still holds a transaction and should at some point call
81 * us. We perform on compare-and-swap to ensure we properly detect when a user is
82 * attempting to allocated multiple transactions concurrently.
84 private static final AtomicReferenceFieldUpdater<PingPongTransactionChain, PingPongTransaction> LOCKED_UPDATER =
85 AtomicReferenceFieldUpdater.newUpdater(PingPongTransactionChain.class, PingPongTransaction.class, "lockedTx");
86 private volatile PingPongTransaction lockedTx;
89 * This updater is used to manipulate the "inflight" transaction. There can be at most
90 * one of these at any given time. We perform only compare-and-swap on these.
92 private static final AtomicReferenceFieldUpdater<PingPongTransactionChain, PingPongTransaction> INFLIGHT_UPDATER =
93 AtomicReferenceFieldUpdater.newUpdater(PingPongTransactionChain.class, PingPongTransaction.class, "inflightTx");
94 private volatile PingPongTransaction inflightTx;
96 PingPongTransactionChain(final DOMDataBroker broker, final TransactionChainListener listener) {
97 this.listener = Preconditions.checkNotNull(listener);
98 this.delegate = broker.createTransactionChain(new TransactionChainListener() {
100 public void onTransactionChainFailed(final TransactionChain<?, ?> chain,
101 final AsyncTransaction<?, ?> transaction, final Throwable cause) {
102 LOG.debug("Transaction chain {} reported failure in {}", chain, transaction, cause);
103 delegateFailed(chain, cause);
107 public void onTransactionChainSuccessful(final TransactionChain<?, ?> chain) {
108 delegateSuccessful(chain);
113 void delegateSuccessful(final TransactionChain<?, ?> chain) {
114 final Entry<PingPongTransaction, Throwable> canceled;
115 synchronized (this) {
116 // This looks weird, but we need not hold the lock while invoking callbacks
120 if (canceled == null) {
121 listener.onTransactionChainSuccessful(this);
125 // Backend shutdown successful, but we have a batch of transactions we have to report as dead due to the
126 // user calling cancel().
127 final PingPongTransaction tx = canceled.getKey();
128 final Throwable cause = canceled.getValue();
129 LOG.debug("Transaction chain {} successful, failing cancelled transaction {}", chain, tx, cause);
131 listener.onTransactionChainFailed(this, tx.getFrontendTransaction(), cause);
135 void delegateFailed(final TransactionChain<?, ?> chain, final Throwable cause) {
137 final DOMDataReadWriteTransaction frontend;
138 final PingPongTransaction tx = inflightTx;
140 LOG.warn("Transaction chain {} failed with no pending transactions", chain);
143 frontend = tx.getFrontendTransaction();
146 listener.onTransactionChainFailed(this, frontend, cause);
148 synchronized (this) {
152 * If we do not have a locked transaction, we need to ensure that
153 * the backend transaction is cancelled. Otherwise we can defer
154 * until the user calls us.
156 if (lockedTx == null) {
162 private synchronized PingPongTransaction slowAllocateTransaction() {
163 Preconditions.checkState(shutdownTx == null, "Transaction chain %s has been shut down", this);
165 if (deadTx != null) {
166 throw new IllegalStateException(String.format(
167 "Transaction chain %s has failed due to transaction %s being canceled", this, deadTx.getKey()),
171 final DOMDataReadWriteTransaction delegateTx = delegate.newReadWriteTransaction();
172 final PingPongTransaction newTx = new PingPongTransaction(delegateTx);
174 if (!LOCKED_UPDATER.compareAndSet(this, null, newTx)) {
176 throw new IllegalStateException(String.format("New transaction %s raced with transaction %s", newTx, lockedTx));
182 private PingPongTransaction allocateTransaction() {
183 // Step 1: acquire current state
184 final PingPongTransaction oldTx = READY_UPDATER.getAndSet(this, null);
186 // Slow path: allocate a delegate transaction
188 return slowAllocateTransaction();
191 // Fast path: reuse current transaction. We will check failures and similar on submit().
192 if (!LOCKED_UPDATER.compareAndSet(this, null, oldTx)) {
193 // Ouch. Delegate chain has not detected a duplicate transaction allocation. This is the best we can do.
194 oldTx.getTransaction().cancel();
195 throw new IllegalStateException(String.format("Reusable transaction %s raced with transaction %s", oldTx, lockedTx));
202 * This forces allocateTransaction() on a slow path, which has to happen after
203 * this method has completed executing. Also inflightTx may be updated outside
204 * the lock, hence we need to re-check.
207 private void processIfReady() {
208 if (inflightTx == null) {
209 final PingPongTransaction tx = READY_UPDATER.getAndSet(this, null);
211 processTransaction(tx);
217 * Process a ready transaction. The caller needs to ensure that
218 * each transaction is seen only once by this method.
220 * @param tx Transaction which needs processing.
223 private void processTransaction(@Nonnull final PingPongTransaction tx) {
225 LOG.debug("Cancelling transaction {}", tx);
226 tx.getTransaction().cancel();
230 LOG.debug("Submitting transaction {}", tx);
231 if (!INFLIGHT_UPDATER.compareAndSet(this, null, tx)) {
232 LOG.warn("Submitting transaction {} while {} is still running", tx, inflightTx);
235 Futures.addCallback(tx.getTransaction().submit(), new FutureCallback<Void>() {
237 public void onSuccess(final Void result) {
238 transactionSuccessful(tx, result);
242 public void onFailure(final Throwable t) {
243 transactionFailed(tx, t);
249 * We got invoked from the data store thread. We need to do two things:
250 * 1) release the in-flight transaction
251 * 2) process the potential next transaction
253 * We have to perform 2) under lock. We could perform 1) without locking, but that means the CAS result may
254 * not be accurate, as a user thread may submit the ready transaction before we acquire the lock -- and checking
255 * for next transaction is not enough, as that may have also be allocated (as a result of a quick
256 * submit/allocate/submit between 1) and 2)). Hence we'd end up doing the following:
257 * 1) CAS of inflightTx
259 * 3) volatile read of inflightTx
261 * Rather than doing that, we keep this method synchronized, hence performing only:
263 * 2) CAS of inflightTx
265 * Since the user thread is barred from submitting the transaction (in processIfReady), we can then proceed with
266 * the knowledge that inflightTx is null -- processTransaction() will still do a CAS, but that is only for
269 private synchronized void processNextTransaction(final PingPongTransaction tx) {
270 final boolean success = INFLIGHT_UPDATER.compareAndSet(this, tx, null);
271 Preconditions.checkState(success, "Completed transaction %s while %s was submitted", tx, inflightTx);
273 final PingPongTransaction nextTx = READY_UPDATER.getAndSet(this, null);
274 if (nextTx != null) {
275 processTransaction(nextTx);
276 } else if (shutdownTx != null) {
277 processTransaction(shutdownTx);
283 void transactionSuccessful(final PingPongTransaction tx, final Void result) {
284 LOG.debug("Transaction {} completed successfully", tx);
286 tx.onSuccess(result);
287 processNextTransaction(tx);
290 void transactionFailed(final PingPongTransaction tx, final Throwable t) {
291 LOG.debug("Transaction {} failed", tx, t);
294 processNextTransaction(tx);
297 void readyTransaction(@Nonnull final PingPongTransaction tx) {
298 // First mark the transaction as not locked.
299 final boolean lockedMatch = LOCKED_UPDATER.compareAndSet(this, tx, null);
300 Preconditions.checkState(lockedMatch, "Attempted to submit transaction %s while we have %s", tx, lockedTx);
301 LOG.debug("Transaction {} unlocked", tx);
304 * The transaction is ready. It will then be picked up by either next allocation,
305 * or a background transaction completion callback.
307 final boolean success = READY_UPDATER.compareAndSet(this, null, tx);
308 Preconditions.checkState(success, "Transaction %s collided on ready state", tx, readyTx);
309 LOG.debug("Transaction {} readied", tx);
312 * We do not see a transaction being in-flight, so we need to take care of dispatching
313 * the transaction to the backend. We are in the ready case, we cannot short-cut
314 * the checking of readyTx, as an in-flight transaction may have completed between us
315 * setting the field above and us checking.
317 if (inflightTx == null) {
318 synchronized (this) {
325 * Transaction cancellation is a heavyweight operation. We only support cancelation of a locked transaction
326 * and return false for everything else. Cancelling such a transaction will result in all transactions in the
327 * batch to be cancelled.
329 * @param tx Backend shared transaction
331 * @param isOpen indicator whether the transaction was already closed
332 * @return True if cancellation succeeded, false otherwise
334 synchronized void cancelTransaction(final PingPongTransaction tx, final DOMDataReadWriteTransaction frontendTx) {
335 // Attempt to unlock the operation.
336 final boolean lockedMatch = LOCKED_UPDATER.compareAndSet(this, tx, null);
337 Verify.verify(lockedMatch, "Cancelling transaction {} collided with locked transaction {}", tx, lockedTx);
339 // Cancel the backend transaction, so we do not end up leaking it.
340 final boolean backendCancelled = tx.getTransaction().cancel();
343 // The transaction has failed, this is probably the user just clearing up the transaction they had. We have
344 // already cancelled the transaction anyway,
346 } else if (!backendCancelled) {
347 LOG.warn("Backend transaction cannot be cancelled during cancellation of {}, attempting to continue", tx);
350 // We have dealt with canceling the backend transaction and have unlocked the transaction. Since we are still
351 // inside the synchronized block, any allocations are blocking on the slow path. Now we have to decide the fate
352 // of this transaction chain.
354 // If there are no other frontend transactions in this batch we are aligned with backend state and we can
355 // continue processing.
356 if (frontendTx.equals(tx.getFrontendTransaction())) {
357 LOG.debug("Cancelled transaction {} was head of the batch, resuming processing", tx);
361 // There are multiple frontend transactions in this batch. We have to report them as failed, which dooms this
362 // transaction chain, too. Since we just came off of a locked transaction, we do not have a ready transaction
363 // at the moment, but there may be some transaction in-flight. So we proceed to shutdown the backend chain
364 // and mark the fact that we should be turning its completion into a failure.
365 deadTx = new SimpleImmutableEntry<>(tx,
366 new CancellationException("Transaction " + frontendTx + " canceled").fillInStackTrace());
371 public synchronized void close() {
372 final PingPongTransaction notLocked = lockedTx;
373 Preconditions.checkState(notLocked == null, "Attempted to close chain with outstanding transaction %s", notLocked);
375 // This is not reliable, but if we observe it to be null and the process has already completed,
376 // the backend transaction chain will throw the appropriate error.
377 Preconditions.checkState(shutdownTx == null, "Attempted to close an already-closed chain");
379 // This may be a reaction to our failure callback, in that case the backend is already shutdown
380 if (deadTx != null) {
381 LOG.debug("Delegate {} is already closed due to failure {}", delegate, deadTx);
385 // Force allocations on slow path, picking up a potentially-outstanding transaction
386 final PingPongTransaction tx = READY_UPDATER.getAndSet(this, null);
389 // We have one more transaction, which needs to be processed somewhere. If we do not
390 // a transaction in-flight, we need to push it down ourselves.
391 // If there is an in-flight transaction we will schedule this last one into a dedicated
392 // slot. Allocation slow path will check its presence and fail, the in-flight path will
393 // pick it up, submit and immediately close the chain.
394 if (inflightTx == null) {
395 processTransaction(tx);
401 // Nothing outstanding, we can safely shutdown
407 public DOMDataReadOnlyTransaction newReadOnlyTransaction() {
408 final PingPongTransaction tx = allocateTransaction();
410 return new DOMDataReadOnlyTransaction() {
412 public CheckedFuture<Optional<NormalizedNode<?, ?>>, ReadFailedException> read(final LogicalDatastoreType store,
413 final YangInstanceIdentifier path) {
414 return tx.getTransaction().read(store, path);
418 public CheckedFuture<Boolean, ReadFailedException> exists(final LogicalDatastoreType store,
419 final YangInstanceIdentifier path) {
420 return tx.getTransaction().exists(store, path);
424 public Object getIdentifier() {
425 return tx.getTransaction().getIdentifier();
429 public void close() {
430 readyTransaction(tx);
436 public DOMDataReadWriteTransaction newReadWriteTransaction() {
437 final PingPongTransaction tx = allocateTransaction();
438 final DOMDataReadWriteTransaction ret = new ForwardingDOMDataReadWriteTransaction() {
439 private boolean isOpen = true;
442 protected DOMDataReadWriteTransaction delegate() {
443 return tx.getTransaction();
447 public CheckedFuture<Void, TransactionCommitFailedException> submit() {
448 readyTransaction(tx);
450 return tx.getSubmitFuture();
455 public ListenableFuture<RpcResult<TransactionStatus>> commit() {
456 readyTransaction(tx);
458 return tx.getCommitFuture();
462 public boolean cancel() {
464 cancelTransaction(tx, this);
473 tx.recordFrontendTransaction(ret);
478 public DOMDataWriteTransaction newWriteOnlyTransaction() {
479 return newReadWriteTransaction();