From 5749084921c4868836d888bf6b0c3b28b094b09d Mon Sep 17 00:00:00 2001 From: Aleksandar Pokopec Date: Thu, 10 Feb 2011 10:17:42 +0000 Subject: Updated docs. No review. --- src/library/scala/collection/Parallel.scala | 11 +- src/library/scala/collection/Parallelizable.scala | 2 + .../scala/collection/parallel/Combiner.scala | 28 +++-- .../scala/collection/parallel/ParIterable.scala | 16 ++- .../collection/parallel/ParIterableLike.scala | 113 +++++++++++++-------- .../collection/parallel/ParIterableView.scala | 16 ++- .../collection/parallel/ParIterableViewLike.scala | 15 ++- src/library/scala/collection/parallel/ParMap.scala | 20 +++- .../scala/collection/parallel/ParMapLike.scala | 20 ++++ src/library/scala/collection/parallel/ParSeq.scala | 14 +++ .../scala/collection/parallel/ParSeqLike.scala | 25 +++-- .../scala/collection/parallel/ParSeqView.scala | 16 ++- .../scala/collection/parallel/ParSeqViewLike.scala | 13 ++- src/library/scala/collection/parallel/ParSet.scala | 18 ++++ .../scala/collection/parallel/ParSetLike.scala | 19 ++++ .../collection/parallel/RemainsIterator.scala | 22 +++- .../scala/collection/parallel/Splitter.scala | 53 ++++++---- .../scala/collection/parallel/TaskSupport.scala | 13 ++- src/library/scala/collection/parallel/Tasks.scala | 15 ++- .../collection/parallel/immutable/ParHashMap.scala | 28 ++++- .../collection/parallel/immutable/ParHashSet.scala | 27 ++++- .../parallel/immutable/ParIterable.scala | 15 ++- .../collection/parallel/immutable/ParMap.scala | 19 ++++ .../collection/parallel/immutable/ParRange.scala | 23 +++++ .../collection/parallel/immutable/ParSeq.scala | 9 ++ .../collection/parallel/immutable/ParSet.scala | 18 ++++ .../collection/parallel/immutable/ParVector.scala | 27 +++++ .../collection/parallel/immutable/package.scala | 9 ++ .../collection/parallel/mutable/LazyCombiner.scala | 9 ++ .../collection/parallel/mutable/ParArray.scala | 29 ++++-- .../parallel/mutable/ParFlatHashTable.scala | 15 +++ .../collection/parallel/mutable/ParHashMap.scala | 25 +++++ .../collection/parallel/mutable/ParHashSet.scala | 25 ++++- .../collection/parallel/mutable/ParHashTable.scala | 9 ++ .../collection/parallel/mutable/ParIterable.scala | 15 ++- .../scala/collection/parallel/mutable/ParMap.scala | 19 ++++ .../collection/parallel/mutable/ParMapLike.scala | 20 ++++ .../scala/collection/parallel/mutable/ParSeq.scala | 9 ++ .../scala/collection/parallel/mutable/ParSet.scala | 9 ++ .../collection/parallel/mutable/ParSetLike.scala | 19 ++++ .../scala/collection/parallel/package.scala | 9 ++ 41 files changed, 710 insertions(+), 126 deletions(-) diff --git a/src/library/scala/collection/Parallel.scala b/src/library/scala/collection/Parallel.scala index e500817745..df77e5d1c7 100644 --- a/src/library/scala/collection/Parallel.scala +++ b/src/library/scala/collection/Parallel.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection @@ -7,7 +16,7 @@ package scala.collection /** A marker trait for objects with parallelised operations. * - * @since 2.8 + * @since 2.9 * @author prokopec */ trait Parallel diff --git a/src/library/scala/collection/Parallelizable.scala b/src/library/scala/collection/Parallelizable.scala index 215a8a66ff..999849fbab 100644 --- a/src/library/scala/collection/Parallelizable.scala +++ b/src/library/scala/collection/Parallelizable.scala @@ -9,6 +9,8 @@ import parallel.ParIterableLike /** This trait describes collections which can be turned into parallel collections * by invoking the method `par`. Parallelizable collections may be parametrized with * a target type different than their own. + * + * @tparam ParRepr the actual type of the collection, which has to be parallel */ trait Parallelizable[+ParRepr <: Parallel] { diff --git a/src/library/scala/collection/parallel/Combiner.scala b/src/library/scala/collection/parallel/Combiner.scala index 4a6ae0cd8f..ec45a5eb90 100644 --- a/src/library/scala/collection/parallel/Combiner.scala +++ b/src/library/scala/collection/parallel/Combiner.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -8,27 +17,25 @@ import scala.collection.generic.Sizing /** The base trait for all combiners. - * A combiner lets one construct collections incrementally just like + * A combiner incremental collection construction just like * a regular builder, but also implements an efficient merge operation of two builders * via `combine` method. Once the collection is constructed, it may be obtained by invoking * the `result` method. * + * The complexity of the `combine` method should be less than linear for best + * performance. The `result` method doesn't have to be a constant time operation, + * but may be performed in parallel. + * * @tparam Elem the type of the elements added to the builder * @tparam To the type of the collection the builder produces * - * @author prokopec + * @author Aleksandar Prokopec + * @since 2.9 */ trait Combiner[-Elem, +To] extends Builder[Elem, To] with Sizing with Parallel { self: EnvironmentPassingCombiner[Elem, To] => private[collection] final val tasksupport = getTaskSupport - // type EPC = EnvironmentPassingCombiner[Elem, To] - // - // [scalacfork] /scratch/trunk2/src/library/scala/collection/parallel/Combiner.scala:25: error: contravariant type Elem occurs in invariant position in type scala.collection.parallel.EnvironmentPassingCombiner[Elem,To] of type EPC - // [scalacfork] type EPC = EnvironmentPassingCombiner[Elem, To] - // [scalacfork] ^ - // [scalacfork] one error found - /** Combines the contents of the receiver builder and the `other` builder, * producing a new builder containing both their elements. * @@ -59,10 +66,9 @@ self: EnvironmentPassingCombiner[Elem, To] => } -trait EnvironmentPassingCombiner[-Elem, +To] extends Combiner[Elem, To] { +private[collection] trait EnvironmentPassingCombiner[-Elem, +To] extends Combiner[Elem, To] { abstract override def result = { val res = super.result - // res } } diff --git a/src/library/scala/collection/parallel/ParIterable.scala b/src/library/scala/collection/parallel/ParIterable.scala index 7f5b39d3e4..48b0e35151 100644 --- a/src/library/scala/collection/parallel/ParIterable.scala +++ b/src/library/scala/collection/parallel/ParIterable.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -14,8 +23,11 @@ import scala.collection.parallel.mutable.ParArray * * @tparam T the element type of the collection * - * @author prokopec - * @since 2.8 + * @author Aleksandar Prokopec + * @since 2.9 + * + * @define Coll ParIterable + * @define coll parallel iterable */ trait ParIterable[+T] extends Iterable[T] with GenericParTemplate[T, ParIterable] diff --git a/src/library/scala/collection/parallel/ParIterableLike.scala b/src/library/scala/collection/parallel/ParIterableLike.scala index 190752a3ca..1a63e26622 100644 --- a/src/library/scala/collection/parallel/ParIterableLike.scala +++ b/src/library/scala/collection/parallel/ParIterableLike.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -18,7 +27,6 @@ import annotation.unchecked.uncheckedVariance -// TODO update docs!! /** A template trait for parallel collections of type `ParIterable[T]`. * * $paralleliterableinfo @@ -30,75 +38,96 @@ import annotation.unchecked.uncheckedVariance * * @define paralleliterableinfo * This is a base trait for Scala parallel collections. It defines behaviour - * common to all parallel collections. The actual parallel operation implementation - * is found in the `ParallelIterableFJImpl` trait extending this trait. Concrete - * parallel collections should inherit both this and that trait. + * common to all parallel collections. Concrete parallel collections should + * inherit this trait and `ParIterable` if they want to define specific combiner + * factories. * * Parallel operations are implemented with divide and conquer style algorithms that * parallelize well. The basic idea is to split the collection into smaller parts until * they are small enough to be operated on sequentially. * - * All of the parallel operations are implemented in terms of several methods. The first is: + * All of the parallel operations are implemented as tasks within this trait. Tasks rely + * on the concept of splitters, which extend iterators. Every parallel collection defines: + * * {{{ - * def split: Seq[Repr] + * def parallelIterator: ParIterableIterator[T] * }}} - * which splits the collection into a sequence of disjunct views. This is typically a - * very fast operation which simply creates wrappers around the receiver collection. - * These views can then be split recursively into smaller views and so on. Each of - * the views is still a parallel collection. * - * The next method is: + * which returns an instance of `ParIterableIterator[T]`, which is a subtype of `Splitter[T]`. + * Parallel iterators have a method `remaining` to check the remaining number of elements, + * and method `split` which is defined by splitters. Method `split` divides the splitters + * iterate over into disjunct subsets: + * * {{{ - * def combine[OtherRepr >: Repr](other: OtherRepr): OtherRepr + * def split: Seq[Splitter] * }}} - * which combines this collection with the argument collection and returns a collection - * containing both the elements of this collection and the argument collection. This behaviour - * may be implemented by producing a view that iterates over both collections, by aggressively - * copying all the elements into the new collection or by lazily creating a wrapper over both - * collections that gets evaluated once it's needed. It is recommended to avoid copying all of + * + * which splits the splitter into a sequence of disjunct subsplitters. This is typically a + * very fast operation which simply creates wrappers around the receiver collection. + * This can be repeated recursively. + * + * 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. + * This method can be implemented by aggressively copying all the elements into the new combiner + * or by lazily binding their results. It is recommended to avoid copying all of * the elements for performance reasons, although that cost might be negligible depending on - * the use case. + * the use case. Standard parallel collection combiners avoid copying when merging results, + * relying either on a two-step lazy construction or specific data-structure properties. * * Methods: + * * {{{ - * def seq: Repr - * }}} - * and - * {{{ + * def seq: Sequential * def par: Repr * }}} + * * produce a view of the collection that has sequential or parallel operations, respectively. + * These methods are efficient - they will not copy the elements, but have fixed target + * types. The combination of methods `toParMap`, `toParSeq` or `toParSet` is more flexible, + * but may copy the elements in some cases. * * The method: + * * {{{ * def threshold(sz: Int, p: Int): Int * }}} + * * provides an estimate on the minimum number of elements the collection has before * the splitting stops and depends on the number of elements in the collection. A rule of the * thumb is the number of elements divided by 8 times the parallelism level. This method may * be overridden in concrete implementations if necessary. * - * Finally, method `newCombiner` produces a new parallel builder. - * - * Since this trait extends the `Iterable` trait, methods like `size` and `iterator` must also - * be implemented. + * Since this trait extends the `Iterable` trait, methods like `size` must also + * be implemented in concrete collections, while `iterator` forwards to `parallelIterator` by + * default. * * Each parallel collection is bound to a specific fork/join pool, on which dormant worker - * threads are kept. One can change a fork/join pool of a collection any time except during - * some method being invoked. The fork/join pool contains other information such as the parallelism + * threads are kept. The fork/join pool contains other information such as the parallelism * level, that is, the number of processors used. When a collection is created, it is assigned the - * default fork/join pool found in the `scala.collection.parallel` package object. + * default fork/join pool found in the `scala.parallel` package object. + * + * Parallel collections are not necessarily ordered in terms of the `foreach` + * operation (see `Traversable`). Parallel sequences have a well defined order for iterators - creating + * an iterator and traversing the elements linearly will always yield the same order. + * However, bulk operations such as `foreach`, `map` or `filter` always occur in undefined orders for all + * parallel collections. * - * Parallel collections may or may not be strict, and they are not ordered in terms of the `foreach` - * operation (see `Traversable`). In terms of the iterator of the collection, some collections - * are ordered (for instance, parallel sequences). + * Existing parallel collection implementations provide strict parallel iterators. Strict parallel iterators are aware + * of the number of elements they have yet to traverse. It's also possible to provide non-strict parallel iterators, + * which do not know the number of elements remaining. To do this, the new collection implementation must override + * `isStrictSplitterCollection` to `false`. This will make some operations unavailable. * - * @author prokopec - * @since 2.8 + * To create a new parallel collection, extend the `ParIterable` trait, and implement `size`, `parallelIterator`, + * `newCombiner` and `seq`. Having an implicit combiner factory requires extending this trait in addition, as + * well as providing a companion object, as with regular collections. + * + * @author Aleksandar Prokopec + * @since 2.9 * * @define sideeffects * The higher-order functions passed to certain operations may contain side-effects. Since implementations - * of operations may not be sequential, this means that side-effects may not be predictable and may + * of bulk operations may not be sequential, this means that side-effects may not be predictable and may * produce data-races, deadlocks or invalidation of state if care is not taken. It is up to the programmer * to either avoid using side-effects or to use some form of synchronization when accessing mutable data. * @@ -112,12 +141,13 @@ import annotation.unchecked.uncheckedVariance * builder for the resulting collection. * * @define abortsignalling - * This method will provide sequential views it produces with `abort` signalling capabilities. This means - * that sequential views may send and read `abort` signals. + * This method will use `abort` signalling capabilities. This means + * that splitters may send and read `abort` signals. * * @define indexsignalling - * This method will provide sequential views it produces with `indexFlag` signalling capabilities. This means - * that sequential views may set and read `indexFlag` state. + * This method will use `indexFlag` signalling capabilities. This means + * that splitters may set and read the `indexFlag` state. + * */ trait ParIterableLike[+T, +Repr <: Parallel, +Sequential <: Iterable[T] with IterableLike[T, Sequential]] extends IterableLike[T, Repr] @@ -213,7 +243,7 @@ self => */ protected[this] override def newBuilder: collection.mutable.Builder[T, Repr] = newCombiner - /** Optionally reuses existing combiner for better performance. By default it doesn't - subclasses may override this behaviour. + /** Optionally reuses an existing combiner for better performance. By default it doesn't - subclasses may override this behaviour. * The provided combiner `oldc` that can potentially be reused will be either some combiner from the previous computational task, or `None` if there * was no previous phase (in which case this method must return `newc`). * @@ -383,7 +413,8 @@ self => executeAndWaitResult(new Aggregate(z, seqop, combop, parallelIterator)) } - /** Applies a function `f` to all the elements of $coll. + /** Applies a function `f` to all the elements of $coll. Does so in a nondefined order, + * and in parallel. * * $undefinedorder * diff --git a/src/library/scala/collection/parallel/ParIterableView.scala b/src/library/scala/collection/parallel/ParIterableView.scala index 5efe87c9ee..0bcad549a2 100644 --- a/src/library/scala/collection/parallel/ParIterableView.scala +++ b/src/library/scala/collection/parallel/ParIterableView.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -13,10 +22,11 @@ import scala.collection.generic.CanCombineFrom /** A template view of a non-strict view of a parallel iterable collection. * - * @tparam T ... - * @tparam Coll ... + * @tparam T the type of elements + * @tparam Coll the type of the parallel collection this view was created from + * @tparam CollSeq the type of the sequential collection corresponding to the underlying parallel collection * - * @since 2.8 + * @since 2.9 */ trait ParIterableView[+T, +Coll <: Parallel, +CollSeq] extends ParIterableViewLike[T, Coll, CollSeq, ParIterableView[T, Coll, CollSeq], IterableView[T, CollSeq]] diff --git a/src/library/scala/collection/parallel/ParIterableViewLike.scala b/src/library/scala/collection/parallel/ParIterableViewLike.scala index 6e3d2ff9fe..d34aa10977 100644 --- a/src/library/scala/collection/parallel/ParIterableViewLike.scala +++ b/src/library/scala/collection/parallel/ParIterableViewLike.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -22,12 +31,12 @@ import scala.collection.parallel.immutable.ParRange * which carries information about the type of the sequential version of the view. * * @tparam T the type of the elements this view can traverse - * @tparam Coll the type of the collection this view is derived from - * @tparam CollSeq TODO + * @tparam Coll the type of the parallel collection this view is derived from + * @tparam CollSeq the type of the sequential collection corresponding to the underlying parallel collection * @tparam This the actual representation type of this view * @tparam ThisSeq the type of the sequential representation of this view * - * @since 2.8 + * @since 2.9 */ trait ParIterableViewLike[+T, +Coll <: Parallel, diff --git a/src/library/scala/collection/parallel/ParMap.scala b/src/library/scala/collection/parallel/ParMap.scala index 4b732e6615..e6763ef83c 100644 --- a/src/library/scala/collection/parallel/ParMap.scala +++ b/src/library/scala/collection/parallel/ParMap.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -15,7 +24,16 @@ import scala.collection.generic.CanCombineFrom - +/** A template trait for parallel maps. + * + * $sideeffects + * + * @tparam K the key type of the map + * @tparam V the value type of the map + * + * @author Aleksandar Prokopec + * @since 2.9 + */ trait ParMap[K, +V] extends Map[K, V] with GenericParMapTemplate[K, V, ParMap] diff --git a/src/library/scala/collection/parallel/ParMapLike.scala b/src/library/scala/collection/parallel/ParMapLike.scala index 9be70d9957..e8f076dc4f 100644 --- a/src/library/scala/collection/parallel/ParMapLike.scala +++ b/src/library/scala/collection/parallel/ParMapLike.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -14,6 +23,17 @@ import scala.collection.mutable.Builder +/** A template trait for mutable parallel maps. This trait is to be mixed in + * with concrete parallel maps to override the representation type. + * + * $sideeffects + * + * @tparam K the key type of the map + * @tparam V the value type of the map + * + * @author Aleksandar Prokopec + * @since 2.9 + */ trait ParMapLike[K, +V, +Repr <: ParMapLike[K, V, Repr, Sequential] with ParMap[K, V], diff --git a/src/library/scala/collection/parallel/ParSeq.scala b/src/library/scala/collection/parallel/ParSeq.scala index 970160ec56..89e77b24d7 100644 --- a/src/library/scala/collection/parallel/ParSeq.scala +++ b/src/library/scala/collection/parallel/ParSeq.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -11,11 +20,16 @@ import scala.collection.parallel.mutable.ParArrayCombiner import scala.collection.parallel.mutable.ParArray + /** A template trait for parallel sequences. * * $parallelseqinfo * * $sideeffects + * + * @tparam T the type of the elements in this parallel sequence + * + * @author Aleksandar Prokopec */ trait ParSeq[+T] extends Seq[T] with ParIterable[T] diff --git a/src/library/scala/collection/parallel/ParSeqLike.scala b/src/library/scala/collection/parallel/ParSeqLike.scala index 8a4f15fe6d..9ac647cf5a 100644 --- a/src/library/scala/collection/parallel/ParSeqLike.scala +++ b/src/library/scala/collection/parallel/ParSeqLike.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -12,29 +21,29 @@ import scala.collection.generic.VolatileAbort -// TODO update docs!! /** A template trait for sequences of type `ParSeq[T]`, representing * parallel sequences with element type `T`. * * $parallelseqinfo * - * @tparam T the type of the elements contained in this collection - * @tparam Repr the type of the actual collection containing the elements + * @tparam T the type of the elements contained in this collection + * @tparam Repr the type of the actual collection containing the elements + * @tparam Sequential the type of the sequential version of this parallel collection * * @define parallelseqinfo - * Parallel sequences inherit the `IndexedSeq` trait. This means they provide - * efficient indexing and length computations. Like their sequential counterparts + * Parallel sequences inherit the `Seq` trait. Their indexing and length computations + * are defined to be efficient. Like their sequential counterparts * they always have a defined order of elements. This means they will produce resulting * parallel sequences in the same way sequential sequences do. However, the order - * in which they iterate over elements to produce results is not defined and is generally + * in which they perform bulk operations on elements to produce results is not defined and is generally * nondeterministic. If the higher-order functions given to them produce no sideeffects, * then this won't be noticeable. * * This trait defines a new, more general `split` operation and reimplements the `split` * operation of `ParallelIterable` trait using the new `split` operation. * - * @author prokopec - * @since 2.8 + * @author Aleksandar Prokopec + * @since 2.9 */ trait ParSeqLike[+T, +Repr <: Parallel, +Sequential <: Seq[T] with SeqLike[T, Sequential]] extends scala.collection.SeqLike[T, Repr] diff --git a/src/library/scala/collection/parallel/ParSeqView.scala b/src/library/scala/collection/parallel/ParSeqView.scala index f46be33513..6ac24668ca 100644 --- a/src/library/scala/collection/parallel/ParSeqView.scala +++ b/src/library/scala/collection/parallel/ParSeqView.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -14,10 +23,11 @@ import scala.collection.generic.CanCombineFrom /** A template view of a non-strict view of a parallel sequence. * - * @tparam T - * @tparam Coll + * @tparam T the type of elements in this parallel sequence + * @tparam Coll the type of the underlying parallel collection + * @tparam CollSeq the type of the sequential collection corresponding to the underlying parallel collection * - * @since 2.8 + * @since 2.9 */ trait ParSeqView[+T, +Coll <: Parallel, +CollSeq] extends ParSeqViewLike[T, Coll, CollSeq, ParSeqView[T, Coll, CollSeq], SeqView[T, CollSeq]] diff --git a/src/library/scala/collection/parallel/ParSeqViewLike.scala b/src/library/scala/collection/parallel/ParSeqViewLike.scala index 7b564a9ad4..e661574c5c 100644 --- a/src/library/scala/collection/parallel/ParSeqViewLike.scala +++ b/src/library/scala/collection/parallel/ParSeqViewLike.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -20,11 +29,11 @@ import scala.collection.parallel.immutable.ParRange * * @tparam T the type of the elements in this view * @tparam Coll type of the collection this view is derived from - * @tparam CollSeq TODO + * @tparam CollSeq type of the sequential collection corresponding to the underlying parallel collection * @tparam This actual representation type of this view * @tparam ThisSeq type of the sequential version of this view * - * @since 2.8 + * @since 2.9 */ trait ParSeqViewLike[+T, +Coll <: Parallel, diff --git a/src/library/scala/collection/parallel/ParSet.scala b/src/library/scala/collection/parallel/ParSet.scala index 0453b8a95e..f3dab8faa9 100644 --- a/src/library/scala/collection/parallel/ParSet.scala +++ b/src/library/scala/collection/parallel/ParSet.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -15,6 +24,15 @@ import scala.collection.generic._ +/** A template trait for parallel sets. + * + * $sideeffects + * + * @tparam T the element type of the set + * + * @author Aleksandar Prokopec + * @since 2.9 + */ trait ParSet[T] extends Set[T] with GenericParTemplate[T, ParSet] diff --git a/src/library/scala/collection/parallel/ParSetLike.scala b/src/library/scala/collection/parallel/ParSetLike.scala index 272ad0048b..d888d5865f 100644 --- a/src/library/scala/collection/parallel/ParSetLike.scala +++ b/src/library/scala/collection/parallel/ParSetLike.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -13,6 +22,16 @@ import scala.collection.mutable.Builder +/** A template trait for parallel sets. This trait is mixed in with concrete + * parallel sets to override the representation type. + * + * $sideeffects + * + * @tparam T the element type of the set + * + * @author Aleksandar Prokopec + * @since 2.9 + */ trait ParSetLike[T, +Repr <: ParSetLike[T, Repr, Sequential] with ParSet[T], +Sequential <: Set[T] with SetLike[T, Sequential]] diff --git a/src/library/scala/collection/parallel/RemainsIterator.scala b/src/library/scala/collection/parallel/RemainsIterator.scala index 3363186b7d..3033511519 100644 --- a/src/library/scala/collection/parallel/RemainsIterator.scala +++ b/src/library/scala/collection/parallel/RemainsIterator.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -12,7 +21,7 @@ import scala.collection.parallel.immutable.repetition -trait RemainsIterator[+T] extends Iterator[T] { +private[collection] trait RemainsIterator[+T] extends Iterator[T] { /** The number of elements this iterator has yet to iterate. * This method doesn't change the state of the iterator. */ @@ -26,7 +35,7 @@ trait RemainsIterator[+T] extends Iterator[T] { * @param T type of the elements iterated. * @param IterRepr iterator type. */ -trait AugmentedIterableIterator[+T] extends RemainsIterator[T] { +private[collection] trait AugmentedIterableIterator[+T] extends RemainsIterator[T] { /* accessors */ @@ -358,6 +367,11 @@ trait AugmentedSeqIterator[+T] extends AugmentedIterableIterator[T] { } +/** Parallel iterators allow splitting and provide a `remaining` method to + * obtain the number of elements remaining in the iterator. + * + * @param T type of the elements iterated. + */ trait ParIterableIterator[+T] extends AugmentedIterableIterator[T] with Splitter[T] @@ -500,6 +514,10 @@ self => } +/** Parallel sequence iterators allow splitting into arbitrary subsets. + * + * @param T type of the elements iterated. + */ trait ParSeqIterator[+T] extends ParIterableIterator[T] with AugmentedSeqIterator[T] diff --git a/src/library/scala/collection/parallel/Splitter.scala b/src/library/scala/collection/parallel/Splitter.scala index e598b96c82..7328f3db6c 100644 --- a/src/library/scala/collection/parallel/Splitter.scala +++ b/src/library/scala/collection/parallel/Splitter.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -7,10 +16,10 @@ import scala.collection.Seq /** A splitter (or a split iterator) can be split into more splitters that traverse over * disjoint subsets of elements. * - * @tparam T type of the elements this parallel iterator traverses + * @tparam T type of the elements this splitter traverses * - * @since 2.8.1 - * @author prokopec + * @since 2.9 + * @author Aleksandar Prokopec */ trait Splitter[+T] extends Iterator[T] { @@ -19,13 +28,13 @@ trait Splitter[+T] extends Iterator[T] { * Returns a sequence of split iterators, each iterating over some subset of the * elements in the collection. These subsets are disjoint and should be approximately * equal in size. These subsets are not empty, unless the iterator is empty in which - * case this method returns a sequence with a single empty iterator. If the iterator has - * more than two elements, this method will return two or more iterators. + * case this method returns a sequence with a single empty iterator. If the splitter has + * more than two elements, this method will return two or more splitters. * - * Implementors are advised to keep this partition relatively small - two iterators are + * Implementors are advised to keep this partition relatively small - two splitters are * already enough when partitioning the collection, although there may be a few more. * - * '''Note:''' this method actually invalidates the current iterator. + * '''Note:''' this method actually invalidates the current splitter. * * @return a sequence of disjunct iterators of the collection */ @@ -59,37 +68,37 @@ object Splitter { * * Implementors might want to override the parameterless `split` method for efficiency. * - * @tparam T type of the elements this parallel iterator traverses + * @tparam T type of the elements this splitter traverses * - * @since 2.8.1 - * @author prokopec + * @since 2.9 + * @author Aleksandar Prokopec */ trait PreciseSplitter[+T] extends Splitter[T] { - /** Splits the iterator into disjunct views. + /** Splits the splitter into disjunct views. * - * This overloaded version of the `split` method is specific to precise parallel iterators. - * It returns a sequence of parallel iterators, each iterating some subset of the - * elements in this iterator. The sizes of the subiterators in the partition is equal to + * This overloaded version of the `split` method is specific to precise splitters. + * It returns a sequence of splitters, each iterating some subset of the + * elements in this splitter. The sizes of the subsplitters in the partition is equal to * the size in the corresponding argument, as long as there are enough elements in this - * iterator to split it that way. + * splitter to split it that way. * - * If there aren't enough elements, a zero element iterator is appended for each additional argument. - * If there are additional elements, an additional iterator is appended at the end to compensate. + * If there aren't enough elements, a zero element splitter is appended for each additional argument. + * If there are additional elements, an additional splitter is appended at the end to compensate. * - * For example, say we have a parallel iterator `ps` with 100 elements. Invoking: + * For example, say we have a splitter `ps` with 100 elements. Invoking: * {{{ * ps.split(50, 25, 25, 10, 5) * }}} - * will return a sequence of five iterators, last two views being empty. On the other hand, calling: + * will return a sequence of five splitters, last two views being empty. On the other hand, calling: * {{{ * ps.split(50, 40) * }}} - * will return a sequence of three iterators, last of them containing ten elements. + * will return a sequence of three splitters, last of them containing ten elements. * - * '''Note:''' this method actually invalidates the current iterator. + * '''Note:''' this method actually invalidates the current splitter. * - * Unlike the case with `split` found in parallel iterable iterators, views returned by this method can be empty. + * Unlike the case with `split` found in splitters, views returned by this method can be empty. * * @param sizes the sizes used to split this split iterator into iterators that traverse disjunct subsets * @return a sequence of disjunct subsequence iterators of this parallel iterator diff --git a/src/library/scala/collection/parallel/TaskSupport.scala b/src/library/scala/collection/parallel/TaskSupport.scala index 1b1ee6e469..20800250b4 100644 --- a/src/library/scala/collection/parallel/TaskSupport.scala +++ b/src/library/scala/collection/parallel/TaskSupport.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -8,9 +17,9 @@ package scala.collection.parallel trait TaskSupport extends Tasks -class ForkJoinTaskSupport extends TaskSupport with AdaptiveWorkStealingForkJoinTasks +private[collection] class ForkJoinTaskSupport extends TaskSupport with AdaptiveWorkStealingForkJoinTasks -class ThreadPoolTaskSupport extends TaskSupport with AdaptiveWorkStealingThreadPoolTasks +private[collection] class ThreadPoolTaskSupport extends TaskSupport with AdaptiveWorkStealingThreadPoolTasks diff --git a/src/library/scala/collection/parallel/Tasks.scala b/src/library/scala/collection/parallel/Tasks.scala index 13a41eb7d4..6f00547925 100644 --- a/src/library/scala/collection/parallel/Tasks.scala +++ b/src/library/scala/collection/parallel/Tasks.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel @@ -13,10 +22,7 @@ import annotation.unchecked.uncheckedVariance /** A trait that declares task execution capabilities used - * by parallel collections. Parallel collections inherit a subtrait - * of this trait. - * - * One implementation trait of `TaskExecution` is `ForkJoinTaskExecution`. + * by parallel collections. */ trait Tasks { @@ -214,6 +220,7 @@ trait AdaptiveWorkStealingTasks extends Tasks { } +/** An implementation of tasks objects based on the Java thread pooling API. */ trait ThreadPoolTasks extends Tasks { import java.util.concurrent._ diff --git a/src/library/scala/collection/parallel/immutable/ParHashMap.scala b/src/library/scala/collection/parallel/immutable/ParHashMap.scala index 446d87348b..66b981e8c4 100644 --- a/src/library/scala/collection/parallel/immutable/ParHashMap.scala +++ b/src/library/scala/collection/parallel/immutable/ParHashMap.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel.immutable @@ -23,9 +32,20 @@ import annotation.unchecked.uncheckedVariance -/** Parallel hash trie map. +/** Immutable parallel hash map, based on hash tries. + * + * $paralleliterableinfo + * + * $sideeffects * - * @author prokopec + * @tparam K the key type of the map + * @tparam V the value type of the map + * + * @author Aleksandar Prokopec + * @since 2.9 + * + * @define Coll immutable.ParHashMap + * @define coll immutable parallel hash map */ @SerialVersionUID(1L) class ParHashMap[K, +V] private[immutable] (private[this] val trie: HashMap[K, V]) @@ -126,6 +146,10 @@ self => } +/** $factoryinfo + * @define Coll immutable.ParHashMap + * @define coll immutable parallel hash map + */ object ParHashMap extends ParMapFactory[ParHashMap] { def empty[K, V]: ParHashMap[K, V] = new ParHashMap[K, V] diff --git a/src/library/scala/collection/parallel/immutable/ParHashSet.scala b/src/library/scala/collection/parallel/immutable/ParHashSet.scala index 77dd947201..bd9cefa298 100644 --- a/src/library/scala/collection/parallel/immutable/ParHashSet.scala +++ b/src/library/scala/collection/parallel/immutable/ParHashSet.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel.immutable @@ -24,9 +33,19 @@ import scala.collection.immutable.HashSet -/** Parallel hash trie set. +/** Immutable parallel hash set, based on hash tries. + * + * $paralleliterableinfo + * + * $sideeffects * - * @author prokopec + * @tparam T the element type of the set + * + * @author Aleksandar Prokopec + * @since 2.9 + * + * @define Coll immutable.ParHashSet + * @define coll immutable parallel hash set */ @SerialVersionUID(1L) class ParHashSet[T] private[immutable] (private[this] val trie: HashSet[T]) @@ -108,6 +127,10 @@ self => } +/** $factoryinfo + * @define Coll immutable.ParHashSet + * @define coll immutable parallel hash set + */ object ParHashSet extends ParSetFactory[ParHashSet] { def newCombiner[T]: Combiner[T, ParHashSet[T]] = HashSetCombiner[T] diff --git a/src/library/scala/collection/parallel/immutable/ParIterable.scala b/src/library/scala/collection/parallel/immutable/ParIterable.scala index 00a8c02fd6..0118452cb8 100644 --- a/src/library/scala/collection/parallel/immutable/ParIterable.scala +++ b/src/library/scala/collection/parallel/immutable/ParIterable.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection package parallel.immutable @@ -14,10 +23,10 @@ import scala.collection.parallel.Combiner * * $sideeffects * - * @tparam A the element type of the collection + * @tparam T the element type of the collection * - * @author prokopec - * @since 2.8 + * @author Aleksandar Prokopec + * @since 2.9 */ trait ParIterable[+T] extends collection.immutable.Iterable[T] diff --git a/src/library/scala/collection/parallel/immutable/ParMap.scala b/src/library/scala/collection/parallel/immutable/ParMap.scala index c06891c459..d99091c57c 100644 --- a/src/library/scala/collection/parallel/immutable/ParMap.scala +++ b/src/library/scala/collection/parallel/immutable/ParMap.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection package parallel.immutable @@ -16,6 +25,16 @@ import scala.collection.parallel.Combiner +/** A template trait for immutable parallel maps. + * + * $sideeffects + * + * @tparam K the key type of the map + * @tparam V the value type of the map + * + * @author Aleksandar Prokopec + * @since 2.9 + */ trait ParMap[K, +V] extends Map[K, V] with GenericParMapTemplate[K, V, ParMap] diff --git a/src/library/scala/collection/parallel/immutable/ParRange.scala b/src/library/scala/collection/parallel/immutable/ParRange.scala index 2456c2beda..19d2a6d3b8 100644 --- a/src/library/scala/collection/parallel/immutable/ParRange.scala +++ b/src/library/scala/collection/parallel/immutable/ParRange.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel.immutable @@ -9,6 +18,20 @@ import scala.collection.parallel.ParIterableIterator +/** Parallel ranges. + * + * $paralleliterableinfo + * + * $sideeffects + * + * @param range the sequential range this parallel range was obtained from + * + * @author Aleksandar Prokopec + * @since 2.9 + * + * @define Coll immutable.ParRange + * @define coll immutable parallel range + */ @SerialVersionUID(1L) class ParRange(val range: Range) extends ParSeq[Int] diff --git a/src/library/scala/collection/parallel/immutable/ParSeq.scala b/src/library/scala/collection/parallel/immutable/ParSeq.scala index 68ed9a3139..dbb37a9c69 100644 --- a/src/library/scala/collection/parallel/immutable/ParSeq.scala +++ b/src/library/scala/collection/parallel/immutable/ParSeq.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection package parallel.immutable diff --git a/src/library/scala/collection/parallel/immutable/ParSet.scala b/src/library/scala/collection/parallel/immutable/ParSet.scala index 5f9e4eee8a..2002d6432d 100644 --- a/src/library/scala/collection/parallel/immutable/ParSet.scala +++ b/src/library/scala/collection/parallel/immutable/ParSet.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection package parallel.immutable @@ -14,6 +23,11 @@ import scala.collection.parallel.Combiner +/** An immutable variant of `ParSet`. + * + * @define Coll mutable.ParSet + * @define coll mutable parallel set + */ trait ParSet[T] extends Set[T] with GenericParTemplate[T, ParSet] @@ -34,6 +48,10 @@ self => +/** $factoryInfo + * @define Coll mutable.ParSet + * @define coll mutable parallel set + */ object ParSet extends ParSetFactory[ParSet] { def newCombiner[T]: Combiner[T, ParSet[T]] = HashSetCombiner[T] diff --git a/src/library/scala/collection/parallel/immutable/ParVector.scala b/src/library/scala/collection/parallel/immutable/ParVector.scala index 663621e060..f79ba2a7f9 100644 --- a/src/library/scala/collection/parallel/immutable/ParVector.scala +++ b/src/library/scala/collection/parallel/immutable/ParVector.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection package parallel.immutable @@ -16,6 +25,20 @@ import immutable.VectorIterator +/** Immutable parallel vectors, based on vectors. + * + * $paralleliterableinfo + * + * $sideeffects + * + * @tparam T the element type of the vector + * + * @author Aleksandar Prokopec + * @since 2.9 + * + * @define Coll immutable.ParVector + * @define coll immutable parallel vector + */ class ParVector[+T](private[this] val vector: Vector[T]) extends ParSeq[T] with GenericParTemplate[T, ParVector] @@ -61,6 +84,10 @@ extends ParSeq[T] +/** $factoryInfo + * @define Coll immutable.ParVector + * @define coll immutable parallel vector + */ object ParVector extends ParFactory[ParVector] { implicit def canBuildFrom[T]: CanCombineFrom[Coll, T, ParVector[T]] = new GenericCanCombineFrom[T] diff --git a/src/library/scala/collection/parallel/immutable/package.scala b/src/library/scala/collection/parallel/immutable/package.scala index 142e554178..8bb0b2216d 100644 --- a/src/library/scala/collection/parallel/immutable/package.scala +++ b/src/library/scala/collection/parallel/immutable/package.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel diff --git a/src/library/scala/collection/parallel/mutable/LazyCombiner.scala b/src/library/scala/collection/parallel/mutable/LazyCombiner.scala index 955698fdd4..8f7a62aa4f 100644 --- a/src/library/scala/collection/parallel/mutable/LazyCombiner.scala +++ b/src/library/scala/collection/parallel/mutable/LazyCombiner.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel.mutable diff --git a/src/library/scala/collection/parallel/mutable/ParArray.scala b/src/library/scala/collection/parallel/mutable/ParArray.scala index ccd693a241..bf5cbf9a1e 100644 --- a/src/library/scala/collection/parallel/mutable/ParArray.scala +++ b/src/library/scala/collection/parallel/mutable/ParArray.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel.mutable @@ -25,17 +34,18 @@ import scala.collection.Sequentializable * cannot be changed after it's been created. * * `ParArray` internally keeps an array containing the elements. This means that - * bulk operations based on traversal are fast, but those returning a parallel array as a result - * are slightly slower. The reason for this is that `ParArray` uses lazy builders that - * create the internal data array only after the size of the array is known. The fragments - * are then copied into the resulting data array in parallel using fast array copy operations. - * Operations for which the resulting array size is known in advance are optimised to use this - * information. + * bulk operations based on traversal ensure fast access to elements. `ParArray` uses lazy builders that + * create the internal data array only after the size of the array is known. In the meantime, they keep + * the result set fragmented. The fragments + * are copied into the resulting data array in parallel using fast array copy operations once all the combiners + * are populated in parallel. * * @tparam T type of the elements in the array * * @define Coll ParArray * @define coll parallel array + * + * @author Aleksandar Prokopec */ @SerialVersionUID(1L) class ParArray[T] private[mutable] (val arrayseq: ArraySeq[T]) @@ -673,9 +683,10 @@ self => } - - - +/** $factoryinfo + * @define Coll mutable.ParArray + * @define coll parallel array + */ object ParArray extends ParFactory[ParArray] { implicit def canBuildFrom[T]: CanCombineFrom[Coll, T, ParArray[T]] = new GenericCanCombineFrom[T] def newBuilder[T]: Combiner[T, ParArray[T]] = newCombiner diff --git a/src/library/scala/collection/parallel/mutable/ParFlatHashTable.scala b/src/library/scala/collection/parallel/mutable/ParFlatHashTable.scala index 82c69b4c53..8929c978b6 100644 --- a/src/library/scala/collection/parallel/mutable/ParFlatHashTable.scala +++ b/src/library/scala/collection/parallel/mutable/ParFlatHashTable.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection package parallel.mutable @@ -9,6 +18,12 @@ import collection.parallel.ParIterableIterator +/** Parallel flat hash table. + * + * @tparam T type of the elements in the table + * + * @author Aleksandar Prokopec + */ trait ParFlatHashTable[T] extends collection.mutable.FlatHashTable[T] { override def alwaysInitSizeMap = true diff --git a/src/library/scala/collection/parallel/mutable/ParHashMap.scala b/src/library/scala/collection/parallel/mutable/ParHashMap.scala index 4db3d89291..4dcf263fc5 100644 --- a/src/library/scala/collection/parallel/mutable/ParHashMap.scala +++ b/src/library/scala/collection/parallel/mutable/ParHashMap.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel package mutable @@ -12,6 +21,18 @@ import collection.mutable.UnrolledBuffer +/** A parallel hash map. + * + * `ParHashMap` is a parallel map which internally keeps elements within a hash table. + * It uses chaining to resolve collisions. + * + * @tparam T type of the elements in the parallel hash map + * + * @define Coll ParHashMap + * @define coll parallel hash map + * + * @author Aleksandar Prokopec + */ @SerialVersionUID(1L) class ParHashMap[K, V] private[collection] (contents: HashTable.Contents[K, DefaultEntry[K, V]]) extends ParMap[K, V] @@ -118,6 +139,10 @@ self => } +/** $factoryinfo + * @define Coll mutable.ParHashMap + * @define coll parallel hash map + */ object ParHashMap extends ParMapFactory[ParHashMap] { var iters = 0 diff --git a/src/library/scala/collection/parallel/mutable/ParHashSet.scala b/src/library/scala/collection/parallel/mutable/ParHashSet.scala index 4065baec06..d22e0e8abd 100644 --- a/src/library/scala/collection/parallel/mutable/ParHashSet.scala +++ b/src/library/scala/collection/parallel/mutable/ParHashSet.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel.mutable @@ -13,6 +22,18 @@ import collection.mutable.UnrolledBuffer +/** A parallel hash set. + * + * `ParHashSet` is a parallel set which internally keeps elements within a hash table. + * It uses linear probing to resolve collisions. + * + * @tparam T type of the elements in the parallel hash map + * + * @define Coll ParHashMap + * @define coll parallel hash map + * + * @author Aleksandar Prokopec + */ @SerialVersionUID(1L) class ParHashSet[T] private[collection] (contents: FlatHashTable.Contents[T]) extends ParSet[T] @@ -86,8 +107,8 @@ extends ParSet[T] /** $factoryInfo - * @define Coll mutable.ParSet - * @define coll mutable parallel set + * @define Coll mutable.ParHashSet + * @define coll parallel hash set */ object ParHashSet extends ParSetFactory[ParHashSet] { implicit def canBuildFrom[T]: CanCombineFrom[Coll, T, ParHashSet[T]] = new GenericCanCombineFrom[T] diff --git a/src/library/scala/collection/parallel/mutable/ParHashTable.scala b/src/library/scala/collection/parallel/mutable/ParHashTable.scala index b238ce09de..be1cbf1333 100644 --- a/src/library/scala/collection/parallel/mutable/ParHashTable.scala +++ b/src/library/scala/collection/parallel/mutable/ParHashTable.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection package parallel.mutable diff --git a/src/library/scala/collection/parallel/mutable/ParIterable.scala b/src/library/scala/collection/parallel/mutable/ParIterable.scala index 5049e3507a..eba4ff2e72 100644 --- a/src/library/scala/collection/parallel/mutable/ParIterable.scala +++ b/src/library/scala/collection/parallel/mutable/ParIterable.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel.mutable @@ -7,7 +16,7 @@ import scala.collection.parallel.ParIterableLike import scala.collection.parallel.Combiner -/** A template trait for parallel iterable collections. +/** A template trait for mutable parallel iterable collections. * * $paralleliterableinfo * @@ -15,8 +24,8 @@ import scala.collection.parallel.Combiner * * @tparam T the element type of the collection * - * @author prokopec - * @since 2.8 + * @author Aleksandar Prokopec + * @since 2.9 */ trait ParIterable[T] extends collection.mutable.Iterable[T] with collection.parallel.ParIterable[T] diff --git a/src/library/scala/collection/parallel/mutable/ParMap.scala b/src/library/scala/collection/parallel/mutable/ParMap.scala index cb6014289d..f4fa7303c4 100644 --- a/src/library/scala/collection/parallel/mutable/ParMap.scala +++ b/src/library/scala/collection/parallel/mutable/ParMap.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel.mutable @@ -8,6 +17,16 @@ import collection.parallel.Combiner +/** A template trait for mutable parallel maps. + * + * $sideeffects + * + * @tparam K the key type of the map + * @tparam V the value type of the map + * + * @author Aleksandar Prokopec + * @since 2.9 + */ trait ParMap[K, V] extends collection.mutable.Map[K, V] with collection.parallel.ParMap[K, V] diff --git a/src/library/scala/collection/parallel/mutable/ParMapLike.scala b/src/library/scala/collection/parallel/mutable/ParMapLike.scala index 25b5c3b5f7..cd2bea1419 100644 --- a/src/library/scala/collection/parallel/mutable/ParMapLike.scala +++ b/src/library/scala/collection/parallel/mutable/ParMapLike.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel package mutable @@ -8,6 +17,17 @@ import collection.mutable.Builder +/** A template trait for mutable parallel maps. This trait is to be mixed in + * with concrete parallel maps to override the representation type. + * + * $sideeffects + * + * @tparam K the key type of the map + * @tparam V the value type of the map + * + * @author Aleksandar Prokopec + * @since 2.9 + */ trait ParMapLike[K, V, +Repr <: ParMapLike[K, V, Repr, Sequential] with ParMap[K, V], diff --git a/src/library/scala/collection/parallel/mutable/ParSeq.scala b/src/library/scala/collection/parallel/mutable/ParSeq.scala index a11ebf42d9..10d3033701 100644 --- a/src/library/scala/collection/parallel/mutable/ParSeq.scala +++ b/src/library/scala/collection/parallel/mutable/ParSeq.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel.mutable diff --git a/src/library/scala/collection/parallel/mutable/ParSet.scala b/src/library/scala/collection/parallel/mutable/ParSet.scala index e700bd97d7..b7f4b61d66 100644 --- a/src/library/scala/collection/parallel/mutable/ParSet.scala +++ b/src/library/scala/collection/parallel/mutable/ParSet.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection.parallel.mutable diff --git a/src/library/scala/collection/parallel/mutable/ParSetLike.scala b/src/library/scala/collection/parallel/mutable/ParSetLike.scala index d3fab5a4db..df87eff42c 100644 --- a/src/library/scala/collection/parallel/mutable/ParSetLike.scala +++ b/src/library/scala/collection/parallel/mutable/ParSetLike.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection package parallel.mutable @@ -13,6 +22,16 @@ import scala.collection.mutable.Builder +/** A template trait for mutable parallel sets. This trait is mixed in with concrete + * parallel sets to override the representation type. + * + * $sideeffects + * + * @tparam T the element type of the set + * + * @author Aleksandar Prokopec + * @since 2.9 + */ trait ParSetLike[T, +Repr <: ParSetLike[T, Repr, Sequential] with ParSet[T], +Sequential <: mutable.Set[T] with mutable.SetLike[T, Sequential]] diff --git a/src/library/scala/collection/parallel/package.scala b/src/library/scala/collection/parallel/package.scala index 67b60ad129..db7e5c75ba 100644 --- a/src/library/scala/collection/parallel/package.scala +++ b/src/library/scala/collection/parallel/package.scala @@ -1,3 +1,12 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + + package scala.collection -- cgit v1.2.3