MoreExecutors
Date: 2016-05-24

com.google.common.util.concurrent

## Class MoreExecutors

- java.lang.Object
- - com.google.common.util.concurrent.MoreExecutors

-     @GwtCompatible(emulated=true)
      public final class MoreExecutors
      extends java.lang.Object

  Factory and utility methods for `Executor`, `ExecutorService`, and `ThreadFactory`.
  Since:
    3.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `addDelayedShutdownHook(java.util.concurrent.ExecutorService service, long terminationTimeout, java.util.concurrent.TimeUnit timeUnit)` Add a shutdown hook to wait for thread completion in the given `service`.
    `static java.util.concurrent.Executor` | `directExecutor()` Returns an `Executor` that runs each task in the thread that invokes `execute`, as in `ThreadPoolExecutor.CallerRunsPolicy`.
    `static java.util.concurrent.ExecutorService` | `getExitingExecutorService(java.util.concurrent.ThreadPoolExecutor executor)` Converts the given ThreadPoolExecutor into an ExecutorService that exits when the application is complete.
    `static java.util.concurrent.ExecutorService` | `getExitingExecutorService(java.util.concurrent.ThreadPoolExecutor executor, long terminationTimeout, java.util.concurrent.TimeUnit timeUnit)` Converts the given ThreadPoolExecutor into an ExecutorService that exits when the application is complete.
    `static java.util.concurrent.ScheduledExecutorService` | `getExitingScheduledExecutorService(java.util.concurrent.ScheduledThreadPoolExecutor executor)` Converts the given ThreadPoolExecutor into a ScheduledExecutorService that exits when the application is complete.
    `static java.util.concurrent.ScheduledExecutorService` | `getExitingScheduledExecutorService(java.util.concurrent.ScheduledThreadPoolExecutor executor, long terminationTimeout, java.util.concurrent.TimeUnit timeUnit)` Converts the given ScheduledThreadPoolExecutor into a ScheduledExecutorService that exits when the application is complete.
    `static ListeningExecutorService` | `listeningDecorator(java.util.concurrent.ExecutorService delegate)` Creates an `ExecutorService` whose `submit` and `invokeAll` methods submit `ListenableFutureTask` instances to the given delegate executor.
    `static ListeningScheduledExecutorService` | `listeningDecorator(java.util.concurrent.ScheduledExecutorService delegate)` Creates a `ScheduledExecutorService` whose `submit` and `invokeAll` methods submit `ListenableFutureTask` instances to the given delegate executor.
    `static ListeningExecutorService` | `newDirectExecutorService()` Creates an executor service that runs each task in the thread that invokes `execute/submit`, as in `ThreadPoolExecutor.CallerRunsPolicy` This applies both to individually submitted tasks and to collections of tasks submitted via `invokeAll` or `invokeAny`.
    `static java.util.concurrent.ThreadFactory` | `platformThreadFactory()` Returns a default thread factory used to create new threads.
    `static ListeningExecutorService` | `sameThreadExecutor()` Deprecated. Use `directExecutor()` if you only require an `Executor` and `newDirectExecutorService()` if you need a `ListeningExecutorService`. This method will be removed in August 2016.
    `static boolean` | `shutdownAndAwaitTermination(java.util.concurrent.ExecutorService service, long timeout, java.util.concurrent.TimeUnit unit)` Shuts down the given executor gradually, first disabling new submissions and later cancelling existing tasks.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### getExitingExecutorService

          @Beta
          @GwtIncompatible(value="TODO")
          public static java.util.concurrent.ExecutorService getExitingExecutorService(java.util.concurrent.ThreadPoolExecutor executor,
                                                                                                 long terminationTimeout,
                                                                                                 java.util.concurrent.TimeUnit timeUnit)

      Converts the given ThreadPoolExecutor into an ExecutorService that exits when the application is complete. It does so by using daemon threads and adding a shutdown hook to wait for their completion.

      This is mainly for fixed thread pools. See `Executors.newFixedThreadPool(int)`.

      Parameters:
        `executor` - the executor to modify to make sure it exits when the application is finished
        `terminationTimeout` - how long to wait for the executor to finish before terminating the JVM
        `timeUnit` - unit of time for the time parameter
      Returns:
        an unmodifiable version of the input which will not hang the JVM

    - #### getExitingScheduledExecutorService

          @Beta
          @GwtIncompatible(value="TODO")
          public static java.util.concurrent.ScheduledExecutorService getExitingScheduledExecutorService(java.util.concurrent.ScheduledThreadPoolExecutor executor,
                                                                                                                   long terminationTimeout,
                                                                                                                   java.util.concurrent.TimeUnit timeUnit)

      Converts the given ScheduledThreadPoolExecutor into a ScheduledExecutorService that exits when the application is complete. It does so by using daemon threads and adding a shutdown hook to wait for their completion.

      This is mainly for fixed thread pools. See `Executors.newScheduledThreadPool(int)`.

      Parameters:
        `executor` - the executor to modify to make sure it exits when the application is finished
        `terminationTimeout` - how long to wait for the executor to finish before terminating the JVM
        `timeUnit` - unit of time for the time parameter
      Returns:
        an unmodifiable version of the input which will not hang the JVM

    - #### addDelayedShutdownHook

          @Beta
          @GwtIncompatible(value="TODO")
          public static void addDelayedShutdownHook(java.util.concurrent.ExecutorService service,
                                                              long terminationTimeout,
                                                              java.util.concurrent.TimeUnit timeUnit)

      Add a shutdown hook to wait for thread completion in the given `service`. This is useful if the given service uses daemon threads, and we want to keep the JVM from exiting immediately on shutdown, instead giving these daemon threads a chance to terminate normally.
      Parameters:
        `service` - ExecutorService which uses daemon threads
        `terminationTimeout` - how long to wait for the executor to finish before terminating the JVM
        `timeUnit` - unit of time for the time parameter

    - #### getExitingExecutorService

          @Beta
          @GwtIncompatible(value="concurrency")
          public static java.util.concurrent.ExecutorService getExitingExecutorService(java.util.concurrent.ThreadPoolExecutor executor)

      Converts the given ThreadPoolExecutor into an ExecutorService that exits when the application is complete. It does so by using daemon threads and adding a shutdown hook to wait for their completion.

      This method waits 120 seconds before continuing with JVM termination, even if the executor has not finished its work.

      This is mainly for fixed thread pools. See `Executors.newFixedThreadPool(int)`.

      Parameters:
        `executor` - the executor to modify to make sure it exits when the application is finished
      Returns:
        an unmodifiable version of the input which will not hang the JVM

    - #### getExitingScheduledExecutorService

          @Beta
          @GwtIncompatible(value="TODO")
          public static java.util.concurrent.ScheduledExecutorService getExitingScheduledExecutorService(java.util.concurrent.ScheduledThreadPoolExecutor executor)

      Converts the given ThreadPoolExecutor into a ScheduledExecutorService that exits when the application is complete. It does so by using daemon threads and adding a shutdown hook to wait for their completion.

      This method waits 120 seconds before continuing with JVM termination, even if the executor has not finished its work.

      This is mainly for fixed thread pools. See `Executors.newScheduledThreadPool(int)`.

      Parameters:
        `executor` - the executor to modify to make sure it exits when the application is finished
      Returns:
        an unmodifiable version of the input which will not hang the JVM

    - #### sameThreadExecutor

          @Deprecated
          @GwtIncompatible(value="TODO")
          public static ListeningExecutorService sameThreadExecutor()

      Deprecated. Use `directExecutor()` if you only require an `Executor` and `newDirectExecutorService()` if you need a `ListeningExecutorService`. This method will be removed in August 2016.
      Creates an executor service that runs each task in the thread that invokes `execute/submit`, as in `ThreadPoolExecutor.CallerRunsPolicy`. This applies both to individually submitted tasks and to collections of tasks submitted via `invokeAll` or `invokeAny`. In the latter case, tasks will run serially on the calling thread. Tasks are run to completion before a `Future` is returned to the caller (unless the executor has been shutdown).

      Although all tasks are immediately executed in the thread that submitted the task, this `ExecutorService` imposes a small locking overhead on each task submission in order to implement shutdown and termination behavior.

      The implementation deviates from the `ExecutorService` specification with regards to the `shutdownNow` method. First, "best-effort" with regards to canceling running tasks is implemented as "no-effort". No interrupts or other attempts are made to stop threads executing tasks. Second, the returned list will always be empty, as any submitted task is considered to have started execution. This applies also to tasks given to `invokeAll` or `invokeAny` which are pending serial execution, even the subset of the tasks that have not yet started execution. It is unclear from the `ExecutorService` specification if these should be included, and it's much easier to implement the interpretation that they not be. Finally, a call to `shutdown` or `shutdownNow` may result in concurrent calls to `invokeAll/invokeAny` throwing RejectedExecutionException, although a subset of the tasks may already have been executed.

      Since:
        10.0 (mostly source-compatible since 3.0)

    - #### newDirectExecutorService

          @GwtIncompatible(value="TODO")
          public static ListeningExecutorService newDirectExecutorService()

      Creates an executor service that runs each task in the thread that invokes `execute/submit`, as in `ThreadPoolExecutor.CallerRunsPolicy` This applies both to individually submitted tasks and to collections of tasks submitted via `invokeAll` or `invokeAny`. In the latter case, tasks will run serially on the calling thread. Tasks are run to completion before a `Future` is returned to the caller (unless the executor has been shutdown).

      Although all tasks are immediately executed in the thread that submitted the task, this `ExecutorService` imposes a small locking overhead on each task submission in order to implement shutdown and termination behavior.

      The implementation deviates from the `ExecutorService` specification with regards to the `shutdownNow` method. First, "best-effort" with regards to canceling running tasks is implemented as "no-effort". No interrupts or other attempts are made to stop threads executing tasks. Second, the returned list will always be empty, as any submitted task is considered to have started execution. This applies also to tasks given to `invokeAll` or `invokeAny` which are pending serial execution, even the subset of the tasks that have not yet started execution. It is unclear from the `ExecutorService` specification if these should be included, and it's much easier to implement the interpretation that they not be. Finally, a call to `shutdown` or `shutdownNow` may result in concurrent calls to `invokeAll/invokeAny` throwing RejectedExecutionException, although a subset of the tasks may already have been executed.

      Since:
        18.0 (present as MoreExecutors.sameThreadExecutor() since 10.0)

    - #### directExecutor

          public static java.util.concurrent.Executor directExecutor()

      Returns an `Executor` that runs each task in the thread that invokes `execute`, as in `ThreadPoolExecutor.CallerRunsPolicy`.

      This instance is equivalent to:

             final class DirectExecutor implements Executor {
               public void execute(Runnable r) {
                 r.run();
               }
             }

      This should be preferred to `newDirectExecutorService()` because the implementing the `ExecutorService` subinterface necessitates significant performance overhead.

      Since:
        18.0

    - #### listeningDecorator

          @GwtIncompatible(value="TODO")
          public static ListeningExecutorService listeningDecorator(java.util.concurrent.ExecutorService delegate)

      Creates an `ExecutorService` whose `submit` and `invokeAll` methods submit `ListenableFutureTask` instances to the given delegate executor. Those methods, as well as `execute` and `invokeAny`, are implemented in terms of calls to `delegate.execute`. All other methods are forwarded unchanged to the delegate. This implies that the returned `ListeningExecutorService` never calls the delegate's `submit`, `invokeAll`, and `invokeAny` methods, so any special handling of tasks must be implemented in the delegate's `execute` method or by wrapping the returned `ListeningExecutorService`.

      If the delegate executor was already an instance of `ListeningExecutorService`, it is returned untouched, and the rest of this documentation does not apply.

      Since:
        10.0

    - #### listeningDecorator

          @GwtIncompatible(value="TODO")
          public static ListeningScheduledExecutorService listeningDecorator(java.util.concurrent.ScheduledExecutorService delegate)

      Creates a `ScheduledExecutorService` whose `submit` and `invokeAll` methods submit `ListenableFutureTask` instances to the given delegate executor. Those methods, as well as `execute` and `invokeAny`, are implemented in terms of calls to `delegate.execute`. All other methods are forwarded unchanged to the delegate. This implies that the returned `ListeningScheduledExecutorService` never calls the delegate's `submit`, `invokeAll`, and `invokeAny` methods, so any special handling of tasks must be implemented in the delegate's `execute` method or by wrapping the returned `ListeningScheduledExecutorService`.

      If the delegate executor was already an instance of `ListeningScheduledExecutorService`, it is returned untouched, and the rest of this documentation does not apply.

      Since:
        10.0

    - #### platformThreadFactory

          @Beta
          @GwtIncompatible(value="concurrency")
          public static java.util.concurrent.ThreadFactory platformThreadFactory()

      Returns a default thread factory used to create new threads.

      On AppEngine, returns `ThreadManager.currentRequestThreadFactory()`. Otherwise, returns `Executors.defaultThreadFactory()`.

      Since:
        14.0

    - #### shutdownAndAwaitTermination

          @Beta
          @GwtIncompatible(value="concurrency")
          public static boolean shutdownAndAwaitTermination(java.util.concurrent.ExecutorService service,
                                                                      long timeout,
                                                                      java.util.concurrent.TimeUnit unit)

      Shuts down the given executor gradually, first disabling new submissions and later cancelling existing tasks.

      The method takes the following steps:

      1. calls `ExecutorService.shutdown()`, disabling acceptance of new submitted tasks.
      2. waits for half of the specified timeout.
      3. if the timeout expires, it calls `ExecutorService.shutdownNow()`, cancelling pending tasks and interrupting running tasks.
      4. waits for the other half of the specified timeout.

      If, at any step of the process, the calling thread is interrupted, the method calls `ExecutorService.shutdownNow()` and returns.

      Parameters:
        `service` - the `ExecutorService` to shut down
        `timeout` - the maximum time to wait for the `ExecutorService` to terminate
        `unit` - the time unit of the timeout argument
      Returns:
        `true` if the `ExecutorService` was terminated successfully, `false` the call timed out or was interrupted
      Since:
        17.0