From da8a29b9071ec15ccc2c6d8eafc182f22bce05f6 Mon Sep 17 00:00:00 2001 From: "Daniel C. Sobral" Date: Wed, 11 Jul 2012 11:59:22 -0300 Subject: SI-6032 Enhance TaskSupport documentation. --- .../collection/parallel/ParIterableLike.scala | 27 ++++++++++ .../scala/collection/parallel/TaskSupport.scala | 61 +++++++++++++++++----- 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 -- cgit v1.2.3