Fork/Join(3)：ForkJoinPool之API翻译

Fork/Join(3)：ForkJoinPool之API翻译

ForkJoinPool是Fork/Join框架的两大核心类之一，这一节先翻译API，具体使用方法和实现原理留待后续章节再谈。

虽然fork/join框架从JDK1.7开始就已经存在，但介绍Fork/Join框架的文章比较少，且大多数都是简单应用。要学习一个框架，从API文档开始或许是一个不错的方式。

特别说明：英文版本来源于JDK1.8_40 API。

第一次尝试翻译英文技术文档，翻译可能并不准确，所以保留了英文。如有错误还望指正！谢谢！

以下为翻译内容：

 

An ExecutorService for runningForkJoinTasks. AForkJoinPool provides the entry point for submissions from non-ForkJoinTask clients, as well as management and monitoring operations.

A ForkJoinPool differs from other kinds ofExecutorService mainly by virtue of employingwork-stealing: all threads in the pool attempt to find and execute tasks submitted to the pool and/or created by other active tasks (eventually blocking waiting for work if none exist). This enables efficient processing when most tasks spawn other subtasks (as do mostForkJoinTasks), as well as when many small tasks are submitted to the pool from external clients. Especially when settingasyncMode to true in constructors,ForkJoinPools may also be appropriate for use with event-style tasks that are never joined.

A static commonPool() is available and appropriate for most applications. The common pool is used by any ForkJoinTask that is not explicitly submitted to a specified pool. Using the common pool normally reduces resource usage (its threads are slowly reclaimed during periods of non-use, and reinstated upon subsequent use).

一个运行ForkJoinTask的ExecutorService，ForkJoinPool 提供了非ForkJoinTask客户端的提交入口及管理监控操作。

ForkJoinPool与其它类型的ExecutorService相比，其主要的不同在于采用了工作窃取算法(work-stealing)：所有池中线程会尝试找到并执行已被提交到池中的或由其他活动任务创建的任务（阻塞直到没有任务存在）。这使得能够有效地处理以下情景：大多数由任务产生大量子任务的情况(譬如ForkJoinTasks)；从外部客户端大量提交小任务到池中的情况。特别强调，如在构造函数中将asyncMode(异步模式)设置为true，当其未被加入时，ForkJoinPools也可适当用于事件式任务。

静态方法commonPool()可适用于大多数应用程序。common pool用于任意没有明确提交到指定池的ForkJoinTask。使用common pool通常可降低资源占用(周期内未被使用的线程会被缓慢回收,并回复可用状态)。

 

For applications that require separate or custom pools, aForkJoinPool may be constructed with a given target parallelism level; by default, equal to the number of available processors. The pool attempts to maintain enough active (or available) threads by dynamically adding, suspending, or resuming internal worker threads, even if some tasks are stalled waiting to join others. However, no such adjustments are guaranteed in the face of blocked I/O or other unmanaged synchronization. The nested ForkJoinPool.ManagedBlocker interface enables extension of the kinds of synchronization accommodated.

In addition to execution and lifecycle control methods, this class provides status check methods (for examplegetStealCount()) that are intended to aid in developing, tuning, and monitoring fork/join applications. Also, methodtoString() returns indications of pool state ina convenient form for informal monitoring.

As is the case with other ExecutorServices, there are three main task execution methods summarized in the following table. These are designed to be used primarily by clients not already engaged in fork/join computations in the current pool. The main forms of these methods accept instances ofForkJoinTask, but overloaded forms also allow mixed execution of plainRunnable- orCallable- based activities as well. However, tasks that are already executing in a pool should normally instead use the within-computation forms listed in the table unless using async event-style tasks that are not usually joined, in which case there is little difference among choice of methods.

如需自定义应用或者线程池，ForkJoinPool可以使用给定的并行度，默认值是可用的处理器数量。线程池通过动态添加、暂停或恢复内部工作线程来保持足够的活动(或可用)线程，即使某些任务在等待加入时处于停滞状态。通常，阻塞I/O或非托管同步并没有提供调节机制，嵌套接口类ForkJoinPool.ManagedBlocker是可扩展的同步容器。

除了执行任务和控制生命周期的方法，还提供了状态检查方法（如getstealcount()），旨在帮助开发、调试、监测Fork/join应用，而tostring()方法则在适当的时点从非正式监控状态中返回线程池状态标识。

与其他executorservice比较,有三个主要任务执行方法总结在下表中。这些设计主要用于运行还未在当前线程池中的fork/join任务。这些方法主要接受forkjointask实例，但重载形式也允许混合执行Runnable或Callable任务。通常，任务在池中运行时采用表中列出的执行方式，因此除非采用异步事件任务方式，否则不会执行join操作，在此情况下，这些方法之间只有少许区别。

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() (ForkJoinTasksare Futures)

 

common pool的默认构造方法采用默认参数，但有三个系统参数可选:

java.util.concurrent.ForkJoinPool.common.parallelism -并行级别(非负整数)

java.util.concurrent.ForkJoinPool.common.threadFactory -ForkJoin线程工厂 ForkJoinPool.ForkJoinWorkerThreadFactory 

java.util.concurrent.ForkJoinPool.common.exceptionHandler -未捕获异常持有器Thread.UncaughtExceptionHandler 

 

If a SecurityManager is present and no factory is specified, then the default pool uses a factory supplying threads that have no Permissions enabled. The system class loader is used to load these classes. Upon any error in establishing these settings, default parameters are used. It is possible to disable or limit the use of threads in the common pool by setting the parallelism property to zero, and/or using a factory that may returnnull. However doing so may cause unjoined tasks to never be executed.

如果存在SecurityManager，且未指定线程工厂，则默认池将没有权限启用工厂提供线程。系统类加载器用于加载这些类。在建立这些设置时发生任何错误，将使用默认参数。通过将并行属性设置为零，或使用可能返回null的工厂，可以禁用或限制common pool中线程使用，但这样做可能导致未加入的任务从不执行。

 

Implementation notes:

This implementation restricts the maximum number of running threads to 32767. Attempts to create pools with greater than the maximum number result inIllegalArgumentException.

This implementation rejects submitted tasks (that is, by throwingRejectedExecutionException) only when the pool is shut down or internal resources have been exhausted.

实现说明：

此实现限制运行线程的最大数量为32767，试图创建超过最大数量的线程时将抛出IllegalArgumentException。只有当线程池关闭或内部资源枯竭才会拒绝提交任务(抛出RejectedExecutionException)

Since: 1.7

 

嵌套类摘要

Nested Classes
Modifier and Type	Class and Description
static interface	ForkJoinPool.ForkJoinWorkerThreadFactory  创建新的ForkJoinWorkerThreads的工厂
static interface	ForkJoinPool.ManagedBlocker  ForkJoinPools用于扩展并行级别管理的接口 Interface for extending managed parallelism for tasks running inForkJoinPools.

 

属性摘要

Fields
Modifier and Type	Field and Description
static ForkJoinPool.ForkJoinWorkerThreadFactory	defaultForkJoinWorkerThreadFactory  创建一个新的ForkJoinWorkerThread。

 

构造方法摘要

Constructors

Constructor and Description

ForkJoinPool()  创建一个ForkJoinPool：使用Runtime.availableProcessors()获取的数值作为并行级别；使用默认的default thread factory；UncaughtExceptionHandler为空；非异步LIFO模式。

ForkJoinPool(int parallelism)  创建一个ForkJoinPool：使用指定数值作为并行级别；使用默认的default thread factory；UncaughtExceptionHandler为空；非异步LIFO模式。

ForkJoinPool(int parallelism,ForkJoinPool.ForkJoinWorkerThreadFactory factory,Thread.UncaughtExceptionHandler handler, boolean asyncMode)  使用指定参数创建一个ForkJoinPool。

 

方法摘要

All Methods
Modifier and Type	Method and Description
boolean	awaitQuiescence(long timeout,TimeUnit unit)  如果被此池中的ForkJoinTask调用，等价于此方法： ForkJoinTask.helpQuiesce()。 If called by a ForkJoinTask operating in this pool, equivalent in effect toForkJoinTask.helpQuiesce().
boolean	awaitTermination(long timeout,TimeUnit unit)  阻塞直到所有任务执行完毕。当任意以下情况出现则停止阻塞，以先发生为准：收到关闭请求、超时、线程中断。 Blocks until all tasks have completed execution after a shutdown request, or the timeout occurs, or the current thread is interrupted, whichever happens first.
static ForkJoinPool	commonPool() 返回common pool 实例。 Returns the common pool instance.
protected int