SI-6032 Enhance TaskSupport documentation.

1 files changed, 49 insertions, 12 deletions

diff --git a/src/library/scala/collection/parallel/TaskSupport.scala b/src/library/scala/collection/parallel/TaskSupport.scala
index 3d27f619bb..b2ff5c9e44 100644
--- a/src/library/scala/collection/parallel/TaskSupport.scala
+++ b/src/library/scala/collection/parallel/TaskSupport.scala
@@ -19,34 +19,71 @@ import scala.concurrent.ExecutionContext
 
 /** A trait implementing the scheduling of
  *  a parallel collection operation.
+ *
+ *  Parallel collections are modular in the way operations are scheduled. Each
+ *  parallel collection is parametrized with a task support object which is
+ *  responsible for scheduling and load-balancing tasks to processors.
  *  
- *  Task support objects handle how a task is split and
- *  distributed across processors. A task support object can be
- *  changed in a parallel collection after it has been created,
- *  but only during a quiescent period, i.e. while there are no
+ *  A task support object can be changed in a parallel collection after it has
+ *  been created, but only during a quiescent period, i.e. while there are no
  *  concurrent invocations to parallel collection methods.
+ *
+ *  There are currently a few task support implementations available for
+ *  parallel collections. The [[scala.collection.parallel.ForkJoinTaskSupport]]
+ *  uses a fork-join pool
+ *  internally and is used by default on JVM 1.6 or greater. The less efficient
+ *  [[scala.collection.parallel.ThreadPoolTaskSupport]] is a fallback for JVM
+ *  1.5 and JVMs that do not support the fork join pools. The
+ *  [[scala.collection.parallel.ExecutionContextTaskSupport]] uses the
+ *  default execution context implementation found in scala.concurrent, and it
+ *  reuses the thread pool used in scala.concurrent (this is either a fork join
+ *  pool or a thread pool executor, depending on the JVM version). The
+ *  execution context task support is set to each parallel collection by
+ *  default, so parallel collections reuse the same fork-join pool as the
+ *  future API.
+ *
+ *  Here is a way to change the task support of a parallel collection:
+ *
+ *  {{{
+ *  import scala.collection.parallel._
+ *  val pc = mutable.ParArray(1, 2, 3)
+ *  pc.tasksupport = new ForkJoinTaskSupport(
+ *    new scala.concurrent.forkjoin.ForkJoinPool(2))
+ *  }}}
+ *
+ *  @see [[http://docs.scala-lang.org/overviews/parallel-collections/configuration.html Configuring Parallel Collections]] section
+ *    on the parallel collection's guide for more information.
  */
 trait TaskSupport extends Tasks
 
 
-/** A task support that uses a fork join pool to schedule tasks */
+/** A task support that uses a fork join pool to schedule tasks.
+ *
+ *  @see [[scala.collection.parallel.TaskSupport]] for more information.
+ */
 class ForkJoinTaskSupport(val environment: ForkJoinPool = ForkJoinTasks.defaultForkJoinPool)
 extends TaskSupport with AdaptiveWorkStealingForkJoinTasks
 
-
-/** A task support that uses a thread pool executor to schedule tasks */
+/** A task support that uses a thread pool executor to schedule tasks.
+ *
+ *  @see [[scala.collection.parallel.TaskSupport]] for more information.
+ */
 class ThreadPoolTaskSupport(val environment: ThreadPoolExecutor = ThreadPoolTasks.defaultThreadPool)
 extends TaskSupport with AdaptiveWorkStealingThreadPoolTasks
 
 
 /** A task support that uses an execution context to schedule tasks.
  *  
- *  It can be used with the default execution context implementation in the `scala.concurrent` package.
- *  It internally forwards the call to either a forkjoin based task support or a thread pool executor one,
- *  depending on what the execution context uses.
+ *  It can be used with the default execution context implementation in the
+ *  `scala.concurrent` package. It internally forwards the call to either a
+ *  forkjoin based task support or a thread pool executor one, depending on
+ *  what the execution context uses.
  *  
- *  By default, parallel collections are parametrized with this task support object, so parallel collections
- *  share the same execution context backend as the rest of the `scala.concurrent` package.
+ *  By default, parallel collections are parametrized with this task support
+ *  object, so parallel collections share the same execution context backend
+ *  as the rest of the `scala.concurrent` package.
+ *
+ *  @see [[scala.collection.parallel.TaskSupport]] for more information.
  */
 class ExecutionContextTaskSupport(val environment: ExecutionContext = scala.concurrent.ExecutionContext.global)
 extends TaskSupport with ExecutionContextTasks