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.mdsal.dom.spi;
10 import static com.google.common.base.Preconditions.checkState;
11 import static com.google.common.base.Verify.verify;
12 import static java.util.Objects.requireNonNull;
14 import com.google.common.util.concurrent.FluentFuture;
15 import com.google.common.util.concurrent.FutureCallback;
16 import com.google.common.util.concurrent.MoreExecutors;
17 import java.util.AbstractMap.SimpleImmutableEntry;
18 import java.util.Map.Entry;
19 import java.util.Optional;
20 import java.util.concurrent.CancellationException;
21 import java.util.concurrent.atomic.AtomicReferenceFieldUpdater;
22 import java.util.function.Function;
23 import org.checkerframework.checker.lock.qual.GuardedBy;
24 import org.checkerframework.checker.lock.qual.Holding;
25 import org.eclipse.jdt.annotation.NonNull;
26 import org.opendaylight.mdsal.common.api.CommitInfo;
27 import org.opendaylight.mdsal.common.api.LogicalDatastoreType;
28 import org.opendaylight.mdsal.dom.api.DOMDataTreeReadTransaction;
29 import org.opendaylight.mdsal.dom.api.DOMDataTreeReadWriteTransaction;
30 import org.opendaylight.mdsal.dom.api.DOMDataTreeTransaction;
31 import org.opendaylight.mdsal.dom.api.DOMDataTreeWriteTransaction;
32 import org.opendaylight.mdsal.dom.api.DOMTransactionChain;
33 import org.opendaylight.mdsal.dom.api.DOMTransactionChainListener;
34 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
35 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
36 import org.slf4j.Logger;
37 import org.slf4j.LoggerFactory;
40 * An implementation of {@link DOMTransactionChain}, which has a very specific behavior, which some users may find
41 * surprising. If keeps the general intent of the contract, but it makes sure there are never more than two transactions
42 * allocated at any given time: one of them is being committed, and while that is happening, the other one acts as
43 * a scratch pad. Once the committing transaction completes successfully, the scratch transaction is enqueued as soon as
47 * This mode of operation means that there is no inherent isolation between the front-end transactions and transactions
48 * cannot be reasonably cancelled.
51 * It furthermore means that the transactions returned by {@link #newReadOnlyTransaction()} counts as an outstanding
52 * transaction and the user may not allocate multiple read-only transactions at the same time.
54 public final class PingPongTransactionChain implements DOMTransactionChain {
55 private static final Logger LOG = LoggerFactory.getLogger(PingPongTransactionChain.class);
57 private final DOMTransactionChainListener listener;
58 private final DOMTransactionChain delegate;
61 private boolean failed;
63 private PingPongTransaction shutdownTx;
65 private Entry<PingPongTransaction, Throwable> deadTx;
67 // This updater is used to manipulate the "ready" transaction. We perform only atomic get-and-set on it.
68 private static final AtomicReferenceFieldUpdater<PingPongTransactionChain, PingPongTransaction> READY_UPDATER =
69 AtomicReferenceFieldUpdater.newUpdater(PingPongTransactionChain.class, PingPongTransaction.class,
71 private volatile PingPongTransaction readyTx;
74 * This updater is used to manipulate the "locked" transaction. A locked transaction means we know that the user
75 * still holds a transaction and should at some point call us. We perform on compare-and-swap to ensure we properly
76 * detect when a user is attempting to allocated multiple transactions concurrently.
78 private static final AtomicReferenceFieldUpdater<PingPongTransactionChain, PingPongTransaction> LOCKED_UPDATER =
79 AtomicReferenceFieldUpdater.newUpdater(PingPongTransactionChain.class, PingPongTransaction.class,
81 private volatile PingPongTransaction lockedTx;
84 * This updater is used to manipulate the "inflight" transaction. There can be at most one of these at any given
85 * time. We perform only compare-and-swap on these.
87 private static final AtomicReferenceFieldUpdater<PingPongTransactionChain, PingPongTransaction> INFLIGHT_UPDATER =
88 AtomicReferenceFieldUpdater.newUpdater(PingPongTransactionChain.class, PingPongTransaction.class,
90 private volatile PingPongTransaction inflightTx;
92 public PingPongTransactionChain(final Function<DOMTransactionChainListener, DOMTransactionChain> delegateFactory,
93 final DOMTransactionChainListener listener) {
94 this.listener = requireNonNull(listener);
95 delegate = delegateFactory.apply(new DOMTransactionChainListener() {
97 public void onTransactionChainFailed(final DOMTransactionChain chain,
98 final DOMDataTreeTransaction transaction, final Throwable cause) {
99 LOG.debug("Transaction chain {} reported failure in {}", chain, transaction, cause);
100 delegateFailed(chain, cause);
104 public void onTransactionChainSuccessful(final DOMTransactionChain chain) {
105 delegateSuccessful(chain);
110 void delegateSuccessful(final DOMTransactionChain chain) {
111 final Entry<PingPongTransaction, Throwable> canceled;
112 synchronized (this) {
113 // This looks weird, but we need not hold the lock while invoking callbacks
117 if (canceled == null) {
118 listener.onTransactionChainSuccessful(this);
122 // Backend shutdown successful, but we have a batch of transactions we have to report as dead due to the
123 // user calling cancel().
124 final PingPongTransaction tx = canceled.getKey();
125 final Throwable cause = canceled.getValue();
126 LOG.debug("Transaction chain {} successful, failing cancelled transaction {}", chain, tx, cause);
128 listener.onTransactionChainFailed(this, tx.getFrontendTransaction(), cause);
132 void delegateFailed(final DOMTransactionChain chain, final Throwable cause) {
134 final DOMDataTreeReadWriteTransaction frontend;
135 final PingPongTransaction tx = inflightTx;
137 LOG.warn("Transaction chain {} failed with no pending transactions", chain);
140 frontend = tx.getFrontendTransaction();
143 listener.onTransactionChainFailed(this, frontend, cause);
145 synchronized (this) {
149 * If we do not have a locked transaction, we need to ensure that the backend transaction is cancelled.
150 * Otherwise we can defer until the user calls us.
152 if (lockedTx == null) {
158 private synchronized @NonNull PingPongTransaction slowAllocateTransaction() {
159 checkState(shutdownTx == null, "Transaction chain %s has been shut down", this);
161 if (deadTx != null) {
162 throw new IllegalStateException(String.format(
163 "Transaction chain %s has failed due to transaction %s being canceled", this, deadTx.getKey()),
167 final DOMDataTreeReadWriteTransaction delegateTx = delegate.newReadWriteTransaction();
168 final PingPongTransaction newTx = new PingPongTransaction(delegateTx);
170 if (!LOCKED_UPDATER.compareAndSet(this, null, newTx)) {
172 throw new IllegalStateException(
173 String.format("New transaction %s raced with transaction %s", newTx, lockedTx));
179 private @NonNull PingPongTransaction allocateTransaction() {
180 // Step 1: acquire current state
181 final PingPongTransaction oldTx = READY_UPDATER.getAndSet(this, null);
183 // Slow path: allocate a delegate transaction
185 return slowAllocateTransaction();
188 // Fast path: reuse current transaction. We will check failures and similar on commit().
189 if (!LOCKED_UPDATER.compareAndSet(this, null, oldTx)) {
190 // Ouch. Delegate chain has not detected a duplicate transaction allocation. This is the best we can do.
191 oldTx.getTransaction().cancel();
192 throw new IllegalStateException(String.format("Reusable transaction %s raced with transaction %s", oldTx,
200 * This forces allocateTransaction() on a slow path, which has to happen after this method has completed executing.
201 * Also inflightTx may be updated outside the lock, hence we need to re-check.
204 private void processIfReady() {
205 if (inflightTx == null) {
206 final PingPongTransaction tx = READY_UPDATER.getAndSet(this, null);
208 processTransaction(tx);
214 * Process a ready transaction. The caller needs to ensure that each transaction is seen only once by this method.
216 * @param tx Transaction which needs processing.
219 private void processTransaction(final @NonNull PingPongTransaction tx) {
221 LOG.debug("Cancelling transaction {}", tx);
222 tx.getTransaction().cancel();
226 LOG.debug("Submitting transaction {}", tx);
227 if (!INFLIGHT_UPDATER.compareAndSet(this, null, tx)) {
228 LOG.warn("Submitting transaction {} while {} is still running", tx, inflightTx);
231 tx.getTransaction().commit().addCallback(new FutureCallback<CommitInfo>() {
233 public void onSuccess(final CommitInfo result) {
234 transactionSuccessful(tx, result);
238 public void onFailure(final Throwable throwable) {
239 transactionFailed(tx, throwable);
241 }, MoreExecutors.directExecutor());
245 * We got invoked from the data store thread. We need to do two things:
246 * 1) release the in-flight transaction
247 * 2) process the potential next transaction
249 * We have to perform 2) under lock. We could perform 1) without locking, but that means the CAS result may
250 * not be accurate, as a user thread may submit the ready transaction before we acquire the lock -- and checking
251 * for next transaction is not enough, as that may have also be allocated (as a result of a quick
252 * submit/allocate/submit between 1) and 2)). Hence we'd end up doing the following:
253 * 1) CAS of inflightTx
255 * 3) volatile read of inflightTx
257 * Rather than doing that, we keep this method synchronized, hence performing only:
259 * 2) CAS of inflightTx
261 * Since the user thread is barred from submitting the transaction (in processIfReady), we can then proceed with
262 * the knowledge that inflightTx is null -- processTransaction() will still do a CAS, but that is only for
265 private synchronized void processNextTransaction(final PingPongTransaction tx) {
266 final boolean success = INFLIGHT_UPDATER.compareAndSet(this, tx, null);
267 checkState(success, "Completed transaction %s while %s was submitted", tx, inflightTx);
269 final PingPongTransaction nextTx = READY_UPDATER.getAndSet(this, null);
270 if (nextTx == null) {
271 final PingPongTransaction local = shutdownTx;
273 processTransaction(local);
278 processTransaction(nextTx);
282 void transactionSuccessful(final PingPongTransaction tx, final CommitInfo result) {
283 LOG.debug("Transaction {} completed successfully", tx);
285 tx.onSuccess(result);
286 processNextTransaction(tx);
289 void transactionFailed(final PingPongTransaction tx, final Throwable throwable) {
290 LOG.debug("Transaction {} failed", tx, throwable);
292 tx.onFailure(throwable);
293 processNextTransaction(tx);
296 void readyTransaction(final @NonNull PingPongTransaction tx) {
297 // First mark the transaction as not locked.
298 final boolean lockedMatch = LOCKED_UPDATER.compareAndSet(this, tx, null);
299 checkState(lockedMatch, "Attempted to submit transaction %s while we have %s", tx, lockedTx);
300 LOG.debug("Transaction {} unlocked", tx);
303 * The transaction is ready. It will then be picked up by either next allocation,
304 * or a background transaction completion callback.
306 final boolean success = READY_UPDATER.compareAndSet(this, null, tx);
307 checkState(success, "Transaction %s collided on ready state", tx, readyTx);
308 LOG.debug("Transaction {} readied", tx);
311 * We do not see a transaction being in-flight, so we need to take care of dispatching
312 * the transaction to the backend. We are in the ready case, we cannot short-cut
313 * the checking of readyTx, as an in-flight transaction may have completed between us
314 * setting the field above and us checking.
316 if (inflightTx == null) {
317 synchronized (this) {
324 * Transaction cancellation is a heavyweight operation. We only support cancelation of a locked transaction
325 * and return false for everything else. Cancelling such a transaction will result in all transactions in the
326 * batch to be cancelled.
328 * @param tx Backend shared transaction
329 * @param frontendTx transaction
330 * @param isOpen indicator whether the transaction was already closed
332 synchronized void cancelTransaction(final PingPongTransaction tx,
333 final DOMDataTreeReadWriteTransaction frontendTx) {
334 // Attempt to unlock the operation.
335 final boolean lockedMatch = LOCKED_UPDATER.compareAndSet(this, tx, null);
336 verify(lockedMatch, "Cancelling transaction %s collided with locked transaction %s", tx, lockedTx);
338 // Cancel the backend transaction, so we do not end up leaking it.
339 final boolean backendCancelled = tx.getTransaction().cancel();
342 // The transaction has failed, this is probably the user just clearing up the transaction they had. We have
343 // already cancelled the transaction anyway,
345 } else if (!backendCancelled) {
346 LOG.warn("Backend transaction cannot be cancelled during cancellation of {}, attempting to continue", tx);
349 // We have dealt with canceling the backend transaction and have unlocked the transaction. Since we are still
350 // inside the synchronized block, any allocations are blocking on the slow path. Now we have to decide the fate
351 // of this transaction chain.
353 // If there are no other frontend transactions in this batch we are aligned with backend state and we can
354 // continue processing.
355 if (frontendTx.equals(tx.getFrontendTransaction())) {
356 LOG.debug("Cancelled transaction {} was head of the batch, resuming processing", tx);
360 // There are multiple frontend transactions in this batch. We have to report them as failed, which dooms this
361 // transaction chain, too. Since we just came off of a locked transaction, we do not have a ready transaction
362 // at the moment, but there may be some transaction in-flight. So we proceed to shutdown the backend chain
363 // and mark the fact that we should be turning its completion into a failure.
364 deadTx = new SimpleImmutableEntry<>(tx, new CancellationException("Transaction " + frontendTx + " canceled")
365 .fillInStackTrace());
370 public synchronized void close() {
371 final PingPongTransaction notLocked = lockedTx;
372 checkState(notLocked == null, "Attempted to close chain with outstanding transaction %s", notLocked);
374 // This is not reliable, but if we observe it to be null and the process has already completed,
375 // the backend transaction chain will throw the appropriate error.
376 checkState(shutdownTx == null, "Attempted to close an already-closed chain");
378 // This may be a reaction to our failure callback, in that case the backend is already shutdown
379 if (deadTx != null) {
380 LOG.debug("Delegate {} is already closed due to failure {}", delegate, deadTx);
384 // Force allocations on slow path, picking up a potentially-outstanding transaction
385 final PingPongTransaction tx = READY_UPDATER.getAndSet(this, null);
388 // We have one more transaction, which needs to be processed somewhere. If we do not
389 // a transaction in-flight, we need to push it down ourselves.
390 // If there is an in-flight transaction we will schedule this last one into a dedicated
391 // slot. Allocation slow path will check its presence and fail, the in-flight path will
392 // pick it up, submit and immediately close the chain.
393 if (inflightTx == null) {
394 processTransaction(tx);
400 // Nothing outstanding, we can safely shutdown
406 public DOMDataTreeReadTransaction newReadOnlyTransaction() {
407 return new PingPongReadTransaction(allocateTransaction());
411 public DOMDataTreeReadWriteTransaction newReadWriteTransaction() {
412 final PingPongTransaction tx = allocateTransaction();
413 final DOMDataTreeReadWriteTransaction ret = new PingPongReadWriteTransaction(tx);
414 tx.recordFrontendTransaction(ret);
419 public DOMDataTreeWriteTransaction newWriteOnlyTransaction() {
420 return newReadWriteTransaction();
423 private final class PingPongReadTransaction implements DOMDataTreeReadTransaction {
424 private final @NonNull PingPongTransaction tx;
426 PingPongReadTransaction(final PingPongTransaction tx) {
427 this.tx = requireNonNull(tx);
431 public FluentFuture<Optional<NormalizedNode>> read(final LogicalDatastoreType store,
432 final YangInstanceIdentifier path) {
433 return tx.getTransaction().read(store, path);
437 public FluentFuture<Boolean> exists(final LogicalDatastoreType store, final YangInstanceIdentifier path) {
438 return tx.getTransaction().exists(store, path);
442 public Object getIdentifier() {
443 return tx.getTransaction().getIdentifier();
447 public void close() {
448 readyTransaction(tx);
452 private final class PingPongReadWriteTransaction extends ForwardingDOMDataReadWriteTransaction {
453 private final @NonNull PingPongTransaction tx;
455 private boolean isOpen = true;
457 PingPongReadWriteTransaction(final PingPongTransaction tx) {
458 this.tx = requireNonNull(tx);
462 public FluentFuture<? extends CommitInfo> commit() {
463 readyTransaction(tx);
465 return tx.getCommitFuture().transform(ignored -> CommitInfo.empty(), MoreExecutors.directExecutor());
469 public boolean cancel() {
471 cancelTransaction(tx, this);
480 protected DOMDataTreeReadWriteTransaction delegate() {
481 return tx.getTransaction();