Java tutorial
/* * Copyright (C) 2007 The Guava Authors * * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except * in compliance with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software distributed under the License * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express * or implied. See the License for the specific language governing permissions and limitations under * the License. */ package com.google.common.util.concurrent; import static com.google.common.base.Preconditions.checkNotNull; import com.google.common.annotations.VisibleForTesting; import java.util.concurrent.Executor; import java.util.logging.Level; import java.util.logging.Logger; import javax.annotation.Nullable; import javax.annotation.concurrent.GuardedBy; /** * A support class for {@code ListenableFuture} implementations to manage their listeners. An * instance contains a list of listeners, each with an associated {@code Executor}, and guarantees * that every {@code Runnable} that is {@linkplain #add added} will be executed after {@link * #execute()} is called. Any {@code Runnable} added after the call to {@code execute} is still * guaranteed to execute. There is no guarantee, however, that listeners will be executed in the * order that they are added. * * <p>Exceptions thrown by a listener will be propagated up to the executor. Any exception thrown * during {@code Executor.execute} (e.g., a {@code RejectedExecutionException} or an exception * thrown by {@linkplain MoreExecutors#directExecutor direct execution}) will be caught and logged. * * @author Nishant Thakkar * @author Sven Mawson * @since 1.0 */ public final class ExecutionList { // Logger to log exceptions caught when running runnables. @VisibleForTesting static final Logger log = Logger.getLogger(ExecutionList.class.getName()); /** * The runnable, executor pairs to execute. This acts as a stack threaded through the {@link * RunnableExecutorPair#next} field. */ @GuardedBy("this") private RunnableExecutorPair runnables; @GuardedBy("this") private boolean executed; /** Creates a new, empty {@link ExecutionList}. */ public ExecutionList() { } /** * Adds the {@code Runnable} and accompanying {@code Executor} to the list of listeners to * execute. If execution has already begun, the listener is executed immediately. * * <p>When selecting an executor, note that {@code directExecutor} is dangerous in some cases. See * the discussion in the {@link ListenableFuture#addListener ListenableFuture.addListener} * documentation. */ public void add(Runnable runnable, Executor executor) { // Fail fast on a null. We throw NPE here because the contract of Executor states that it // throws NPE on null listener, so we propagate that contract up into the add method as well. checkNotNull(runnable, "Runnable was null."); checkNotNull(executor, "Executor was null."); // Lock while we check state. We must maintain the lock while adding the new pair so that // another thread can't run the list out from under us. We only add to the list if we have not // yet started execution. synchronized (this) { if (!executed) { runnables = new RunnableExecutorPair(runnable, executor, runnables); return; } } // Execute the runnable immediately. Because of scheduling this may end up getting called before // some of the previously added runnables, but we're OK with that. If we want to change the // contract to guarantee ordering among runnables we'd have to modify the logic here to allow // it. executeListener(runnable, executor); } /** * Runs this execution list, executing all existing pairs in the order they were added. However, * note that listeners added after this point may be executed before those previously added, and * note that the execution order of all listeners is ultimately chosen by the implementations of * the supplied executors. * * <p>This method is idempotent. Calling it several times in parallel is semantically equivalent * to calling it exactly once. * * @since 10.0 (present in 1.0 as {@code run}) */ public void execute() { // Lock while we update our state so the add method above will finish adding any listeners // before we start to run them. RunnableExecutorPair list; synchronized (this) { if (executed) { return; } executed = true; list = runnables; runnables = null; // allow GC to free listeners even if this stays around for a while. } // If we succeeded then list holds all the runnables we to execute. The pairs in the stack are // in the opposite order from how they were added so we need to reverse the list to fulfill our // contract. // This is somewhat annoying, but turns out to be very fast in practice. Alternatively, we // could drop the contract on the method that enforces this queue like behavior since depending // on it is likely to be a bug anyway. // N.B. All writes to the list and the next pointers must have happened before the above // synchronized block, so we can iterate the list without the lock held here. RunnableExecutorPair reversedList = null; while (list != null) { RunnableExecutorPair tmp = list; list = list.next; tmp.next = reversedList; reversedList = tmp; } while (reversedList != null) { executeListener(reversedList.runnable, reversedList.executor); reversedList = reversedList.next; } } /** * Submits the given runnable to the given {@link Executor} catching and logging all {@linkplain * RuntimeException runtime exceptions} thrown by the executor. */ private static void executeListener(Runnable runnable, Executor executor) { try { executor.execute(runnable); } catch (RuntimeException e) { // Log it and keep going, bad runnable and/or executor. Don't punish the other runnables if // we're given a bad one. We only catch RuntimeException because we want Errors to propagate // up. log.log(Level.SEVERE, "RuntimeException while executing runnable " + runnable + " with executor " + executor, e); } } private static final class RunnableExecutorPair { final Runnable runnable; final Executor executor; @Nullable RunnableExecutorPair next; RunnableExecutorPair(Runnable runnable, Executor executor, RunnableExecutorPair next) { this.runnable = runnable; this.executor = executor; this.next = next; } } }