Removing toPar* methods, since we've agreed the...

Removing toPar* methods, since we've agreed they're difficult to: -
underestand - maintain

Also, changed the docs and some tests appropriately.

Description:
1) Every collection is now parallelizable - switch to the parallel version of the collection is done via `par`.

- Traversable collections and iterators have `par` return a parallel
- collection of type `ParIterable[A]` with the implementation being the
- representative of `ParIterable`s (currently, `ParArray`). Iterable
- collections do the same thing. Sequences refine `par`'s returns type
- to `ParSeq[A]`. Maps and sets do a similar thing.

The above means that the contract for `par` changed - it is no longer guaranteed to be O(1), nor reflect the same underlying data, as was the case for mutable collections before. Method `par` is now at worst linear.

Furthermore, specific collection implementations override `par` to a more efficient alternative - instead of copying the dataset, the dataset is shared between the old and the new version. Implementation complexity may be sublinear or constant in these cases, and the underlying data structure may be shared. Currently, these data structures include parallel arrays, maps and sets, vectors, hash trie maps and sets, and ranges.

Finally, parallel collections implement `par` trivially.

2) Methods `toMap`, `toSet`, `toSeq` and `toIterable` have been refined
for parallel collections to switch between collection types, however,
they never switch an implementation from parallel to sequential. They
may or may not copy the elements, as is the case with sequential
variants of these methods.

3) The preferred way to switch between different collection types,
whether maps, sets and seqs, or parallel and sequential, is now via use
of methods `toIterable`, `toSeq`, `toSet` and `toMap` in combination
with `par` and `seq`.

Review by odersky.

1 files changed, 45 insertions, 4 deletions

diff --git a/src/library/scala/collection/Parallelizable.scala b/src/library/scala/collection/Parallelizable.scala
index 999849fbab..207bb25cb6 100644
--- a/src/library/scala/collection/Parallelizable.scala
+++ b/src/library/scala/collection/Parallelizable.scala
@@ -1,8 +1,18 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection
 
 
 
 import parallel.ParIterableLike
+import parallel.Combiner
 
 
 
@@ -10,19 +20,50 @@ import parallel.ParIterableLike
  *  by invoking the method `par`. Parallelizable collections may be parametrized with
  *  a target type different than their own.
  *
+ *  @tparam A            the type of the elements in the collection
  *  @tparam ParRepr      the actual type of the collection, which has to be parallel
  */
-trait Parallelizable[+ParRepr <: Parallel] {
-
-  /** Returns a parallel implementation of a collection.
+trait Parallelizable[+A, +ParRepr <: Parallel] {
+self: TraversableOnce[A] =>
+
+  /** Returns a parallel implementation of this collection.
+   *
+   *  For most collection types, this method creates a new parallel collection by copying
+   *  all the elements. For these collection, `par` takes linear time. Mutable collections
+   *  in this category do not produce a mutable parallel collection that has the same
+   *  underlying dataset, so changes in one collection will not be reflected in the other one.
+   *
+   *  Specific collections (e.g. `ParArray` or `mutable.ParHashMap`) override this default
+   *  behaviour by creating a parallel collection which shares the same underlying dataset.
+   *  For these collections, `par` takes constant or sublinear time.
+   *
+   *  All parallel collections return a reference to themselves.
+   *
+   *  @return  a parallel implementation of this collection
    */
-  def par: ParRepr
+  def par: ParRepr = {
+    val cb = parCombiner
+    for (x <- this) cb += x
+    cb.result
+  }
+
+  /** The default `par` implementation uses the combiner provided by this method
+   *  to create a new parallel collection.
+   *
+   *  @return  a combiner for the parallel collection of type `ParRepr`
+   */
+  protected[this] def parCombiner: Combiner[A, ParRepr]
 
 }
 
 
+trait CustomParallelizable[+A, +ParRepr <: Parallel] extends Parallelizable[A, ParRepr] {
+self: TraversableOnce[A] =>
 
+  override def par: ParRepr
 
+  protected override def parCombiner = throw new UnsupportedOperationException("")
+}