SI-6032 Enhance TaskSupport documentation.

2 files changed, 76 insertions, 12 deletions

diff --git a/src/library/scala/collection/parallel/ParIterableLike.scala b/src/library/scala/collection/parallel/ParIterableLike.scala
index 82498f9b63..d4f1c2f39f 100644
--- a/src/library/scala/collection/parallel/ParIterableLike.scala
+++ b/src/library/scala/collection/parallel/ParIterableLike.scala
@@ -72,6 +72,10 @@ import language.implicitConversions
  *  very fast operation which simply creates wrappers around the receiver collection.
  *  This can be repeated recursively.
  *
+ *  Tasks are scheduled for execution through a
+ *  [[scala.collection.parallel.TaskSupport]] object, which can be changed
+ *  through the `tasksupport` setter of the collection.
+ *
  *  Method `newCombiner` produces a new combiner. Combiners are an extension of builders.
  *  They provide a method `combine` which combines two combiners and returns a combiner
  *  containing elements of both combiners.
@@ -165,6 +169,11 @@ self: ParIterableLike[T, Repr, Sequential] =>
     _tasksupport = defaultTaskSupport
   }
 
+  /** The task support object which is responsible for scheduling and
+   *  load-balancing tasks to processors.
+   *                                                                              
+   *  @see [[scala.collection.parallel.TaskSupport]]
+   */     
   def tasksupport = {
     val ts = _tasksupport
     if (ts eq null) {
@@ -173,6 +182,24 @@ self: ParIterableLike[T, Repr, Sequential] =>
     } else ts
   }
 
+  /** Changes the task support object which is responsible for scheduling and
+   *  load-balancing tasks to 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 concurrent invocations to parallel collection methods.
+   *                                                                              
+   *  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 [[scala.collection.parallel.TaskSupport]]
+   */     
   def tasksupport_=(ts: TaskSupport) = _tasksupport = ts
 
   def seq: Sequential
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