1 /*
2 * Copyright (C) 2007 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14
15 package com.google.common.util.concurrent;
16
17 import static com.google.common.base.Preconditions.checkNotNull;
18
19 import com.google.common.annotations.GwtIncompatible;
20 import com.google.errorprone.annotations.concurrent.GuardedBy;
21 import java.util.concurrent.Executor;
22 import java.util.logging.Level;
23 import java.util.logging.Logger;
24 import javax.annotation.CheckForNull;
25
26 /**
27 * A support class for {@code ListenableFuture} implementations to manage their listeners. An
28 * instance contains a list of listeners, each with an associated {@code Executor}, and guarantees
29 * that every {@code Runnable} that is {@linkplain #add added} will be executed after {@link
30 * #execute()} is called. Any {@code Runnable} added after the call to {@code execute} is still
31 * guaranteed to execute. There is no guarantee, however, that listeners will be executed in the
32 * order that they are added.
33 *
34 * <p>Exceptions thrown by a listener will be propagated up to the executor. Any exception thrown
35 * during {@code Executor.execute} (e.g., a {@code RejectedExecutionException} or an exception
36 * thrown by {@linkplain MoreExecutors#directExecutor direct execution}) will be caught and logged.
37 *
38 * @author Nishant Thakkar
39 * @author Sven Mawson
40 * @since 1.0
41 */
42 @GwtIncompatible
43 @ElementTypesAreNonnullByDefault
44 public final class ExecutionList {
45 /** Logger to log exceptions caught when running runnables. */
46 private static final Logger log = Logger.getLogger(ExecutionList.class.getName());
47
48 /**
49 * The runnable, executor pairs to execute. This acts as a stack threaded through the {@link
50 * RunnableExecutorPair#next} field.
51 */
52 @GuardedBy("this")
53 @CheckForNull
54 private RunnableExecutorPair runnables;
55
56 @GuardedBy("this")
57 private boolean executed;
58
59 /** Creates a new, empty {@link ExecutionList}. */
60 public ExecutionList() {}
61
62 /**
63 * Adds the {@code Runnable} and accompanying {@code Executor} to the list of listeners to
64 * execute. If execution has already begun, the listener is executed immediately.
65 *
66 * <p>When selecting an executor, note that {@code directExecutor} is dangerous in some cases. See
67 * the discussion in the {@link ListenableFuture#addListener ListenableFuture.addListener}
68 * documentation.
69 */
70 public void add(Runnable runnable, Executor executor) {
71 // Fail fast on a null. We throw NPE here because the contract of Executor states that it throws
72 // NPE on null listener, so we propagate that contract up into the add method as well.
73 checkNotNull(runnable, "Runnable was null.");
74 checkNotNull(executor, "Executor was null.");
75
76 // Lock while we check state. We must maintain the lock while adding the new pair so that
77 // another thread can't run the list out from under us. We only add to the list if we have not
78 // yet started execution.
79 synchronized (this) {
80 if (!executed) {
81 runnables = new RunnableExecutorPair(runnable, executor, runnables);
82 return;
83 }
84 }
85 // Execute the runnable immediately. Because of scheduling this may end up getting called before
86 // some of the previously added runnables, but we're OK with that. If we want to change the
87 // contract to guarantee ordering among runnables we'd have to modify the logic here to allow
88 // it.
89 executeListener(runnable, executor);
90 }
91
92 /**
93 * Runs this execution list, executing all existing pairs in the order they were added. However,
94 * note that listeners added after this point may be executed before those previously added, and
95 * note that the execution order of all listeners is ultimately chosen by the implementations of
96 * the supplied executors.
97 *
98 * <p>This method is idempotent. Calling it several times in parallel is semantically equivalent
99 * to calling it exactly once.
100 *
101 * @since 10.0 (present in 1.0 as {@code run})
102 */
103 public void execute() {
104 // Lock while we update our state so the add method above will finish adding any listeners
105 // before we start to run them.
106 RunnableExecutorPair list;
107 synchronized (this) {
108 if (executed) {
109 return;
110 }
111 executed = true;
112 list = runnables;
113 runnables = null; // allow GC to free listeners even if this stays around for a while.
114 }
115 // If we succeeded then list holds all the runnables we to execute. The pairs in the stack are
116 // in the opposite order from how they were added so we need to reverse the list to fulfill our
117 // contract.
118 // This is somewhat annoying, but turns out to be very fast in practice. Alternatively, we could
119 // drop the contract on the method that enforces this queue like behavior since depending on it
120 // is likely to be a bug anyway.
121
122 // N.B. All writes to the list and the next pointers must have happened before the above
123 // synchronized block, so we can iterate the list without the lock held here.
124 RunnableExecutorPair reversedList = null;
125 while (list != null) {
126 RunnableExecutorPair tmp = list;
127 list = list.next;
128 tmp.next = reversedList;
129 reversedList = tmp;
130 }
131 while (reversedList != null) {
132 executeListener(reversedList.runnable, reversedList.executor);
133 reversedList = reversedList.next;
134 }
135 }
136
137 /**
138 * Submits the given runnable to the given {@link Executor} catching and logging all {@linkplain
139 * RuntimeException runtime exceptions} thrown by the executor.
140 */
141 private static void executeListener(Runnable runnable, Executor executor) {
142 try {
143 executor.execute(runnable);
144 } catch (RuntimeException e) {
145 // Log it and keep going -- bad runnable and/or executor. Don't punish the other runnables if
146 // we're given a bad one. We only catch RuntimeException because we want Errors to propagate
147 // up.
148 log.log(
149 Level.SEVERE,
150 "RuntimeException while executing runnable " + runnable + " with executor " + executor,
151 e);
152 }
153 }
154
155 private static final class RunnableExecutorPair {
156 final Runnable runnable;
157 final Executor executor;
158 @CheckForNull RunnableExecutorPair next;
159
160 RunnableExecutorPair(
161 Runnable runnable, Executor executor, @CheckForNull RunnableExecutorPair next) {
162 this.runnable = runnable;
163 this.executor = executor;
164 this.next = next;
165 }
166 }
167 }