Module java.base
Package java.util.concurrent

Class ScheduledThreadPoolExecutor

java.lang.Object
java.util.concurrent.AbstractExecutorService
java.util.concurrent.ThreadPoolExecutor
java.util.concurrent.ScheduledThreadPoolExecutor
所有已实现的接口:
AutoCloseable, Executor, ExecutorService, ScheduledExecutorService
public class ScheduledThreadPoolExecutor extends ThreadPoolExecutor implements ScheduledExecutorService
一个可以在给定延迟后调度命令运行或定期执行的ThreadPoolExecutor。当需要多个工作线程或需要ThreadPoolExecutor的额外灵活性或功能时，此类优于Timer。

延迟任务执行不会早于启用它们，但在启用后，对它们何时开始没有实时保证。安排在完全相同执行时间的任务按照提交的先进先出（FIFO）顺序启用。

当提交的任务在运行之前被取消时，执行将被抑制。默认情况下，这样一个被取消的任务直到其延迟过去之前不会自动从工作队列中移除。虽然这样可以进行进一步的检查和监控，但也可能导致被取消的任务无限期地保留。为了避免这种情况，使用setRemoveOnCancelPolicy(boolean)使任务在取消时立即从工作队列中移除。

通过scheduleAtFixedRate或scheduleWithFixedDelay调度的周期性任务的连续执行不会重叠。虽然不同的执行可能由不同的线程执行，但先前执行的效果在后续执行之前发生happen-before。

虽然此类继承自ThreadPoolExecutor，但一些继承的调整方法对它并不实用。特别是，因为它作为一个使用corePoolSize线程和无界队列的固定大小池，调整maximumPoolSize没有实际效果。此外，将corePoolSize设置为零或使用allowCoreThreadTimeOut几乎从不是一个好主意，因为这可能会导致池在任务变得可运行后没有线程来处理任务。

与ThreadPoolExecutor一样，如果没有另外指定，此类使用Executors.defaultThreadFactory()作为默认线程工厂，并使用ThreadPoolExecutor.AbortPolicy作为默认的拒绝执行处理程序。

扩展说明: 此类重写了execute和submit方法，生成内部ScheduledFuture对象来控制每个任务的延迟和调度。为了保留功能，子类中这些方法的任何进一步重写必须调用超类版本，这有效地禁用了额外的任务定制。但是，此类提供了替代的受保护扩展方法decorateTask（每个Runnable和Callable各一个版本），可用于自定义用于执行通过execute、submit、schedule、scheduleAtFixedRate和scheduleWithFixedDelay输入的命令的具体任务类型。默认情况下，ScheduledThreadPoolExecutor使用扩展FutureTask的任务类型。但是，可以使用以下形式的子类修改或替换它：

 
 public class CustomScheduledExecutor extends ScheduledThreadPoolExecutor {

   static class CustomTask<V> implements RunnableScheduledFuture<V> { ... }

   protected <V> RunnableScheduledFuture<V> decorateTask(
                Runnable r, RunnableScheduledFuture<V> task) {
       return new CustomTask<V>(r, task);
   }

   protected <V> RunnableScheduledFuture<V> decorateTask(
                Callable<V> c, RunnableScheduledFuture<V> task) {
       return new CustomTask<V>(c, task);
   }
   // ... add constructors, etc.
 }
自从:
1.5

  • Constructor Details

    • ScheduledThreadPoolExecutor

      public ScheduledThreadPoolExecutor(int corePoolSize)
      创建一个具有给定核心池大小的新ScheduledThreadPoolExecutor。
      参数:
      corePoolSize - 保留在池中的线程数，即使它们处于空闲状态，除非设置了allowCoreThreadTimeOut
      抛出:
      IllegalArgumentException - 如果corePoolSize < 0

    • ScheduledThreadPoolExecutor

      public ScheduledThreadPoolExecutor(int corePoolSize, ThreadFactory threadFactory)
      创建一个具有给定初始参数的新ScheduledThreadPoolExecutor。
      参数:
      corePoolSize - 保留在池中的线程数，即使它们处于空闲状态，除非设置了allowCoreThreadTimeOut
      threadFactory - 执行程序创建新线程时使用的工厂
      抛出:
      IllegalArgumentException - 如果corePoolSize < 0
      NullPointerException - 如果threadFactory为null

    • ScheduledThreadPoolExecutor

      public ScheduledThreadPoolExecutor(int corePoolSize, RejectedExecutionHandler handler)
      创建一个具有给定初始参数的新ScheduledThreadPoolExecutor。
      参数:
      corePoolSize - 保留在池中的线程数，即使它们处于空闲状态，除非设置了allowCoreThreadTimeOut
      handler - 当执行由于线程边界和队列容量达到而被阻塞时使用的处理程序
      抛出:
      IllegalArgumentException - 如果corePoolSize < 0
      NullPointerException - 如果handler为null

    • ScheduledThreadPoolExecutor

      public ScheduledThreadPoolExecutor(int corePoolSize, ThreadFactory threadFactory, RejectedExecutionHandler handler)
      创建一个具有给定初始参数的新ScheduledThreadPoolExecutor。
      参数:
      corePoolSize - 保留在池中的线程数，即使它们处于空闲状态，除非设置了allowCoreThreadTimeOut
      threadFactory - 执行程序创建新线程时使用的工厂
      handler - 当执行由于线程边界和队列容量达到而被阻塞时使用的处理程序
      抛出:
      IllegalArgumentException - 如果corePoolSize < 0
      NullPointerException - 如果threadFactory或handler为null

  • Method Details

    • decorateTask

      protected <V> RunnableScheduledFuture<V> decorateTask(Runnable runnable, RunnableScheduledFuture<V> task)
      修改或替换用于执行可运行任务的任务。此方法可用于覆盖用于管理内部任务的具体类。默认实现只是返回给定的任务。
      类型参数:
      V - 任务结果的类型
      参数:
      runnable - 提交的Runnable
      task - 用于执行runnable的任务
      返回:
      可以执行runnable的任务
      自1.6起:
      1.6

    • decorateTask

      protected <V> RunnableScheduledFuture<V> decorateTask(Callable<V> callable, RunnableScheduledFuture<V> task)
      修改或替换用于执行可调用的任务。此方法可用于覆盖用于管理内部任务的具体类。默认实现只是返回给定的任务。
      类型参数:
      V - 任务结果的类型
      参数:
      callable - 提交的Callable
      task - 用于执行callable的任务
      返回:
      可以执行callable的任务
      自1.6起:
      1.6

    • schedule

      public ScheduledFuture<?> schedule(Runnable command, long delay, TimeUnit unit)
      从接口复制的描述: ScheduledExecutorService
      提交一个一次性任务，在给定延迟后启用。
      指定者:
      schedule 在接口 ScheduledExecutorService中
      参数:
      command - 要执行的任务
      delay - 从现在开始延迟执行的时间
      unit - 延迟参数的时间单位
      返回:
      代表任务挂起完成的ScheduledFuture，其get()方法在完成时将返回null
      抛出:
      RejectedExecutionException - 如果无法安排任务执行
      NullPointerException - 如果command或unit为null

    • schedule

      public <V> ScheduledFuture<V> schedule(Callable<V> callable, long delay, TimeUnit unit)
      从接口复制的描述: ScheduledExecutorService
      提交一个值返回的一次性任务，在给定延迟后启用。
      指定者:
      schedule 在接口 ScheduledExecutorService中
      类型参数:
      V - callable结果的类型
      参数:
      callable - 要执行的函数
      delay - 从现在开始延迟执行的时间
      unit - initialDelay和period参数的时间单位
      返回:
      代表可以用于提取结果或取消的ScheduledFuture
      抛出:
      RejectedExecutionException - 如果无法安排任务执行
      NullPointerException - 如果callable或unit为null

    • scheduleAtFixedRate

      public ScheduledFuture<?> scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit)
      提交一个周期性操作，首次在给定初始延迟后启用，随后以给定周期启用；也就是说，执行将在initialDelay后开始，然后initialDelay + period，然后initialDelay + 2 * period等等。

      任务执行序列将无限期地继续，直到发生以下异常完成之一：

      后续执行将被抑制。对返回的future上的isDone()的后续调用将返回true。

      如果此任务的任何执行时间超过其周期，则后续执行可能会延迟开始，但不会同时执行。

      指定者:
      scheduleAtFixedRate 在接口 ScheduledExecutorService中
      参数:
      command - 要执行的任务
      initialDelay - 第一次执行的延迟时间
      period - 连续执行之间的周期
      unit - initialDelay和period参数的时间单位
      返回:
      代表一系列重复任务挂起完成的ScheduledFuture。future的get()方法永远不会正常返回，并且在任务取消或任务执行异常终止时将抛出异常。
      抛出:
      RejectedExecutionException - 如果无法安排任务执行
      NullPointerException - 如果command或unit为null
      IllegalArgumentException - 如果period小于或等于零

    • scheduleWithFixedDelay

      public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit)
      提交一个周期性操作，首次在给定初始延迟后启用，随后在一个执行终止和下一个执行开始之间给定的延迟之间启用。

      任务执行序列将无限期地继续，直到发生以下异常完成之一：

      后续执行将被抑制。对返回的future上的isDone()的后续调用将返回true。
      指定者:
      scheduleWithFixedDelay 在接口 ScheduledExecutorService中
      参数:
      command - 要执行的任务
      initialDelay - 第一次执行的延迟时间
      delay - 一个执行终止和下一个执行开始之间的延迟
      unit - initialDelay和delay参数的时间单位
      返回:
      代表一系列重复任务挂起完成的ScheduledFuture。future的get()方法永远不会正常返回，并且在任务取消或任务执行异常终止时将抛出异常。
      抛出:
      RejectedExecutionException - 如果无法安排任务执行
      NullPointerException - 如果command或unit为null
      IllegalArgumentException - 如果delay小于或等于零

    • execute

      public void execute(Runnable command)
      以零所需延迟执行command。这等效于schedule(command, 0, anyUnit)的效果。请注意，对队列和由shutdownNow返回的列表的检查将访问零延迟的ScheduledFuture，而不是command本身。

      使用ScheduledFuture对象的一个后果是，afterExecute始终以null第二个Throwable参数调用，即使command突然终止。相反，可以通过Future.get()获取此类任务抛出的Throwable。

      指定由：
      execute 在接口 Executor中
      覆盖：
      execute 在类 ThreadPoolExecutor中
      参数：
      command - 要执行的任务
      抛出：
      RejectedExecutionException - 由RejectedExecutionHandler自行决定，如果任务无法被接受执行，因为执行程序已关闭
      NullPointerException - 如果command为null

    • submit

      public Future<?> submit(Runnable task)
      从接口复制的描述： ExecutorService
      提交一个Runnable任务以执行，并返回代表该任务的Future。Future的get方法在成功完成时将返回null。
      指定由：
      submit 在接口 ExecutorService中
      覆盖：
      submit 在类 AbstractExecutorService中
      参数：
      task - 要提交的任务
      返回：
      代表任务待完成的Future
      抛出：
      RejectedExecutionException - 如果任务无法被调度执行
      NullPointerException - 如果任务为null

    • submit

      public <T> Future<T> submit(Runnable task, T result)
      从接口复制的描述： ExecutorService
      提交一个Runnable任务以执行，并返回代表该任务的Future。Future的get方法在成功完成时将返回给定的结果。
      指定由：
      submit 在接口 ExecutorService中
      覆盖：
      submit 在类 AbstractExecutorService中
      类型参数：
      T - 结果的类型
      参数：
      task - 要提交的任务
      result - 要返回的结果
      返回：
      代表任务待完成的Future
      抛出：
      RejectedExecutionException - 如果任务无法被调度执行
      NullPointerException - 如果任务为null

    • submit

      public <T> Future<T> submit(Callable<T> task)
      从接口复制的描述： ExecutorService
      提交一个返回值任务以执行，并返回代表任务待完成结果的Future。Future的get方法在成功完成时将返回任务的结果。

      如果您希望立即阻塞等待任务完成，可以使用形式为result = exec.submit(aCallable).get();的结构。

      注意：Executors类包括一组方法，可以将一些其他常见的类似闭包的对象，例如，PrivilegedAction转换为Callable形式，以便提交。

      指定由：
      submit 在接口 ExecutorService中
      覆盖：
      submit 在类 AbstractExecutorService中
      类型参数：
      T - 任务结果的类型
      参数：
      task - 要提交的任务
      返回：
      代表任务待完成的Future
      抛出：
      RejectedExecutionException - 如果任务无法被调度执行
      NullPointerException - 如果任务为null

    • setContinueExistingPeriodicTasksAfterShutdownPolicy

      public void setContinueExistingPeriodicTasksAfterShutdownPolicy(boolean value)
      设置是否在执行程序已关闭后继续执行现有周期性任务的策略。在这种情况下，执行将继续，直到shutdownNow或当已关闭时策略设置为false。默认情况下，此值为false。
      参数：
      value - 如果为true，则在关闭后继续执行，否则不继续
      参见：

    • getContinueExistingPeriodicTasksAfterShutdownPolicy

      public boolean getContinueExistingPeriodicTasksAfterShutdownPolicy()
      获取是否在执行程序已关闭后继续执行现有周期性任务的策略。在这种情况下，执行将继续，直到shutdownNow或当已关闭时策略设置为false。默认情况下，此值为false。
      返回：
      如果在关闭后将继续执行，则为true
      参见：

    • setExecuteExistingDelayedTasksAfterShutdownPolicy

      public void setExecuteExistingDelayedTasksAfterShutdownPolicy(boolean value)
      设置是否在执行程序已关闭后执行现有延迟任务的策略。在这种情况下，这些任务只会在shutdownNow后终止，或在已关闭时将策略设置为false后终止。默认情况下，此值为true。
      参数：
      value - 如果为true，则在关闭后执行，否则不执行
      参见：

    • getExecuteExistingDelayedTasksAfterShutdownPolicy

      public boolean getExecuteExistingDelayedTasksAfterShutdownPolicy()
      获取是否在执行程序已关闭后执行现有延迟任务的策略。在这种情况下，这些任务只会在shutdownNow后终止，或在已关闭时将策略设置为false后终止。默认情况下，此值为true。
      返回：
      如果在关闭后将执行，则为true
      参见：

    • setRemoveOnCancelPolicy

      public void setRemoveOnCancelPolicy(boolean value)
      设置是否应立即在取消时从工作队列中删除取消的任务的策略。默认情况下，此值为false。
      参数：
      value - 如果为true，则在取消时移除，否则不移除
      自1.7起：
      1.7
      参见：

    • getRemoveOnCancelPolicy

      public boolean getRemoveOnCancelPolicy()
      获取是否应立即在取消时从工作队列中删除取消的任务的策略。默认情况下，此值为false。
      返回：
      如果取消的任务立即从队列中移除，则为true
      自1.7起：
      1.7
      参见：

    • shutdown

      public void shutdown()
      启动一个有序的关闭过程，在此过程中将执行先前提交的任务，但不会接受新任务。如果已经关闭，则调用不会有额外效果。

      此方法不会等待先前提交的任务完成执行。使用awaitTermination来完成此操作。

      如果已将ExecuteExistingDelayedTasksAfterShutdownPolicy设置为false，则将取消尚未到期的现有延迟任务。并且除非ContinueExistingPeriodicTasksAfterShutdownPolicy已设置为true，否则将取消现有周期性任务的未来执行。

      指定由：
      shutdown 在接口 ExecutorService中
      覆盖：
      shutdown 在类 ThreadPoolExecutor中
      抛出：
      SecurityException - 如果存在安全管理器，并且关闭此ExecutorService可能操纵调用者无权修改的线程，因为它没有持有RuntimePermission("modifyThread")，或者安全管理器的checkAccess方法拒绝访问。

    • shutdownNow

      public List<Runnable> shutdownNow()
      尝试停止所有正在执行的任务，停止处理等待中的任务，并返回等待执行的任务列表。这些任务在从此方法返回时从任务队列中移除。

      此方法不会等待正在执行的任务终止。使用awaitTermination来实现。

      除了尽力尝试停止处理正在执行的任务外，没有其他保证。此实现通过Thread.interrupt()中断任务；任何未响应中断的任务可能永远不会终止。

      指定由：
      shutdownNow 在接口 ExecutorService中
      覆盖：
      shutdownNow 在类 ThreadPoolExecutor中
      返回：
      从未开始执行的任务列表。此列表的每个元素都是一个ScheduledFuture。对于通过其中一个schedule方法提交的任务，元素将与返回的ScheduledFuture相同。对于使用execute提交的任务，元素将是一个零延迟的ScheduledFuture。
      抛出：
      SecurityException - 如果存在安全管理器，并且关闭此ExecutorService可能操纵调用者无权修改的线程，因为它没有持有RuntimePermission("modifyThread")，或者安全管理器的checkAccess方法拒绝访问。

    • getQueue

      public BlockingQueue<Runnable> getQueue()
      返回此执行程序使用的任务队列。主要用于调试和监视访问任务队列。此队列可能正在使用中。检索任务队列不会阻止排队的任务执行。

      此队列的每个元素都是一个ScheduledFuture。对于通过其中一个schedule方法提交的任务，元素将与返回的ScheduledFuture相同。对于使用execute提交的任务，元素将是一个零延迟的ScheduledFuture。

      对此队列的迭代不能保证按照将执行的顺序遍历任务。

      覆盖：
      getQueue 在类 ThreadPoolExecutor中
      返回：
      任务队列