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.util.concurrent.CheckedFuture;
13 import com.google.common.util.concurrent.FutureCallback;
14 import com.google.common.util.concurrent.Futures;
15 import com.google.common.util.concurrent.ListenableFuture;
16 import java.util.concurrent.atomic.AtomicReferenceFieldUpdater;
17 import javax.annotation.Nonnull;
18 import javax.annotation.concurrent.GuardedBy;
19 import org.opendaylight.controller.md.sal.common.api.TransactionStatus;
20 import org.opendaylight.controller.md.sal.common.api.data.AsyncTransaction;
21 import org.opendaylight.controller.md.sal.common.api.data.LogicalDatastoreType;
22 import org.opendaylight.controller.md.sal.common.api.data.ReadFailedException;
23 import org.opendaylight.controller.md.sal.common.api.data.TransactionChain;
24 import org.opendaylight.controller.md.sal.common.api.data.TransactionChainListener;
25 import org.opendaylight.controller.md.sal.common.api.data.TransactionCommitFailedException;
26 import org.opendaylight.controller.md.sal.dom.api.DOMDataBroker;
27 import org.opendaylight.controller.md.sal.dom.api.DOMDataReadOnlyTransaction;
28 import org.opendaylight.controller.md.sal.dom.api.DOMDataReadWriteTransaction;
29 import org.opendaylight.controller.md.sal.dom.api.DOMDataWriteTransaction;
30 import org.opendaylight.controller.md.sal.dom.api.DOMTransactionChain;
31 import org.opendaylight.controller.md.sal.dom.spi.ForwardingDOMDataReadWriteTransaction;
32 import org.opendaylight.yangtools.yang.common.RpcResult;
33 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
34 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
35 import org.slf4j.Logger;
36 import org.slf4j.LoggerFactory;
39 * An implementation of {@link DOMTransactionChain}, which has a very specific
40 * behavior, which some users may find surprising. If keeps the general
41 * intent of the contract, but it makes sure there are never more than two
42 * transactions allocated at any given time: one of them is being committed,
43 * and while that is happening, the other one acts as the scratch pad. Once
44 * the committing transaction completes successfully, the scratch transaction
45 * is enqueued as soon as it is ready.
47 * This mode of operation means that there is no inherent isolation between
48 * the front-end transactions and transactions cannot be reasonably cancelled.
50 * It furthermore means that the transactions returned by {@link #newReadOnlyTransaction()}
51 * counts as an outstanding transaction and the user may not allocate multiple
52 * read-only transactions at the same time.
54 public final class PingPongTransactionChain implements DOMTransactionChain {
55 private static final Logger LOG = LoggerFactory.getLogger(PingPongTransactionChain.class);
56 private final DOMTransactionChain delegate;
59 private boolean failed;
61 private PingPongTransaction shutdownTx;
64 * This updater is used to manipulate the "ready" transaction. We perform only atomic
67 private static final AtomicReferenceFieldUpdater<PingPongTransactionChain, PingPongTransaction> READY_UPDATER =
68 AtomicReferenceFieldUpdater.newUpdater(PingPongTransactionChain.class, PingPongTransaction.class, "readyTx");
69 private volatile PingPongTransaction readyTx;
72 * This updater is used to manipulate the "locked" transaction. A locked transaction
73 * means we know that the user still holds a transaction and should at some point call
74 * us. We perform on compare-and-swap to ensure we properly detect when a user is
75 * attempting to allocated multiple transactions concurrently.
77 private static final AtomicReferenceFieldUpdater<PingPongTransactionChain, PingPongTransaction> LOCKED_UPDATER =
78 AtomicReferenceFieldUpdater.newUpdater(PingPongTransactionChain.class, PingPongTransaction.class, "lockedTx");
79 private volatile PingPongTransaction lockedTx;
82 * This updater is used to manipulate the "inflight" transaction. There can be at most
83 * one of these at any given time. We perform only compare-and-swap on these.
85 private static final AtomicReferenceFieldUpdater<PingPongTransactionChain, PingPongTransaction> INFLIGHT_UPDATER =
86 AtomicReferenceFieldUpdater.newUpdater(PingPongTransactionChain.class, PingPongTransaction.class, "inflightTx");
87 private volatile PingPongTransaction inflightTx;
89 PingPongTransactionChain(final DOMDataBroker broker, final TransactionChainListener listener) {
90 this.delegate = broker.createTransactionChain(new TransactionChainListener() {
92 public void onTransactionChainFailed(final TransactionChain<?, ?> chain, final AsyncTransaction<?, ?> transaction, final Throwable cause) {
93 LOG.debug("Delegate chain {} reported failure in {}", chain, transaction, cause);
95 final DOMDataReadWriteTransaction frontend;
96 final PingPongTransaction tx = inflightTx;
98 LOG.warn("Transaction chain {} failed with no pending transactions", chain);
101 frontend = tx.getFrontendTransaction();
104 listener.onTransactionChainFailed(PingPongTransactionChain.this, frontend, cause);
109 public void onTransactionChainSuccessful(final TransactionChain<?, ?> chain) {
110 listener.onTransactionChainSuccessful(PingPongTransactionChain.this);
115 private synchronized void delegateFailed() {
119 * If we do not have a locked transaction, we need to ensure that
120 * the backend transaction is cancelled. Otherwise we can defer
121 * until the user calls us.
123 if (lockedTx == null) {
128 private synchronized PingPongTransaction slowAllocateTransaction() {
129 Preconditions.checkState(shutdownTx == null, "Transaction chain %s has been shut down", this);
131 final DOMDataReadWriteTransaction delegateTx = delegate.newReadWriteTransaction();
132 final PingPongTransaction newTx = new PingPongTransaction(delegateTx);
134 if (!LOCKED_UPDATER.compareAndSet(this, null, newTx)) {
136 throw new IllegalStateException(String.format("New transaction %s raced with transacion %s", newTx, lockedTx));
142 private PingPongTransaction allocateTransaction() {
143 // Step 1: acquire current state
144 final PingPongTransaction oldTx = READY_UPDATER.getAndSet(this, null);
146 // Slow path: allocate a delegate transaction
148 return slowAllocateTransaction();
151 // Fast path: reuse current transaction. We will check
152 // failures and similar on submit().
153 if (!LOCKED_UPDATER.compareAndSet(this, null, oldTx)) {
154 // Ouch. Delegate chain has not detected a duplicate
155 // transaction allocation. This is the best we can do.
156 oldTx.getTransaction().cancel();
157 throw new IllegalStateException(String.format("Reusable transaction %s raced with transaction %s", oldTx, lockedTx));
164 * This forces allocateTransaction() on a slow path, which has to happen after
165 * this method has completed executing. Also inflightTx may be updated outside
166 * the lock, hence we need to re-check.
169 private void processIfReady() {
170 if (inflightTx == null) {
171 final PingPongTransaction tx = READY_UPDATER.getAndSet(this, null);
173 processTransaction(tx);
179 * Process a ready transaction. The caller needs to ensure that
180 * each transaction is seen only once by this method.
182 * @param tx Transaction which needs processing.
185 private void processTransaction(@Nonnull final PingPongTransaction tx) {
187 LOG.debug("Cancelling transaction {}", tx);
188 tx.getTransaction().cancel();
192 LOG.debug("Submitting transaction {}", tx);
193 if (!INFLIGHT_UPDATER.compareAndSet(this, null, tx)) {
194 LOG.warn("Submitting transaction {} while {} is still running", tx, inflightTx);
197 Futures.addCallback(tx.getTransaction().submit(), new FutureCallback<Void>() {
199 public void onSuccess(final Void result) {
200 transactionSuccessful(tx, result);
204 public void onFailure(final Throwable t) {
205 transactionFailed(tx, t);
211 * We got invoked from the data store thread. We need to do two things:
212 * 1) release the in-flight transaction
213 * 2) process the potential next transaction
215 * We have to perform 2) under lock. We could perform 1) without locking, but that means the CAS result may
216 * not be accurate, as a user thread may submit the ready transaction before we acquire the lock -- and checking
217 * for next transaction is not enough, as that may have also be allocated (as a result of a quick
218 * submit/allocate/submit between 1) and 2)). Hence we'd end up doing the following:
219 * 1) CAS of inflightTx
221 * 3) volatile read of inflightTx
223 * Rather than doing that, we keep this method synchronized, hence performing only:
225 * 2) CAS of inflightTx
227 * Since the user thread is barred from submitting the transaction (in processIfReady), we can then proceed with
228 * the knowledge that inflightTx is null -- processTransaction() will still do a CAS, but that is only for
231 private synchronized void processNextTransaction(final PingPongTransaction tx) {
232 final boolean success = INFLIGHT_UPDATER.compareAndSet(this, tx, null);
233 Preconditions.checkState(success, "Completed transaction %s while %s was submitted", tx, inflightTx);
235 final PingPongTransaction nextTx = READY_UPDATER.getAndSet(this, null);
236 if (nextTx != null) {
237 processTransaction(nextTx);
238 } else if (shutdownTx != null) {
239 processTransaction(shutdownTx);
245 private void transactionSuccessful(final PingPongTransaction tx, final Void result) {
246 LOG.debug("Transaction {} completed successfully", tx);
248 tx.onSuccess(result);
249 processNextTransaction(tx);
252 private void transactionFailed(final PingPongTransaction tx, final Throwable t) {
253 LOG.debug("Transaction {} failed", tx, t);
256 processNextTransaction(tx);
259 private void readyTransaction(@Nonnull final PingPongTransaction tx) {
260 // First mark the transaction as not locked.
261 final boolean lockedMatch = LOCKED_UPDATER.compareAndSet(this, tx, null);
262 Preconditions.checkState(lockedMatch, "Attempted to submit transaction %s while we have %s", tx, lockedTx);
263 LOG.debug("Transaction {} unlocked", tx);
266 * The transaction is ready. It will then be picked up by either next allocation,
267 * or a background transaction completion callback.
269 final boolean success = READY_UPDATER.compareAndSet(this, null, tx);
270 Preconditions.checkState(success, "Transaction %s collided on ready state", tx, readyTx);
271 LOG.debug("Transaction {} readied", tx);
274 * We do not see a transaction being in-flight, so we need to take care of dispatching
275 * the transaction to the backend. We are in the ready case, we cannot short-cut
276 * the checking of readyTx, as an in-flight transaction may have completed between us
277 * setting the field above and us checking.
279 if (inflightTx == null) {
280 synchronized (this) {
287 public synchronized void close() {
288 final PingPongTransaction notLocked = lockedTx;
289 Preconditions.checkState(notLocked == null, "Attempted to close chain with outstanding transaction %s", notLocked);
291 // This is not reliable, but if we observe it to be null and the process has already completed,
292 // the backend transaction chain will throw the appropriate error.
293 Preconditions.checkState(shutdownTx == null, "Attempted to close an already-closed chain");
295 // Force allocations on slow path, picking up a potentially-outstanding transaction
296 final PingPongTransaction tx = READY_UPDATER.getAndSet(this, null);
299 // We have one more transaction, which needs to be processed somewhere. If we do not
300 // a transaction in-flight, we need to push it down ourselves.
301 // If there is an in-flight transaction we will schedule this last one into a dedicated
302 // slot. Allocation slow path will check its presence and fail, the in-flight path will
303 // pick it up, submit and immediately close the chain.
304 if (inflightTx == null) {
305 processTransaction(tx);
311 // Nothing outstanding, we can safely shutdown
317 public DOMDataReadOnlyTransaction newReadOnlyTransaction() {
318 final PingPongTransaction tx = allocateTransaction();
320 return new DOMDataReadOnlyTransaction() {
322 public CheckedFuture<Optional<NormalizedNode<?, ?>>, ReadFailedException> read(final LogicalDatastoreType store,
323 final YangInstanceIdentifier path) {
324 return tx.getTransaction().read(store, path);
328 public CheckedFuture<Boolean, ReadFailedException> exists(final LogicalDatastoreType store,
329 final YangInstanceIdentifier path) {
330 return tx.getTransaction().exists(store, path);
334 public Object getIdentifier() {
335 return tx.getTransaction().getIdentifier();
339 public void close() {
340 readyTransaction(tx);
346 public DOMDataReadWriteTransaction newReadWriteTransaction() {
347 final PingPongTransaction tx = allocateTransaction();
348 final DOMDataReadWriteTransaction ret = new ForwardingDOMDataReadWriteTransaction() {
350 protected DOMDataReadWriteTransaction delegate() {
351 return tx.getTransaction();
355 public CheckedFuture<Void, TransactionCommitFailedException> submit() {
356 readyTransaction(tx);
357 return tx.getSubmitFuture();
361 public ListenableFuture<RpcResult<TransactionStatus>> commit() {
362 readyTransaction(tx);
363 return tx.getCommitFuture();
367 public boolean cancel() {
368 throw new UnsupportedOperationException("Transaction cancellation is not supported");
372 tx.recordFrontendTransaction(ret);
377 public DOMDataWriteTransaction newWriteOnlyTransaction() {
378 return newReadWriteTransaction();