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 017package com.google.common.util.concurrent; 018 019import static com.google.common.base.Preconditions.checkArgument; 020import static com.google.common.base.Preconditions.checkNotNull; 021 022import com.google.common.annotations.Beta; 023import com.google.common.annotations.GwtCompatible; 024import com.google.common.annotations.GwtIncompatible; 025import com.google.common.annotations.VisibleForTesting; 026import com.google.common.base.Supplier; 027import com.google.common.base.Throwables; 028import com.google.common.collect.Lists; 029import com.google.common.collect.Queues; 030import com.google.common.util.concurrent.ForwardingListenableFuture.SimpleForwardingListenableFuture; 031 032import java.lang.reflect.InvocationTargetException; 033import java.util.Collection; 034import java.util.Collections; 035import java.util.Iterator; 036import java.util.List; 037import java.util.concurrent.BlockingQueue; 038import java.util.concurrent.Callable; 039import java.util.concurrent.Delayed; 040import java.util.concurrent.ExecutionException; 041import java.util.concurrent.Executor; 042import java.util.concurrent.ExecutorService; 043import java.util.concurrent.Executors; 044import java.util.concurrent.Future; 045import java.util.concurrent.RejectedExecutionException; 046import java.util.concurrent.ScheduledExecutorService; 047import java.util.concurrent.ScheduledFuture; 048import java.util.concurrent.ScheduledThreadPoolExecutor; 049import java.util.concurrent.ThreadFactory; 050import java.util.concurrent.ThreadPoolExecutor; 051import java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy; 052import java.util.concurrent.TimeUnit; 053import java.util.concurrent.TimeoutException; 054 055import javax.annotation.concurrent.GuardedBy; 056 057/** 058 * Factory and utility methods for {@link java.util.concurrent.Executor}, {@link 059 * ExecutorService}, and {@link ThreadFactory}. 060 * 061 * @author Eric Fellheimer 062 * @author Kyle Littlefield 063 * @author Justin Mahoney 064 * @since 3.0 065 */ 066@GwtCompatible(emulated = true) 067public final class MoreExecutors { 068 private MoreExecutors() {} 069 070 /** 071 * Converts the given ThreadPoolExecutor into an ExecutorService that exits 072 * when the application is complete. It does so by using daemon threads and 073 * adding a shutdown hook to wait for their completion. 074 * 075 * <p>This is mainly for fixed thread pools. 076 * See {@link Executors#newFixedThreadPool(int)}. 077 * 078 * @param executor the executor to modify to make sure it exits when the 079 * application is finished 080 * @param terminationTimeout how long to wait for the executor to 081 * finish before terminating the JVM 082 * @param timeUnit unit of time for the time parameter 083 * @return an unmodifiable version of the input which will not hang the JVM 084 */ 085 @Beta 086 @GwtIncompatible("TODO") 087 public static ExecutorService getExitingExecutorService( 088 ThreadPoolExecutor executor, long terminationTimeout, TimeUnit timeUnit) { 089 return new Application() 090 .getExitingExecutorService(executor, terminationTimeout, timeUnit); 091 } 092 093 /** 094 * Converts the given ScheduledThreadPoolExecutor into a 095 * ScheduledExecutorService that exits when the application is complete. It 096 * does so by using daemon threads and adding a shutdown hook to wait for 097 * their completion. 098 * 099 * <p>This is mainly for fixed thread pools. 100 * See {@link Executors#newScheduledThreadPool(int)}. 101 * 102 * @param executor the executor to modify to make sure it exits when the 103 * application is finished 104 * @param terminationTimeout how long to wait for the executor to 105 * finish before terminating the JVM 106 * @param timeUnit unit of time for the time parameter 107 * @return an unmodifiable version of the input which will not hang the JVM 108 */ 109 @Beta 110 @GwtIncompatible("TODO") 111 public static ScheduledExecutorService getExitingScheduledExecutorService( 112 ScheduledThreadPoolExecutor executor, long terminationTimeout, TimeUnit timeUnit) { 113 return new Application() 114 .getExitingScheduledExecutorService(executor, terminationTimeout, timeUnit); 115 } 116 117 /** 118 * Add a shutdown hook to wait for thread completion in the given 119 * {@link ExecutorService service}. This is useful if the given service uses 120 * daemon threads, and we want to keep the JVM from exiting immediately on 121 * shutdown, instead giving these daemon threads a chance to terminate 122 * normally. 123 * @param service ExecutorService which uses daemon threads 124 * @param terminationTimeout how long to wait for the executor to finish 125 * before terminating the JVM 126 * @param timeUnit unit of time for the time parameter 127 */ 128 @Beta 129 @GwtIncompatible("TODO") 130 public static void addDelayedShutdownHook( 131 ExecutorService service, long terminationTimeout, TimeUnit timeUnit) { 132 new Application() 133 .addDelayedShutdownHook(service, terminationTimeout, timeUnit); 134 } 135 136 /** 137 * Converts the given ThreadPoolExecutor into an ExecutorService that exits 138 * when the application is complete. It does so by using daemon threads and 139 * adding a shutdown hook to wait for their completion. 140 * 141 * <p>This method waits 120 seconds before continuing with JVM termination, 142 * even if the executor has not finished its work. 143 * 144 * <p>This is mainly for fixed thread pools. 145 * See {@link Executors#newFixedThreadPool(int)}. 146 * 147 * @param executor the executor to modify to make sure it exits when the 148 * application is finished 149 * @return an unmodifiable version of the input which will not hang the JVM 150 */ 151 @Beta 152 @GwtIncompatible("concurrency") 153 public static ExecutorService getExitingExecutorService(ThreadPoolExecutor executor) { 154 return new Application().getExitingExecutorService(executor); 155 } 156 157 /** 158 * Converts the given ThreadPoolExecutor into a ScheduledExecutorService that 159 * exits when the application is complete. It does so by using daemon threads 160 * and adding a shutdown hook to wait for their completion. 161 * 162 * <p>This method waits 120 seconds before continuing with JVM termination, 163 * even if the executor has not finished its work. 164 * 165 * <p>This is mainly for fixed thread pools. 166 * See {@link Executors#newScheduledThreadPool(int)}. 167 * 168 * @param executor the executor to modify to make sure it exits when the 169 * application is finished 170 * @return an unmodifiable version of the input which will not hang the JVM 171 */ 172 @Beta 173 @GwtIncompatible("TODO") 174 public static ScheduledExecutorService getExitingScheduledExecutorService( 175 ScheduledThreadPoolExecutor executor) { 176 return new Application().getExitingScheduledExecutorService(executor); 177 } 178 179 /** Represents the current application to register shutdown hooks. */ 180 @GwtIncompatible("TODO") 181 @VisibleForTesting 182 static class Application { 183 184 final ExecutorService getExitingExecutorService( 185 ThreadPoolExecutor executor, long terminationTimeout, TimeUnit timeUnit) { 186 useDaemonThreadFactory(executor); 187 ExecutorService service = Executors.unconfigurableExecutorService(executor); 188 addDelayedShutdownHook(service, terminationTimeout, timeUnit); 189 return service; 190 } 191 192 final ScheduledExecutorService getExitingScheduledExecutorService( 193 ScheduledThreadPoolExecutor executor, long terminationTimeout, TimeUnit timeUnit) { 194 useDaemonThreadFactory(executor); 195 ScheduledExecutorService service = Executors.unconfigurableScheduledExecutorService(executor); 196 addDelayedShutdownHook(service, terminationTimeout, timeUnit); 197 return service; 198 } 199 200 final void addDelayedShutdownHook( 201 final ExecutorService service, final long terminationTimeout, final TimeUnit timeUnit) { 202 checkNotNull(service); 203 checkNotNull(timeUnit); 204 addShutdownHook(MoreExecutors.newThread("DelayedShutdownHook-for-" + service, new Runnable() { 205 @Override 206 public void run() { 207 try { 208 // We'd like to log progress and failures that may arise in the 209 // following code, but unfortunately the behavior of logging 210 // is undefined in shutdown hooks. 211 // This is because the logging code installs a shutdown hook of its 212 // own. See Cleaner class inside {@link LogManager}. 213 service.shutdown(); 214 service.awaitTermination(terminationTimeout, timeUnit); 215 } catch (InterruptedException ignored) { 216 // We're shutting down anyway, so just ignore. 217 } 218 } 219 })); 220 } 221 222 final ExecutorService getExitingExecutorService(ThreadPoolExecutor executor) { 223 return getExitingExecutorService(executor, 120, TimeUnit.SECONDS); 224 } 225 226 final ScheduledExecutorService getExitingScheduledExecutorService( 227 ScheduledThreadPoolExecutor executor) { 228 return getExitingScheduledExecutorService(executor, 120, TimeUnit.SECONDS); 229 } 230 231 @VisibleForTesting void addShutdownHook(Thread hook) { 232 Runtime.getRuntime().addShutdownHook(hook); 233 } 234 } 235 236 @GwtIncompatible("TODO") 237 private static void useDaemonThreadFactory(ThreadPoolExecutor executor) { 238 executor.setThreadFactory(new ThreadFactoryBuilder() 239 .setDaemon(true) 240 .setThreadFactory(executor.getThreadFactory()) 241 .build()); 242 } 243 244 /** 245 * Creates an executor service that runs each task in the thread 246 * that invokes {@code execute/submit}, as in {@link CallerRunsPolicy}. This 247 * applies both to individually submitted tasks and to collections of tasks 248 * submitted via {@code invokeAll} or {@code invokeAny}. In the latter case, 249 * tasks will run serially on the calling thread. Tasks are run to 250 * completion before a {@code Future} is returned to the caller (unless the 251 * executor has been shutdown). 252 * 253 * <p>Although all tasks are immediately executed in the thread that 254 * submitted the task, this {@code ExecutorService} imposes a small 255 * locking overhead on each task submission in order to implement shutdown 256 * and termination behavior. 257 * 258 * <p>The implementation deviates from the {@code ExecutorService} 259 * specification with regards to the {@code shutdownNow} method. First, 260 * "best-effort" with regards to canceling running tasks is implemented 261 * as "no-effort". No interrupts or other attempts are made to stop 262 * threads executing tasks. Second, the returned list will always be empty, 263 * as any submitted task is considered to have started execution. 264 * This applies also to tasks given to {@code invokeAll} or {@code invokeAny} 265 * which are pending serial execution, even the subset of the tasks that 266 * have not yet started execution. It is unclear from the 267 * {@code ExecutorService} specification if these should be included, and 268 * it's much easier to implement the interpretation that they not be. 269 * Finally, a call to {@code shutdown} or {@code shutdownNow} may result 270 * in concurrent calls to {@code invokeAll/invokeAny} throwing 271 * RejectedExecutionException, although a subset of the tasks may already 272 * have been executed. 273 * 274 * @since 10.0 (<a href="https://github.com/google/guava/wiki/Compatibility" 275 * >mostly source-compatible</a> since 3.0) 276 * @deprecated Use {@link #directExecutor()} if you only require an {@link Executor} and 277 * {@link #newDirectExecutorService()} if you need a {@link ListeningExecutorService}. This 278 * method will be removed in August 2016. 279 */ 280 @Deprecated 281 @GwtIncompatible("TODO") 282 public static ListeningExecutorService sameThreadExecutor() { 283 return new DirectExecutorService(); 284 } 285 286 // See sameThreadExecutor javadoc for behavioral notes. 287 @GwtIncompatible("TODO") 288 private static class DirectExecutorService 289 extends AbstractListeningExecutorService { 290 /** 291 * Lock used whenever accessing the state variables 292 * (runningTasks, shutdown) of the executor 293 */ 294 private final Object lock = new Object(); 295 296 /* 297 * Conceptually, these two variables describe the executor being in 298 * one of three states: 299 * - Active: shutdown == false 300 * - Shutdown: runningTasks > 0 and shutdown == true 301 * - Terminated: runningTasks == 0 and shutdown == true 302 */ 303 @GuardedBy("lock") private int runningTasks = 0; 304 @GuardedBy("lock") private boolean shutdown = false; 305 306 @Override 307 public void execute(Runnable command) { 308 startTask(); 309 try { 310 command.run(); 311 } finally { 312 endTask(); 313 } 314 } 315 316 @Override 317 public boolean isShutdown() { 318 synchronized (lock) { 319 return shutdown; 320 } 321 } 322 323 @Override 324 public void shutdown() { 325 synchronized (lock) { 326 shutdown = true; 327 if (runningTasks == 0) { 328 lock.notifyAll(); 329 } 330 } 331 } 332 333 // See sameThreadExecutor javadoc for unusual behavior of this method. 334 @Override 335 public List<Runnable> shutdownNow() { 336 shutdown(); 337 return Collections.emptyList(); 338 } 339 340 @Override 341 public boolean isTerminated() { 342 synchronized (lock) { 343 return shutdown && runningTasks == 0; 344 } 345 } 346 347 @Override 348 public boolean awaitTermination(long timeout, TimeUnit unit) 349 throws InterruptedException { 350 long nanos = unit.toNanos(timeout); 351 synchronized (lock) { 352 for (;;) { 353 if (shutdown && runningTasks == 0) { 354 return true; 355 } else if (nanos <= 0) { 356 return false; 357 } else { 358 long now = System.nanoTime(); 359 TimeUnit.NANOSECONDS.timedWait(lock, nanos); 360 nanos -= System.nanoTime() - now; // subtract the actual time we waited 361 } 362 } 363 } 364 } 365 366 /** 367 * Checks if the executor has been shut down and increments the running 368 * task count. 369 * 370 * @throws RejectedExecutionException if the executor has been previously 371 * shutdown 372 */ 373 private void startTask() { 374 synchronized (lock) { 375 if (shutdown) { 376 throw new RejectedExecutionException("Executor already shutdown"); 377 } 378 runningTasks++; 379 } 380 } 381 382 /** 383 * Decrements the running task count. 384 */ 385 private void endTask() { 386 synchronized (lock) { 387 int numRunning = --runningTasks; 388 if (numRunning == 0) { 389 lock.notifyAll(); 390 } 391 } 392 } 393 } 394 395 /** 396 * Creates an executor service that runs each task in the thread 397 * that invokes {@code execute/submit}, as in {@link CallerRunsPolicy} This 398 * applies both to individually submitted tasks and to collections of tasks 399 * submitted via {@code invokeAll} or {@code invokeAny}. In the latter case, 400 * tasks will run serially on the calling thread. Tasks are run to 401 * completion before a {@code Future} is returned to the caller (unless the 402 * executor has been shutdown). 403 * 404 * <p>Although all tasks are immediately executed in the thread that 405 * submitted the task, this {@code ExecutorService} imposes a small 406 * locking overhead on each task submission in order to implement shutdown 407 * and termination behavior. 408 * 409 * <p>The implementation deviates from the {@code ExecutorService} 410 * specification with regards to the {@code shutdownNow} method. First, 411 * "best-effort" with regards to canceling running tasks is implemented 412 * as "no-effort". No interrupts or other attempts are made to stop 413 * threads executing tasks. Second, the returned list will always be empty, 414 * as any submitted task is considered to have started execution. 415 * This applies also to tasks given to {@code invokeAll} or {@code invokeAny} 416 * which are pending serial execution, even the subset of the tasks that 417 * have not yet started execution. It is unclear from the 418 * {@code ExecutorService} specification if these should be included, and 419 * it's much easier to implement the interpretation that they not be. 420 * Finally, a call to {@code shutdown} or {@code shutdownNow} may result 421 * in concurrent calls to {@code invokeAll/invokeAny} throwing 422 * RejectedExecutionException, although a subset of the tasks may already 423 * have been executed. 424 * 425 * @since 18.0 (present as MoreExecutors.sameThreadExecutor() since 10.0) 426 */ 427 @GwtIncompatible("TODO") 428 public static ListeningExecutorService newDirectExecutorService() { 429 return new DirectExecutorService(); 430 } 431 432 /** 433 * Returns an {@link Executor} that runs each task in the thread that invokes 434 * {@link Executor#execute execute}, as in {@link CallerRunsPolicy}. 435 * 436 * <p>This instance is equivalent to: <pre> {@code 437 * final class DirectExecutor implements Executor { 438 * public void execute(Runnable r) { 439 * r.run(); 440 * } 441 * }}</pre> 442 * 443 * <p>This should be preferred to {@link #newDirectExecutorService()} because the implementing the 444 * {@link ExecutorService} subinterface necessitates significant performance overhead. 445 * 446 * @since 18.0 447 */ 448 public static Executor directExecutor() { 449 return DirectExecutor.INSTANCE; 450 } 451 452 /** See {@link #directExecutor} for behavioral notes. */ 453 private enum DirectExecutor implements Executor { 454 INSTANCE; 455 @Override public void execute(Runnable command) { 456 command.run(); 457 } 458 } 459 460 /** 461 * Creates an {@link ExecutorService} whose {@code submit} and {@code 462 * invokeAll} methods submit {@link ListenableFutureTask} instances to the 463 * given delegate executor. Those methods, as well as {@code execute} and 464 * {@code invokeAny}, are implemented in terms of calls to {@code 465 * delegate.execute}. All other methods are forwarded unchanged to the 466 * delegate. This implies that the returned {@code ListeningExecutorService} 467 * never calls the delegate's {@code submit}, {@code invokeAll}, and {@code 468 * invokeAny} methods, so any special handling of tasks must be implemented in 469 * the delegate's {@code execute} method or by wrapping the returned {@code 470 * ListeningExecutorService}. 471 * 472 * <p>If the delegate executor was already an instance of {@code 473 * ListeningExecutorService}, it is returned untouched, and the rest of this 474 * documentation does not apply. 475 * 476 * @since 10.0 477 */ 478 @GwtIncompatible("TODO") 479 public static ListeningExecutorService listeningDecorator( 480 ExecutorService delegate) { 481 return (delegate instanceof ListeningExecutorService) 482 ? (ListeningExecutorService) delegate 483 : (delegate instanceof ScheduledExecutorService) 484 ? new ScheduledListeningDecorator((ScheduledExecutorService) delegate) 485 : new ListeningDecorator(delegate); 486 } 487 488 /** 489 * Creates a {@link ScheduledExecutorService} whose {@code submit} and {@code 490 * invokeAll} methods submit {@link ListenableFutureTask} instances to the 491 * given delegate executor. Those methods, as well as {@code execute} and 492 * {@code invokeAny}, are implemented in terms of calls to {@code 493 * delegate.execute}. All other methods are forwarded unchanged to the 494 * delegate. This implies that the returned {@code 495 * ListeningScheduledExecutorService} never calls the delegate's {@code 496 * submit}, {@code invokeAll}, and {@code invokeAny} methods, so any special 497 * handling of tasks must be implemented in the delegate's {@code execute} 498 * method or by wrapping the returned {@code 499 * ListeningScheduledExecutorService}. 500 * 501 * <p>If the delegate executor was already an instance of {@code 502 * ListeningScheduledExecutorService}, it is returned untouched, and the rest 503 * of this documentation does not apply. 504 * 505 * @since 10.0 506 */ 507 @GwtIncompatible("TODO") 508 public static ListeningScheduledExecutorService listeningDecorator( 509 ScheduledExecutorService delegate) { 510 return (delegate instanceof ListeningScheduledExecutorService) 511 ? (ListeningScheduledExecutorService) delegate 512 : new ScheduledListeningDecorator(delegate); 513 } 514 515 @GwtIncompatible("TODO") 516 private static class ListeningDecorator 517 extends AbstractListeningExecutorService { 518 private final ExecutorService delegate; 519 520 ListeningDecorator(ExecutorService delegate) { 521 this.delegate = checkNotNull(delegate); 522 } 523 524 @Override 525 public boolean awaitTermination(long timeout, TimeUnit unit) 526 throws InterruptedException { 527 return delegate.awaitTermination(timeout, unit); 528 } 529 530 @Override 531 public boolean isShutdown() { 532 return delegate.isShutdown(); 533 } 534 535 @Override 536 public boolean isTerminated() { 537 return delegate.isTerminated(); 538 } 539 540 @Override 541 public void shutdown() { 542 delegate.shutdown(); 543 } 544 545 @Override 546 public List<Runnable> shutdownNow() { 547 return delegate.shutdownNow(); 548 } 549 550 @Override 551 public void execute(Runnable command) { 552 delegate.execute(command); 553 } 554 } 555 556 @GwtIncompatible("TODO") 557 private static class ScheduledListeningDecorator 558 extends ListeningDecorator implements ListeningScheduledExecutorService { 559 @SuppressWarnings("hiding") 560 final ScheduledExecutorService delegate; 561 562 ScheduledListeningDecorator(ScheduledExecutorService delegate) { 563 super(delegate); 564 this.delegate = checkNotNull(delegate); 565 } 566 567 @Override 568 public ListenableScheduledFuture<?> schedule( 569 Runnable command, long delay, TimeUnit unit) { 570 TrustedListenableFutureTask<Void> task = 571 TrustedListenableFutureTask.create(command, null); 572 ScheduledFuture<?> scheduled = delegate.schedule(task, delay, unit); 573 return new ListenableScheduledTask<Void>(task, scheduled); 574 } 575 576 @Override 577 public <V> ListenableScheduledFuture<V> schedule( 578 Callable<V> callable, long delay, TimeUnit unit) { 579 TrustedListenableFutureTask<V> task = TrustedListenableFutureTask.create(callable); 580 ScheduledFuture<?> scheduled = delegate.schedule(task, delay, unit); 581 return new ListenableScheduledTask<V>(task, scheduled); 582 } 583 584 @Override 585 public ListenableScheduledFuture<?> scheduleAtFixedRate( 586 Runnable command, long initialDelay, long period, TimeUnit unit) { 587 NeverSuccessfulListenableFutureTask task = 588 new NeverSuccessfulListenableFutureTask(command); 589 ScheduledFuture<?> scheduled = 590 delegate.scheduleAtFixedRate(task, initialDelay, period, unit); 591 return new ListenableScheduledTask<Void>(task, scheduled); 592 } 593 594 @Override 595 public ListenableScheduledFuture<?> scheduleWithFixedDelay( 596 Runnable command, long initialDelay, long delay, TimeUnit unit) { 597 NeverSuccessfulListenableFutureTask task = 598 new NeverSuccessfulListenableFutureTask(command); 599 ScheduledFuture<?> scheduled = 600 delegate.scheduleWithFixedDelay(task, initialDelay, delay, unit); 601 return new ListenableScheduledTask<Void>(task, scheduled); 602 } 603 604 private static final class ListenableScheduledTask<V> 605 extends SimpleForwardingListenableFuture<V> 606 implements ListenableScheduledFuture<V> { 607 608 private final ScheduledFuture<?> scheduledDelegate; 609 610 public ListenableScheduledTask( 611 ListenableFuture<V> listenableDelegate, 612 ScheduledFuture<?> scheduledDelegate) { 613 super(listenableDelegate); 614 this.scheduledDelegate = scheduledDelegate; 615 } 616 617 @Override 618 public boolean cancel(boolean mayInterruptIfRunning) { 619 boolean cancelled = super.cancel(mayInterruptIfRunning); 620 if (cancelled) { 621 // Unless it is cancelled, the delegate may continue being scheduled 622 scheduledDelegate.cancel(mayInterruptIfRunning); 623 624 // TODO(user): Cancel "this" if "scheduledDelegate" is cancelled. 625 } 626 return cancelled; 627 } 628 629 @Override 630 public long getDelay(TimeUnit unit) { 631 return scheduledDelegate.getDelay(unit); 632 } 633 634 @Override 635 public int compareTo(Delayed other) { 636 return scheduledDelegate.compareTo(other); 637 } 638 } 639 640 @GwtIncompatible("TODO") 641 private static final class NeverSuccessfulListenableFutureTask 642 extends AbstractFuture<Void> 643 implements Runnable { 644 private final Runnable delegate; 645 646 public NeverSuccessfulListenableFutureTask(Runnable delegate) { 647 this.delegate = checkNotNull(delegate); 648 } 649 650 @Override public void run() { 651 try { 652 delegate.run(); 653 } catch (Throwable t) { 654 setException(t); 655 throw Throwables.propagate(t); 656 } 657 } 658 } 659 } 660 661 /* 662 * This following method is a modified version of one found in 663 * http://gee.cs.oswego.edu/cgi-bin/viewcvs.cgi/jsr166/src/test/tck/AbstractExecutorServiceTest.java?revision=1.30 664 * which contained the following notice: 665 * 666 * Written by Doug Lea with assistance from members of JCP JSR-166 667 * Expert Group and released to the public domain, as explained at 668 * http://creativecommons.org/publicdomain/zero/1.0/ 669 * Other contributors include Andrew Wright, Jeffrey Hayes, 670 * Pat Fisher, Mike Judd. 671 */ 672 673 /** 674 * An implementation of {@link ExecutorService#invokeAny} for {@link ListeningExecutorService} 675 * implementations. 676 */ static <T> T invokeAnyImpl(ListeningExecutorService executorService, 677 Collection<? extends Callable<T>> tasks, boolean timed, long nanos) 678 throws InterruptedException, ExecutionException, TimeoutException { 679 checkNotNull(executorService); 680 int ntasks = tasks.size(); 681 checkArgument(ntasks > 0); 682 List<Future<T>> futures = Lists.newArrayListWithCapacity(ntasks); 683 BlockingQueue<Future<T>> futureQueue = Queues.newLinkedBlockingQueue(); 684 685 // For efficiency, especially in executors with limited 686 // parallelism, check to see if previously submitted tasks are 687 // done before submitting more of them. This interleaving 688 // plus the exception mechanics account for messiness of main 689 // loop. 690 691 try { 692 // Record exceptions so that if we fail to obtain any 693 // result, we can throw the last exception we got. 694 ExecutionException ee = null; 695 long lastTime = timed ? System.nanoTime() : 0; 696 Iterator<? extends Callable<T>> it = tasks.iterator(); 697 698 futures.add(submitAndAddQueueListener(executorService, it.next(), futureQueue)); 699 --ntasks; 700 int active = 1; 701 702 for (;;) { 703 Future<T> f = futureQueue.poll(); 704 if (f == null) { 705 if (ntasks > 0) { 706 --ntasks; 707 futures.add(submitAndAddQueueListener(executorService, it.next(), futureQueue)); 708 ++active; 709 } else if (active == 0) { 710 break; 711 } else if (timed) { 712 f = futureQueue.poll(nanos, TimeUnit.NANOSECONDS); 713 if (f == null) { 714 throw new TimeoutException(); 715 } 716 long now = System.nanoTime(); 717 nanos -= now - lastTime; 718 lastTime = now; 719 } else { 720 f = futureQueue.take(); 721 } 722 } 723 if (f != null) { 724 --active; 725 try { 726 return f.get(); 727 } catch (ExecutionException eex) { 728 ee = eex; 729 } catch (RuntimeException rex) { 730 ee = new ExecutionException(rex); 731 } 732 } 733 } 734 735 if (ee == null) { 736 ee = new ExecutionException(null); 737 } 738 throw ee; 739 } finally { 740 for (Future<T> f : futures) { 741 f.cancel(true); 742 } 743 } 744 } 745 746 /** 747 * Submits the task and adds a listener that adds the future to {@code queue} when it completes. 748 */ 749 @GwtIncompatible("TODO") 750 private static <T> ListenableFuture<T> submitAndAddQueueListener( 751 ListeningExecutorService executorService, Callable<T> task, 752 final BlockingQueue<Future<T>> queue) { 753 final ListenableFuture<T> future = executorService.submit(task); 754 future.addListener(new Runnable() { 755 @Override public void run() { 756 queue.add(future); 757 } 758 }, directExecutor()); 759 return future; 760 } 761 762 /** 763 * Returns a default thread factory used to create new threads. 764 * 765 * <p>On AppEngine, returns {@code ThreadManager.currentRequestThreadFactory()}. 766 * Otherwise, returns {@link Executors#defaultThreadFactory()}. 767 * 768 * @since 14.0 769 */ 770 @Beta 771 @GwtIncompatible("concurrency") 772 public static ThreadFactory platformThreadFactory() { 773 if (!isAppEngine()) { 774 return Executors.defaultThreadFactory(); 775 } 776 try { 777 return (ThreadFactory) Class.forName("com.google.appengine.api.ThreadManager") 778 .getMethod("currentRequestThreadFactory") 779 .invoke(null); 780 } catch (IllegalAccessException e) { 781 throw new RuntimeException("Couldn't invoke ThreadManager.currentRequestThreadFactory", e); 782 } catch (ClassNotFoundException e) { 783 throw new RuntimeException("Couldn't invoke ThreadManager.currentRequestThreadFactory", e); 784 } catch (NoSuchMethodException e) { 785 throw new RuntimeException("Couldn't invoke ThreadManager.currentRequestThreadFactory", e); 786 } catch (InvocationTargetException e) { 787 throw Throwables.propagate(e.getCause()); 788 } 789 } 790 791 @GwtIncompatible("TODO") 792 private static boolean isAppEngine() { 793 if (System.getProperty("com.google.appengine.runtime.environment") == null) { 794 return false; 795 } 796 try { 797 // If the current environment is null, we're not inside AppEngine. 798 return Class.forName("com.google.apphosting.api.ApiProxy") 799 .getMethod("getCurrentEnvironment") 800 .invoke(null) != null; 801 } catch (ClassNotFoundException e) { 802 // If ApiProxy doesn't exist, we're not on AppEngine at all. 803 return false; 804 } catch (InvocationTargetException e) { 805 // If ApiProxy throws an exception, we're not in a proper AppEngine environment. 806 return false; 807 } catch (IllegalAccessException e) { 808 // If the method isn't accessible, we're not on a supported version of AppEngine; 809 return false; 810 } catch (NoSuchMethodException e) { 811 // If the method doesn't exist, we're not on a supported version of AppEngine; 812 return false; 813 } 814 } 815 816 /** 817 * Creates a thread using {@link #platformThreadFactory}, and sets its name to {@code name} 818 * unless changing the name is forbidden by the security manager. 819 */ 820 @GwtIncompatible("concurrency") 821 static Thread newThread(String name, Runnable runnable) { 822 checkNotNull(name); 823 checkNotNull(runnable); 824 Thread result = platformThreadFactory().newThread(runnable); 825 try { 826 result.setName(name); 827 } catch (SecurityException e) { 828 // OK if we can't set the name in this environment. 829 } 830 return result; 831 } 832 833 // TODO(lukes): provide overloads for ListeningExecutorService? ListeningScheduledExecutorService? 834 // TODO(lukes): provide overloads that take constant strings? Function<Runnable, String>s to 835 // calculate names? 836 837 /** 838 * Creates an {@link Executor} that renames the {@link Thread threads} that its tasks run in. 839 * 840 * <p>The names are retrieved from the {@code nameSupplier} on the thread that is being renamed 841 * right before each task is run. The renaming is best effort, if a {@link SecurityManager} 842 * prevents the renaming then it will be skipped but the tasks will still execute. 843 * 844 * 845 * @param executor The executor to decorate 846 * @param nameSupplier The source of names for each task 847 */ 848 @GwtIncompatible("concurrency") 849 static Executor renamingDecorator(final Executor executor, final Supplier<String> nameSupplier) { 850 checkNotNull(executor); 851 checkNotNull(nameSupplier); 852 if (isAppEngine()) { 853 // AppEngine doesn't support thread renaming, so don't even try 854 return executor; 855 } 856 return new Executor() { 857 @Override public void execute(Runnable command) { 858 executor.execute(Callables.threadRenaming(command, nameSupplier)); 859 } 860 }; 861 } 862 863 /** 864 * Creates an {@link ExecutorService} that renames the {@link Thread threads} that its tasks run 865 * in. 866 * 867 * <p>The names are retrieved from the {@code nameSupplier} on the thread that is being renamed 868 * right before each task is run. The renaming is best effort, if a {@link SecurityManager} 869 * prevents the renaming then it will be skipped but the tasks will still execute. 870 * 871 * 872 * @param service The executor to decorate 873 * @param nameSupplier The source of names for each task 874 */ 875 @GwtIncompatible("concurrency") 876 static ExecutorService renamingDecorator(final ExecutorService service, 877 final Supplier<String> nameSupplier) { 878 checkNotNull(service); 879 checkNotNull(nameSupplier); 880 if (isAppEngine()) { 881 // AppEngine doesn't support thread renaming, so don't even try. 882 return service; 883 } 884 return new WrappingExecutorService(service) { 885 @Override protected <T> Callable<T> wrapTask(Callable<T> callable) { 886 return Callables.threadRenaming(callable, nameSupplier); 887 } 888 @Override protected Runnable wrapTask(Runnable command) { 889 return Callables.threadRenaming(command, nameSupplier); 890 } 891 }; 892 } 893 894 /** 895 * Creates a {@link ScheduledExecutorService} that renames the {@link Thread threads} that its 896 * tasks run in. 897 * 898 * <p>The names are retrieved from the {@code nameSupplier} on the thread that is being renamed 899 * right before each task is run. The renaming is best effort, if a {@link SecurityManager} 900 * prevents the renaming then it will be skipped but the tasks will still execute. 901 * 902 * 903 * @param service The executor to decorate 904 * @param nameSupplier The source of names for each task 905 */ 906 @GwtIncompatible("concurrency") 907 static ScheduledExecutorService renamingDecorator(final ScheduledExecutorService service, 908 final Supplier<String> nameSupplier) { 909 checkNotNull(service); 910 checkNotNull(nameSupplier); 911 if (isAppEngine()) { 912 // AppEngine doesn't support thread renaming, so don't even try. 913 return service; 914 } 915 return new WrappingScheduledExecutorService(service) { 916 @Override protected <T> Callable<T> wrapTask(Callable<T> callable) { 917 return Callables.threadRenaming(callable, nameSupplier); 918 } 919 @Override protected Runnable wrapTask(Runnable command) { 920 return Callables.threadRenaming(command, nameSupplier); 921 } 922 }; 923 } 924 925 /** 926 * Shuts down the given executor gradually, first disabling new submissions and later cancelling 927 * existing tasks. 928 * 929 * <p>The method takes the following steps: 930 * <ol> 931 * <li>calls {@link ExecutorService#shutdown()}, disabling acceptance of new submitted tasks. 932 * <li>waits for half of the specified timeout. 933 * <li>if the timeout expires, it calls {@link ExecutorService#shutdownNow()}, cancelling 934 * pending tasks and interrupting running tasks. 935 * <li>waits for the other half of the specified timeout. 936 * </ol> 937 * 938 * <p>If, at any step of the process, the calling thread is interrupted, the method calls {@link 939 * ExecutorService#shutdownNow()} and returns. 940 * 941 * @param service the {@code ExecutorService} to shut down 942 * @param timeout the maximum time to wait for the {@code ExecutorService} to terminate 943 * @param unit the time unit of the timeout argument 944 * @return {@code true} if the {@code ExecutorService} was terminated successfully, {@code false} 945 * the call timed out or was interrupted 946 * @since 17.0 947 */ 948 @Beta 949 @GwtIncompatible("concurrency") 950 public static boolean shutdownAndAwaitTermination( 951 ExecutorService service, long timeout, TimeUnit unit) { 952 checkNotNull(unit); 953 // Disable new tasks from being submitted 954 service.shutdown(); 955 try { 956 long halfTimeoutNanos = TimeUnit.NANOSECONDS.convert(timeout, unit) / 2; 957 // Wait for half the duration of the timeout for existing tasks to terminate 958 if (!service.awaitTermination(halfTimeoutNanos, TimeUnit.NANOSECONDS)) { 959 // Cancel currently executing tasks 960 service.shutdownNow(); 961 // Wait the other half of the timeout for tasks to respond to being cancelled 962 service.awaitTermination(halfTimeoutNanos, TimeUnit.NANOSECONDS); 963 } 964 } catch (InterruptedException ie) { 965 // Preserve interrupt status 966 Thread.currentThread().interrupt(); 967 // (Re-)Cancel if current thread also interrupted 968 service.shutdownNow(); 969 } 970 return service.isTerminated(); 971 } 972}