| // Copyright 2015 The Bazel Authors. All rights reserved. |
| // |
| // 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.devtools.build.lib.concurrent; |
| |
| import com.google.common.annotations.VisibleForTesting; |
| import com.google.common.util.concurrent.ListenableFuture; |
| import java.util.concurrent.CountDownLatch; |
| import java.util.concurrent.Executor; |
| |
| /** |
| * QuiescingExecutor is an {@link Executor} which supports waiting until all submitted tasks are |
| * complete. This is useful when tasks may submit additional tasks. |
| * |
| * <p>Consider the following example: |
| * <pre> |
| * ThreadPoolExecutor executor = <...> |
| * executor.submit(myRunnableTask); |
| * executor.shutdown(); |
| * executor.awaitTermination(); |
| * </pre> |
| * |
| * <p>This won't work properly if {@code myRunnableTask} submits additional tasks to the |
| * executor, because it may already have shut down by that point. |
| * |
| * <p>QuiescingExecutor supports interruption. If the main thread is interrupted, tasks will no |
| * longer be started, and the {@link #awaitQuiescence} method will throw {@link |
| * InterruptedException}. |
| */ |
| public interface QuiescingExecutor extends Executor { |
| |
| /** |
| * Waits for all tasks to complete. If the {@link QuiescingExecutor} owns its own {@link |
| * java.util.concurrent.ExecutorService}, the service will also be shutdown. |
| * |
| * <p>Throws (the same) unchecked exception if any worker thread failed unexpectedly. If the main |
| * thread is interrupted and a worker also throws an unchecked exception, the unchecked exception |
| * is rethrown, since it may indicate a programming bug. If callers handle the unchecked |
| * exception, they may check the interrupted bit to see if the pool was interrupted. |
| * |
| * @param interruptWorkers if true, interrupt worker threads if main thread gets an interrupt. |
| * If false, just wait for them to terminate normally. |
| */ |
| void awaitQuiescence(boolean interruptWorkers) throws InterruptedException; |
| |
| /** |
| * Prevent quiescence of the executor until the given future is completed. If the executor is |
| * interrupted, then the executor will call {@link ListenableFuture#cancel} with a parameter of |
| * {@code true}. |
| */ |
| void dependOnFuture(ListenableFuture<?> future) throws InterruptedException; |
| |
| /** Get latch that is released if a task throws an exception. Used only in tests. */ |
| @VisibleForTesting |
| CountDownLatch getExceptionLatchForTestingOnly(); |
| |
| /** Get latch that is released if a task is interrupted. Used only in tests. */ |
| @VisibleForTesting |
| CountDownLatch getInterruptionLatchForTestingOnly(); |
| } |