001/* 002 * Copyright (C) 2007 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the License 010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 011 * or implied. See the License for the specific language governing permissions and limitations under 012 * the License. 013 */ 014 015package com.google.common.util.concurrent; 016 017import static com.google.common.base.Preconditions.checkNotNull; 018 019import com.google.common.annotations.GwtIncompatible; 020import com.google.errorprone.annotations.concurrent.GuardedBy; 021import java.util.concurrent.Executor; 022import java.util.logging.Level; 023import java.util.logging.Logger; 024import org.checkerframework.checker.nullness.qual.Nullable; 025 026/** 027 * A support class for {@code ListenableFuture} implementations to manage their listeners. An 028 * instance contains a list of listeners, each with an associated {@code Executor}, and guarantees 029 * that every {@code Runnable} that is {@linkplain #add added} will be executed after {@link 030 * #execute()} is called. Any {@code Runnable} added after the call to {@code execute} is still 031 * guaranteed to execute. There is no guarantee, however, that listeners will be executed in the 032 * order that they are added. 033 * 034 * <p>Exceptions thrown by a listener will be propagated up to the executor. Any exception thrown 035 * during {@code Executor.execute} (e.g., a {@code RejectedExecutionException} or an exception 036 * thrown by {@linkplain MoreExecutors#directExecutor direct execution}) will be caught and logged. 037 * 038 * @author Nishant Thakkar 039 * @author Sven Mawson 040 * @since 1.0 041 */ 042@GwtIncompatible 043public final class ExecutionList { 044 /** Logger to log exceptions caught when running runnables. */ 045 private static final Logger log = Logger.getLogger(ExecutionList.class.getName()); 046 047 /** 048 * The runnable, executor pairs to execute. This acts as a stack threaded through the {@link 049 * RunnableExecutorPair#next} field. 050 */ 051 @GuardedBy("this") 052 private @Nullable RunnableExecutorPair runnables; 053 054 @GuardedBy("this") 055 private boolean executed; 056 057 /** Creates a new, empty {@link ExecutionList}. */ 058 public ExecutionList() {} 059 060 /** 061 * Adds the {@code Runnable} and accompanying {@code Executor} to the list of listeners to 062 * execute. If execution has already begun, the listener is executed immediately. 063 * 064 * <p>When selecting an executor, note that {@code directExecutor} is dangerous in some cases. See 065 * the discussion in the {@link ListenableFuture#addListener ListenableFuture.addListener} 066 * documentation. 067 */ 068 public void add(Runnable runnable, Executor executor) { 069 // Fail fast on a null. We throw NPE here because the contract of Executor states that it throws 070 // NPE on null listener, so we propagate that contract up into the add method as well. 071 checkNotNull(runnable, "Runnable was null."); 072 checkNotNull(executor, "Executor was null."); 073 074 // Lock while we check state. We must maintain the lock while adding the new pair so that 075 // another thread can't run the list out from under us. We only add to the list if we have not 076 // yet started execution. 077 synchronized (this) { 078 if (!executed) { 079 runnables = new RunnableExecutorPair(runnable, executor, runnables); 080 return; 081 } 082 } 083 // Execute the runnable immediately. Because of scheduling this may end up getting called before 084 // some of the previously added runnables, but we're OK with that. If we want to change the 085 // contract to guarantee ordering among runnables we'd have to modify the logic here to allow 086 // it. 087 executeListener(runnable, executor); 088 } 089 090 /** 091 * Runs this execution list, executing all existing pairs in the order they were added. However, 092 * note that listeners added after this point may be executed before those previously added, and 093 * note that the execution order of all listeners is ultimately chosen by the implementations of 094 * the supplied executors. 095 * 096 * <p>This method is idempotent. Calling it several times in parallel is semantically equivalent 097 * to calling it exactly once. 098 * 099 * @since 10.0 (present in 1.0 as {@code run}) 100 */ 101 public void execute() { 102 // Lock while we update our state so the add method above will finish adding any listeners 103 // before we start to run them. 104 RunnableExecutorPair list; 105 synchronized (this) { 106 if (executed) { 107 return; 108 } 109 executed = true; 110 list = runnables; 111 runnables = null; // allow GC to free listeners even if this stays around for a while. 112 } 113 // If we succeeded then list holds all the runnables we to execute. The pairs in the stack are 114 // in the opposite order from how they were added so we need to reverse the list to fulfill our 115 // contract. 116 // This is somewhat annoying, but turns out to be very fast in practice. Alternatively, we could 117 // drop the contract on the method that enforces this queue like behavior since depending on it 118 // is likely to be a bug anyway. 119 120 // N.B. All writes to the list and the next pointers must have happened before the above 121 // synchronized block, so we can iterate the list without the lock held here. 122 RunnableExecutorPair reversedList = null; 123 while (list != null) { 124 RunnableExecutorPair tmp = list; 125 list = list.next; 126 tmp.next = reversedList; 127 reversedList = tmp; 128 } 129 while (reversedList != null) { 130 executeListener(reversedList.runnable, reversedList.executor); 131 reversedList = reversedList.next; 132 } 133 } 134 135 /** 136 * Submits the given runnable to the given {@link Executor} catching and logging all {@linkplain 137 * RuntimeException runtime exceptions} thrown by the executor. 138 */ 139 private static void executeListener(Runnable runnable, Executor executor) { 140 try { 141 executor.execute(runnable); 142 } catch (RuntimeException e) { 143 // Log it and keep going -- bad runnable and/or executor. Don't punish the other runnables if 144 // we're given a bad one. We only catch RuntimeException because we want Errors to propagate 145 // up. 146 log.log( 147 Level.SEVERE, 148 "RuntimeException while executing runnable " + runnable + " with executor " + executor, 149 e); 150 } 151 } 152 153 private static final class RunnableExecutorPair { 154 final Runnable runnable; 155 final Executor executor; 156 @Nullable RunnableExecutorPair next; 157 158 RunnableExecutorPair(Runnable runnable, Executor executor, RunnableExecutorPair next) { 159 this.runnable = runnable; 160 this.executor = executor; 161 this.next = next; 162 } 163 } 164}