001 /*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package com.google.common.util.concurrent;
018
019 import com.google.common.annotations.Beta;
020 import com.google.common.base.Preconditions;
021 import com.google.common.collect.Lists;
022
023 import java.util.Queue;
024 import java.util.concurrent.Executor;
025 import java.util.logging.Level;
026 import java.util.logging.Logger;
027
028 /**
029 * <p>A list of listeners, each with an associated {@code Executor}, that
030 * guarantees that every {@code Runnable} that is {@linkplain #add added} will
031 * be executed after {@link #execute()} is called. Any {@code Runnable} added
032 * after the call to {@code execute} is still guaranteed to execute. There is no
033 * guarantee, however, that listeners will be executed in the order that they
034 * are added.
035 *
036 * <p>Exceptions thrown by a listener will be propagated up to the executor.
037 * Any exception thrown during {@code Executor.execute} (e.g., a {@code
038 * RejectedExecutionException} or an exception thrown by {@linkplain
039 * MoreExecutors#sameThreadExecutor inline execution}) will be caught and
040 * logged.
041 *
042 * @author Nishant Thakkar
043 * @author Sven Mawson
044 * @since 1.0
045 */
046 public final class ExecutionList {
047
048 // Logger to log exceptions caught when running runnables.
049 private static final Logger log =
050 Logger.getLogger(ExecutionList.class.getName());
051
052 // The runnable,executor pairs to execute.
053 private final Queue<RunnableExecutorPair> runnables = Lists.newLinkedList();
054
055 // Boolean we use mark when execution has started. Only accessed from within
056 // synchronized blocks.
057 private boolean executed = false;
058
059 /** Creates a new, empty {@link ExecutionList}. */
060 public ExecutionList() {
061 }
062
063 /**
064 * Adds the {@code Runnable} and accompanying {@code Executor} to the list of
065 * listeners to execute. If execution has already begun, the listener is
066 * executed immediately.
067 *
068 * <p>Note: For fast, lightweight listeners that would be safe to execute in
069 * any thread, consider {@link MoreExecutors#sameThreadExecutor}. For heavier
070 * listeners, {@code sameThreadExecutor()} carries some caveats: First, the
071 * thread that the listener runs in depends on whether the {@code Future} is
072 * done at the time it is added. In particular, if added late, listeners will
073 * run in the thread that called {@code add}. Second, listeners may run in an
074 * internal thread of the system responsible for the input {@code Future},
075 * such as an RPC network thread. Finally, during the execution of a {@link
076 * MoreExecutors#sameThreadExecutor sameThreadExecutor} listener, all other
077 * registered but unexecuted listeners are prevented from running, even if
078 * those listeners are to run in other executors.
079 */
080 public void add(Runnable runnable, Executor executor) {
081 // Fail fast on a null. We throw NPE here because the contract of
082 // Executor states that it throws NPE on null listener, so we propagate
083 // that contract up into the add method as well.
084 Preconditions.checkNotNull(runnable, "Runnable was null.");
085 Preconditions.checkNotNull(executor, "Executor was null.");
086
087 boolean executeImmediate = false;
088
089 // Lock while we check state. We must maintain the lock while adding the
090 // new pair so that another thread can't run the list out from under us.
091 // We only add to the list if we have not yet started execution.
092 synchronized (runnables) {
093 if (!executed) {
094 runnables.add(new RunnableExecutorPair(runnable, executor));
095 } else {
096 executeImmediate = true;
097 }
098 }
099
100 // Execute the runnable immediately. Because of scheduling this may end up
101 // getting called before some of the previously added runnables, but we're
102 // OK with that. If we want to change the contract to guarantee ordering
103 // among runnables we'd have to modify the logic here to allow it.
104 if (executeImmediate) {
105 new RunnableExecutorPair(runnable, executor).execute();
106 }
107 }
108
109 /**
110 * Equivalent to {@link #execute}.
111 *
112 * @deprecated Use {@link #execute}. This method will be removed in Guava
113 * release 11.
114 */
115 @Beta @Deprecated
116 public
117 void run() {
118 execute();
119 }
120
121 /**
122 * Runs this execution list, executing all existing pairs in the order they
123 * were added. However, note that listeners added after this point may be
124 * executed before those previously added, and note that the execution order
125 * of all listeners is ultimately chosen by the implementations of the
126 * supplied executors.
127 *
128 * <p>This method is idempotent. Calling it several times in parallel is
129 * semantically equivalent to calling it exactly once.
130 *
131 * @since 10.0 (present in 1.0 as {@code run})
132 */
133 public void execute() {
134 // Lock while we update our state so the add method above will finish adding
135 // any listeners before we start to run them.
136 synchronized (runnables) {
137 if (executed) {
138 return;
139 }
140 executed = true;
141 }
142
143 // At this point the runnables will never be modified by another
144 // thread, so we are safe using it outside of the synchronized block.
145 while (!runnables.isEmpty()) {
146 runnables.poll().execute();
147 }
148 }
149
150 private static class RunnableExecutorPair {
151 final Runnable runnable;
152 final Executor executor;
153
154 RunnableExecutorPair(Runnable runnable, Executor executor) {
155 this.runnable = runnable;
156 this.executor = executor;
157 }
158
159 void execute() {
160 try {
161 executor.execute(runnable);
162 } catch (RuntimeException e) {
163 // Log it and keep going, bad runnable and/or executor. Don't
164 // punish the other runnables if we're given a bad one. We only
165 // catch RuntimeException because we want Errors to propagate up.
166 log.log(Level.SEVERE, "RuntimeException while executing runnable "
167 + runnable + " with executor " + executor, e);
168 }
169 }
170 }
171 }