模块  java.base
软件包  java.util.concurrent

Class ForkJoinPool

  • 实现的所有接口
    Executor ， ExecutorService 
    public class ForkJoinPool
extends AbstractExecutorService
    一个ExecutorService运行ForkJoinTask秒。 ForkJoinPool提供了非ForkJoinTask客户端提交的入口点，以及管理和监视操作。

    一个ForkJoinPool与其他种类的不同ExecutorService主要凭借用人偷盗的：所有的线程池中试图找到并执行其他活动任务提交到池和/或创建（最终阻塞等待工作，如果不存在）的任务。 当大多数任务产生其他子任务时（如大多数ForkJoinTask ），以及从外部客户端向池提交许多小任务时，这可以实现高效处理。 尤其是在构造函数设置asyncMode为真时， ForkJoinPool S还可能适合于与事件式的任务中使用那些从未加入。 所有工作线程都使用Thread.isDaemon() set true进行初始化。

    静态commonPool()适用于大多数应用程序。 公共池由未显式提交到指定池的任何ForkJoinTask使用。 使用公共池通常会减少资源使用（其线程在不使用期间缓慢回收，并在后续使用时恢复）。

    对于需要单独或自定义池的应用程序，可以构造具有给定目标并行度级别的ForkJoinPool ; 默认情况下，等于可用处理器的数量。 池尝试通过动态添加，挂起或恢复内部工作线程来维护足够的活动（或可用）线程，即使某些任务停止等待加入其他任务也是如此。 但是，面对阻塞的I / O或其他非托管同步，不能保证这样的调整。 嵌套的ForkJoinPool.ManagedBlocker接口可以扩展所容纳的同步类型。 可以使用具有与类ThreadPoolExecutor中记录的参数对应的参数的构造函数来覆盖默认策略。

    除了执行和生命周期控制方法之外，此类还提供状态检查方法（例如getStealCount() ），旨在帮助开发，调优和监视fork / join应用程序。 而且，方法toString()以方便的形式返回池状态的指示以用于非正式监视。

    与其他ExecutorServices的情况一样，下表总结了三种主要的任务执行方法。 这些主要用于当前池中尚未参与fork / join计算的客户端。 这些方法的主要形式接受ForkJoinTask实例，但重载的表单也允许混合执行基于Runnable或Callable基本活动。 但是，已经在池中执行的任务通常应该使用表中列出的计算内表单，除非使用通常不连接的异步事件样式任务，在这种情况下，方法选择之间几乎没有区别。

    Summary of task execution methods Call from non-fork/join clients Call from within fork/join computations Arrange async execution execute(ForkJoinTask) ForkJoinTask.fork() Await and obtain result invoke(ForkJoinTask) ForkJoinTask.invoke() Arrange exec and obtain Future submit(ForkJoinTask) ForkJoinTask.fork() (ForkJoinTasks are Futures)

    可以通过设置以下system properties来控制用于构造公共池的参数：

    如果没有通过系统属性提供线程工厂，则公共池使用使用系统类加载器的工厂作为thread context class loader 。 此外，如果存在SecurityManager ，则公共池使用提供未启用Permissions的线程的工厂。 如果在建立这些设置时出现任何错误，则使用默认参数。 通过将parallelism属性设置为零和/或使用可能返回null的工厂，可以禁用或限制公共池中线程的使用。 但是，这样做可能会导致永远不会执行未连接的任务。

    实施说明 ：此实现将最大运行线程数限制为32767.尝试创建大于最大数量的池将导致IllegalArgumentException 。

    仅当池关闭或内部资源耗尽时，此实现才会拒绝提交的任务（即通过抛出RejectedExecutionException ）。

    从以下版本开始：
    1.7

    • 字段详细信息

      • defaultForkJoinWorkerThreadFactory

        public static final ForkJoinPool.ForkJoinWorkerThreadFactory defaultForkJoinWorkerThreadFactory
        创建一个新的ForkJoinWorkerThread。 除非在ForkJoinPool构造函数中重写，否则将使用此工厂。

    • 构造方法详细信息

      • ForkJoinPool

        public ForkJoinPool​(int parallelism,
                    ForkJoinPool.ForkJoinWorkerThreadFactory factory,
                    Thread.UncaughtExceptionHandler handler,
                    boolean asyncMode,
                    int corePoolSize,
                    int maximumPoolSize,
                    int minimumRunnable,
                    Predicate<? super ForkJoinPool> saturate,
                    long keepAliveTime,
                    TimeUnit unit)
        使用给定参数创建 ForkJoinPool 。
        参数
        parallelism - 并行度级别。 对于默认值，请使用Runtime.availableProcessors() 。
        factory - 用于创建新线程的工厂。 对于默认值，请使用defaultForkJoinWorkerThreadFactory 。
        handler - 由于执行任务时遇到不可恢复的错误而终止的内部工作线程的处理程序。 对于默认值，请使用null 。
        asyncMode - 如果为true，则为从未加入的分叉任务建立本地先进先出调度模式。 在工作线程仅处理事件样式异步任务的应用程序中，此模式可能比默认的基于本地堆栈的模式更合适。 对于默认值，请使用false 。
        corePoolSize - 要保留在池中的线程数（除非在经过保持活动后超时）。 通常（默认情况下）这是与并行度级别相同的值，但可以设置为更大的值，以便在任务定期阻止时减少动态开销。 使用较小的值（例如0 ）与默认值具有相同的效果。
        maximumPoolSize - 允许的最大线程数。 达到最大值时，尝试替换被阻止的线程失败。 （但是，由于不同线程的创建和终止可能会重叠，并且可能由给定的线程工厂管理，因此可能会暂时超出此值。）要安排与公共池默认使用的值相同的值，请使用256加上parallelism等级。 （默认情况下，公共池最多允许256个备用线程。）使用大于实现的总线程限制的值（例如Integer.MAX_VALUE ）与使用此限制（默认值）具有相同的效果。
        minimumRunnable - 未被连接阻止的最小允许核心线程数或ForkJoinPool.ManagedBlocker 。 为了确保进度，当存在太少的未阻塞线程且可能存在未执行的任务时，将构造新线程，直到给定的maximumPoolSize。 对于默认值，请使用1来确保活跃度。 较大的值可能会在存在阻塞活动时提高吞吐量，但可能不会因为增加的开销而增加。 当提交的任务不具有需要额外线程的依赖项时，值为零可能是可接受的。
        saturate - 如果为非null，则在尝试创建超过最大允许总线程数时调用谓词。 默认情况下，当线程即将在某个连接或ForkJoinPool.ManagedBlocker上阻塞 ，但由于将超过maximumPoolSize而无法替换时，将引发RejectedExecutionException 。 但是，如果此谓词返回true ，则不会抛出任何异常，因此池继续以少于目标可运行线程数运行，这可能无法确保进度。
        keepAliveTime - 线程终止之前上次使用后经过的时间（如果需要，稍后再替换）。 对于默认值，请使用60, TimeUnit.SECONDS 。
        unit - keepAliveTime参数的时间单位
        异常
        IllegalArgumentException - 如果并行度小于或等于零，或者大于实现限制，或者如果maximumPoolSize小于并行度，则keepAliveTime小于或等于零。
        NullPointerException - 如果工厂为空
        SecurityException - 如果存在安全管理器并且不允许调用者修改线程，因为它不符合RuntimePermission ("modifyThread")
        从以下版本开始：
        9

    • 方法详细信息

      • commonPool

        public static ForkJoinPool commonPool()
        返回公共池实例。 这个游泳池是静态建造的; 其运行状态不受shutdown()或shutdownNow()的尝试影响。 但是，在程序System.exit(int)上，此池和任何正在进行的处理将自动终止。 任何依赖异步任务处理在程序终止之前完成的程序应在退出之前调用commonPool(). awaitQuiescence 。
        结果
        公共池实例
        从以下版本开始：
        1.8

      • invoke

        public <T> T invoke​(ForkJoinTask<T> task)
        执行给定任务，完成后返回结果。 如果计算遇到未经检查的异常或错误，则将其重新作为此调用的结果。 Rethrown异常的行为方式与常规异常相同，但在可能的情况下，包含当前线程以及实际遇到异常的线程的堆栈跟踪（如使用ex.printStackTrace()显示）; 最低限度只有后者。
        参数类型
        T - 任务结果的类型
        参数
        task - 任务
        结果
        任务的结果
        异常
        NullPointerException - 如果任务为空
        RejectedExecutionException - 如果无法安排任务执行

      • execute

        public void execute​(Runnable task)
        从界面复制的说明： Executor
        在将来的某个时间执行给定的命令。 该命令可以在新线程，池化线程或调用线程中执行，由Executor实现自行决定。
        参数
        task - 可运行的任务
        异常
        NullPointerException - 如果任务为空
        RejectedExecutionException - 如果无法安排任务执行

      • submit

        public <T> ForkJoinTask<T> submit​(Callable<T> task)
        从界面复制的说明： ExecutorService
        提交值返回任务以执行并返回表示任务的挂起结果的Future。 Future的get方法将在成功完成后返回任务的结果。

        如果您想立即阻止等待任务，可以使用result = exec.submit(aCallable).get();表单的result = exec.submit(aCallable).get();

        注意： Executors类包含一组方法，可以将一些其他常见的类似闭包的对象（例如， PrivilegedAction）转换为Callable表单，以便可以提交它们。

        Specified by:
        submit在界面 ExecutorService
        重写：
        submit类 AbstractExecutorService
        参数类型
        T - 任务结果的类型
        参数
        task - 要提交的任务
        结果
        表示未完成任务的Future
        异常
        NullPointerException - 如果任务为空
        RejectedExecutionException - 如果无法安排任务执行

      • invokeAll

        public <T> List<Future<T>> invokeAll​(Collection<? extends Callable<T>> tasks)
        从界面复制的说明： ExecutorService
        执行给定的任务，返回完成所有状态和结果的Futures列表。 对于返回列表的每个元素， Future.isDone()是true 。 请注意，已完成的任务可能正常终止或通过抛出异常终止。 如果在此操作正在进行时修改了给定集合，则此方法的结果未定义。
        参数类型
        T - 从任务返回的值的类型
        参数
        tasks - 任务集合
        结果
        表示任务的Futures列表，与迭代器为给定任务列表生成的顺序相同，每个已完成
        异常
        NullPointerException - 如果任务或其任何元素是 null
        RejectedExecutionException - 如果无法安排任何任务执行

      • getUncaughtExceptionHandler

        public Thread.UncaughtExceptionHandler getUncaughtExceptionHandler()
        返回由于执行任务时遇到不可恢复的错误而终止的内部工作线程的处理程序。
        结果
        处理程序，如果没有， null

      • getParallelism

        public int getParallelism()
        返回此池的目标并行级别。
        结果
        此池的目标并行级别

      • getCommonPoolParallelism

        public static int getCommonPoolParallelism()
        返回公共池的目标并行级别。
        结果
        公共池的目标并行度级别
        从以下版本开始：
        1.8

      • getPoolSize

        public int getPoolSize()
        返回已启动但尚未终止的工作线程数。 此方法返回的结果可能与getParallelism()不同， 此时创建线程以在其他方式被协同阻止时保持并行性。
        结果
        工作线程数

      • getAsyncMode

        public boolean getAsyncMode()
        如果此池对从未加入的分叉任务使用本地先进先出调度模式，则返回 true 。
        结果
        true如果此池使用异步模式

      • getRunningThreadCount

        public int getRunningThreadCount()
        返回未等待加入任务或其他托管同步的阻塞的工作线程数的估计值。 此方法可能会高估正在运行的线程数。
        结果
        工作线程数

      • getActiveThreadCount

        public int getActiveThreadCount()
        返回当前窃取或执行任务的线程数的估计值。 此方法可能会高估活动线程的数量。
        结果
        活动线程数

      • isQuiescent

        public boolean isQuiescent()
        如果所有工作线程当前都处于空闲状态，则返回true 。 空闲工作程序是无法获取要执行的任务的工作程序，因为没有可用于从其他线程窃取，并且没有待处理的提交到池中。 这种方法很保守; 它可能不会在所有线程空闲时立即返回true ，但如果线程保持不活动状态，最终将变为true。
        结果
        true如果所有线程当前都处于空闲状态

      • getStealCount

        public long getStealCount()
        返回从另一个线程的工作队列中窃取的任务总数的估计值。 报告的值低估了池不静止时的实际抢断总数。 此值可用于监视和调优fork / join程序：通常，窃取计数应足够高以保持线程忙，但足够低以避免线程上的开销和争用。
        结果
        抢断次数

      • getQueuedTaskCount

        public long getQueuedTaskCount()
        返回工作线程当前在队列中保留的任务总数的估计值（但不包括提交到池中的尚未开始执行的任务）。 此值只是一种近似值，通过迭代池中的所有线程获得。 此方法可用于调整任务粒度。
        结果
        排队任务的数量

      • getQueuedSubmissionCount

        public int getQueuedSubmissionCount()
        返回提交到此池但尚未开始执行的任务数的估计值。 此方法可能需要与提交的数量成比例的时间。
        结果
        排队提交的数量

      • hasQueuedSubmissions

        public boolean hasQueuedSubmissions()
        如果有任何提交到此池的任务尚未开始执行，则返回 true 。
        结果
        true如果有任何排队的提交

      • pollSubmission

        protected ForkJoinTask<?> pollSubmission()
        删除并返回下一个未执行的提交（如果有）。 此方法可用于此类的扩展，该类在具有多个池的系统中重新分配工作。
        结果
        下次提交，如果没有， null

      • drainTasksTo

        protected int drainTasksTo​(Collection<? super ForkJoinTask<?>> c)
        从调度队列中删除所有可用的未执行提交和分叉任务，并将它们添加到给定集合，而不会更改其执行状态。 这些可能包括人工生成或包装的任务。 此方法仅在已知池处于静止状态时才会调用。 其他时间的调用可能无法删除所有任务。 尝试将元素添加到集合c遇到的故障可能导致在抛出关联的异常时元素既不在集合中，也不在集合中。 如果在操作正在进行时修改了指定的集合，则此操作的行为是不确定的。
        参数
        c - 将元素转移到的集合
        结果
        转移的元素数量

      • toString

        public String toString()
        返回标识此池及其状态的字符串，包括运行状态，并行度级别以及工作和任务计数的指示。
        重写：
        toString在类 Object
        结果
        标识此池的字符串及其状态

      • shutdown

        public void shutdown()
        可能会启动有序关闭，其中先前提交的任务将被执行，但不会接受任何新任务。 如果这是commonPool() ，则调用对执行状态没有影响，如果已经关闭，则调用没有其他影响。 在此方法过程中同时提交的任务可能会也可能不会被拒绝。
        异常
        SecurityException - 如果存在安全管理器并且不允许调用者修改线程，因为它不能保留RuntimePermission ("modifyThread")

      • shutdownNow

        public List<Runnable> shutdownNow()
        可能尝试取消和/或停止所有任务，并拒绝所有后续提交的任务。 如果这是commonPool() ，则调用对执行状态没有影响，如果已经关闭，则调用没有其他影响。 否则，在此方法过程中同时提交或执行的任务可能会也可能不会被拒绝。 此方法取消现有和未执行的任务，以便在存在任务依赖性时允许终止。 所以该方法总是返回一个空列表（与其他一些Executors的情况不同）。
        结果
        一个空列表
        异常
        SecurityException - 如果存在安全管理器并且不允许调用者修改线程，因为它不能保存RuntimePermission ("modifyThread")

      • isTerminated

        public boolean isTerminated()
        如果关闭后所有任务都已完成，则返回 true 。
        结果
        true如果关闭后所有任务都已完成

      • isTerminating

        public boolean isTerminating()
        如果终止过程已经开始但尚未完成，则返回true 。 此方法可用于调试。 返回true报告在关闭后足够的时间段可能表示已提交的任务已忽略或抑制中断，或正在等待I / O，导致此执行程序无法正常终止。 （参见ForkJoinTask类的咨询说明，说明任务通常不应该包含阻塞操作。但是如果它们这样做，它们必须在中断时中止它们。）
        结果
        true如果终止但尚未终止

      • isShutdown

        public boolean isShutdown()
        如果此池已关闭，则返回 true 。
        结果
        如果此池已关闭， true

      • awaitTermination

        public boolean awaitTermination​(long timeout,
                                TimeUnit unit)
                         throws InterruptedException
        阻止所有任务在关闭请求之后完成执行，或发生超时，或者当前线程被中断，以先发生者为准。 因为commonPool()永远不会终止，直到程序关闭，当应用于公共池时，此方法等效于awaitQuiescence(long, TimeUnit)但始终返回false 。
        参数
        timeout - 等待的最长时间
        unit - 超时参数的时间单位
        结果
        true如果此执行终止， false ，如果超时终止前经过
        异常
        InterruptedException - 如果在等待时被打断

      • awaitQuiescence

        public boolean awaitQuiescence​(long timeout,
                               TimeUnit unit)
        如果在此池中运行的ForkJoinTask调用，则等效于ForkJoinTask.helpQuiesce() 。 否则，等待和/或尝试协助执行任务，直到此池isQuiescent()或指示的超时过去。
        参数
        timeout - 等待的最长时间
        unit - 超时参数的时间单位
        结果
        true如果静止; false如果超时已超时。

      • managedBlock

        public static void managedBlock​(ForkJoinPool.ManagedBlocker blocker)
                         throws InterruptedException
        运行给定的可能阻塞任务。 当running in a ForkJoinPool时 ，此方法可能会安排在必要时激活备用线程，以确保当前线程在blocker.block()中被阻止时具有足够的并行性 。

        此方法重复调用blocker.isReleasable()和blocker.block()直到任一方法返回true 。 每次拨打blocker.block()之前，都会调用blocker.isReleasable() ，并返回false 。

        如果没有在ForkJoinPool中运行，则此方法在行为上等效于 

           while (!blocker.isReleasable()) if (blocker.block()) break;
        如果在ForkJoinPool中运行，则可以首先扩展池以确保在调用blocker.block()期间有足够的并行blocker.block() 。
        参数
        blocker - 阻止任务
        异常
        InterruptedException - 如果 blocker.block()这样做了