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, 0 insertions, 60 deletions

diff --git a/src/library/scala/collection/TraversableOnce.scala b/src/library/scala/collection/TraversableOnce.scala
index 5b8abb3e5e..de3b4770f3 100644
--- a/src/library/scala/collection/TraversableOnce.scala
+++ b/src/library/scala/collection/TraversableOnce.scala
@@ -501,66 +501,6 @@ trait TraversableOnce[+A] {
     b.result
   }
 
-  /* The following 4 methods are implemented in a generic way here,
-   * but are specialized further down the hierarchy where possible.
-   * In particular:
-   *
-   * - all concrete sequential collection classes that can be
-   *   parallelized have their corresponding `toPar*` methods
-   *   overridden (e.g. ArrayBuffer overrides `toParIterable`
-   *   and `toParSeq`)
-   * - ParIterableLike overrides all 4 methods
-   * - ParSeqLike again overrides `toParSeq`
-   * - ParSetLike again overrides `toParSet`
-   * - ParMapLike again overrides `toParMap`
-   * - immutable.ParIterable overrides all 4 methods to have immutable return types
-   * - immutable.ParSet overrides `toParSet` to `this`
-   * - immutable.ParSeq overrides nothing yet TODO vector
-   * - immutable.ParMap overrides `toParMap` to `this`
-   */
-
-  /** Converts this $coll to a parallel iterable.
-   *  $willNotTerminateInf
-   *  @return     a parallel iterable containing all elements of this $coll.
-   */
-  def toParIterable: parallel.ParIterable[A] = toParSeq
-
-  /** Converts this $coll to a parallel sequence.
-   *  $willNotTerminateInf
-   *  @return     a parallel sequence containing all elements of this $coll.
-   */
-  def toParSeq: parallel.ParSeq[A] = {
-    val cb = parallel.mutable.ParArray.newCombiner[A]
-    for (elem <- this) cb += elem
-    cb.result
-  }
-
-  /** Converts this $coll to a parallel set.
-   *  $willNotTerminateInf
-   *  @return     a parallel set containing all elements of this $coll.
-   */
-  def toParSet[B >: A]: parallel.ParSet[B] = {
-    val cb = parallel.mutable.ParHashSet.newCombiner[B]
-    for (elem <- this) cb += elem
-    cb.result
-  }
-
-  /** Converts this $coll to a parallel map.
-   *  $willNotTerminateInf
-   *
-   *  This operation is only available on collections containing pairs of elements.
-   *
-   *  @return    a parallel map containing all elements of this $coll.
-   *  @usecase   def toParMap[T, U]: ParMap[T, U]
-   *  @return    a parallel map of type `parallel.ParMap[T, U]`
-   *             containing all key/value pairs of type `(T, U)` of this $coll.
-   */
-  def toParMap[T, U](implicit ev: A <:< (T, U)): parallel.ParMap[T, U] = {
-    val cb = parallel.mutable.ParHashMap.newCombiner[T, U]
-    for (elem <- this) cb += elem
-    cb.result
-  }
-
   /** Displays all elements of this $coll in a string using start, end, and
    *  separator strings.
    *