--- jsr166/src/extra166y/ParallelArray.java 2012/02/21 01:54:03 1.4
+++ jsr166/src/extra166y/ParallelArray.java 2013/02/05 17:49:18 1.12
@@ -22,7 +22,7 @@ import java.lang.reflect.Array;
* matching a predicate or ranges of indices, and to reduce
* all elements into a single value such as a sum.
*
- *
A ParallelArray is constructed by allocating, using, or copying
+ *
A ParallelArray is constructed by allocating, using, or copying
* an array, using one of the static factory methods {@link #create},
* {@link #createEmpty}, {@link #createUsingHandoff} and {@link
* #createFromCopy}. Upon construction, the encapsulated array managed
@@ -31,7 +31,7 @@ import java.lang.reflect.Array;
* array, access by another thread of an element of a ParallelArray
* while another operation is in progress has undefined effects.
*
- *
The ForkJoinPool used to construct a ParallelArray can be
+ *
The ForkJoinPool used to construct a ParallelArray can be
* shared safely by other threads (and used in other
* ParallelArrays). To avoid the overhead associated with creating
* multiple executors, it is often a good idea to use the {@link
@@ -42,15 +42,15 @@ import java.lang.reflect.Array;
*
A ParallelArray is not a List. It relies on random access across
* array elements to support efficient parallel operations. However,
* a ParallelArray can be viewed and manipulated as a List, via method
- * {@link ParallelArray#asList}. The asList view allows
+ * {@link ParallelArray#asList}. The {@code asList} view allows
* incremental insertion and modification of elements while setting up
* a ParallelArray, generally before using it for parallel
* operations. Similarly, the list view may be useful when accessing
* the results of computations in sequential contexts. A
* ParallelArray may also be created using the elements of any other
* Collection, by constructing from the array returned by the
- * Collection's toArray method. The effects of mutative
- * asList operations may also be achieved directly using
+ * Collection's {@code toArray} method. The effects of mutative
+ * {@code asList} operations may also be achieved directly using
* method {@link #setLimit} along with element-by-element access
* methods {@link #get} and {@link #set}.
*
@@ -61,21 +61,21 @@ import java.lang.reflect.Array;
* {@link ParallelDoubleArray} are also supplied, and designed to
* smoothly interoperate with ParallelArrays. You should also use a
* ParallelLongArray for processing other integral scalar data
- * (int, short, etc). And similarly use a
- * ParallelDoubleArray for float data. (Further
+ * ({@code int}, {@code short}, etc). And similarly use a
+ * ParallelDoubleArray for {@code float} data. (Further
* specializations for these other types would add clutter without
* significantly improving performance beyond that of the Long and
* Double versions.)
*
- *
Most usages of ParallelArray involve sets of operations prefixed
+ *
Most usages of ParallelArray involve sets of operations prefixed
* with range bounds, filters, and mappings (including mappings that
* combine elements from other ParallelArrays), using
- * withBounds, withFilter, and withMapping,
+ * {@code withBounds}, {@code withFilter}, and {@code withMapping},
* respectively. For example,
- * aParallelArray.withFilter(aPredicate).all() creates a new
+ * {@code aParallelArray.withFilter(aPredicate).all()} creates a new
* ParallelArray containing only those elements matching the
* predicate. And for ParallelLongArrays a, b, and c,
- * a.withMapping(CommonOps.longAdder(),b).withMapping(CommonOps.longAdder(),c).min()
+ * {@code a.withMapping(CommonOps.longAdder(),b).withMapping(CommonOps.longAdder(),c).min()}
* returns the minimum value of a[i]+b[i]+c[i] for all i. As
* illustrated below, a mapping often represents accessing
* some field or invoking some method of an element. These versions
@@ -87,21 +87,21 @@ import java.lang.reflect.Array;
* be cascaded, but all filter prefixes must precede all mapping
* prefixes, to ensure efficient execution in a single parallel step.
* In cases of combined mapping expressions, this rule is only
- * dynamically enforced. For example, pa.withMapping(op,
- * pb.withFilter(f)) will compile but throw an exception upon
+ * dynamically enforced. For example, {@code pa.withMapping(op,
+ * pb.withFilter(f))} will compile but throw an exception upon
* execution because the filter precedes the mapping.
*
*
While series of filters and mappings are allowed, it is
* usually more efficient to combine them into single filters or
* mappings when possible. For example
- * pa.withMapping(addOne).withMapping(addOne) is generally
- * less efficient than pa.withMapping(addTwo). Methods
- * withIndexedFilter and withIndexedMapping may be
+ * {@code pa.withMapping(addOne).withMapping(addOne)} is generally
+ * less efficient than {@code pa.withMapping(addTwo)}. Methods
+ * {@code withIndexedFilter} and {@code withIndexedMapping} may be
* useful when combining such expressions.
*
- *
This class includes some reductions, such as min, that
+ *
This class includes some reductions, such as {@code min}, that
* are commonly useful for most element types, as well as a combined
- * version, summary, that computes all of them in a single
+ * version, {@code summary}, that computes all of them in a single
* parallel step, which is normally more efficient than computing each
* in turn.
*
@@ -117,7 +117,7 @@ import java.lang.reflect.Array;
* programming with aggregates is that you must separately define each
* of the component functions on elements. For example, the following
* returns the maximum Grade Point Average across all senior students,
- * given a (fictional) Student class:
+ * given a (fictional) {@code Student} class:
*
*
* import static Ops.*;
@@ -139,7 +139,6 @@ import java.lang.reflect.Array;
* static final GpaField gpaField = new GpaField();
* }
*
- *
*/
public class ParallelArray extends AbstractParallelAnyArray.OUPap implements Iterable {
/*
@@ -292,7 +291,7 @@ public class ParallelArray extends Ab
public ForkJoinPool getExecutor() { return ex; }
/**
- * Applies the given procedure to elements
+ * Applies the given procedure to elements.
* @param procedure the procedure
*/
public void apply(Procedure super T> procedure) {
@@ -300,7 +299,7 @@ public class ParallelArray extends Ab
}
/**
- * Returns reduction of elements
+ * Returns reduction of elements.
* @param reducer the reducer
* @param base the result for an empty array
* @return reduction
@@ -310,7 +309,7 @@ public class ParallelArray extends Ab
}
/**
- * Returns a new ParallelArray holding all elements
+ * Returns a new ParallelArray holding all elements.
* @return a new ParallelArray holding all elements
*/
public ParallelArray all() {
@@ -319,7 +318,7 @@ public class ParallelArray extends Ab
/**
* Returns a new ParallelArray with the given element type holding
- * all elements
+ * all elements.
* @param elementType the type of the elements
* @return a new ParallelArray holding all elements
*/
@@ -353,7 +352,7 @@ public class ParallelArray extends Ab
/**
* Replaces elements with the results of applying the given
- * mapping to each index and current element value
+ * mapping to each index and current element value.
* @param op the op
* @return this (to simplify use in expressions)
*/
@@ -387,7 +386,7 @@ public class ParallelArray extends Ab
/**
* Replaces elements with results of applying
- * op(thisElement, otherElement)
+ * {@code op(thisElement, otherElement)}.
* @param other the other array
* @param combiner the combiner
* @return this (to simplify use in expressions)
@@ -401,7 +400,7 @@ public class ParallelArray extends Ab
/**
* Replaces elements with results of applying
- * op(thisElement, otherElement)
+ * {@code op(thisElement, otherElement)}.
* @param other the other array
* @param combiner the combiner
* @return this (to simplify use in expressions)
@@ -414,7 +413,7 @@ public class ParallelArray extends Ab
/**
* Returns the index of some element equal to given target,
- * or -1 if not present
+ * or -1 if not present.
* @param target the element to search for
* @return the index or -1 if not present
*/
@@ -451,7 +450,7 @@ public class ParallelArray extends Ab
* to locate minimum and maximum elements.
* @param comparator the comparator to use for
* locating minimum and maximum elements
- * @return the summary.
+ * @return the summary
*/
public ParallelArray.SummaryStatistics summary
(Comparator super T> comparator) {
@@ -460,15 +459,15 @@ public class ParallelArray extends Ab
/**
* Returns summary statistics, assuming that all elements are
- * Comparables
- * @return the summary.
+ * Comparables.
+ * @return the summary
*/
public ParallelArray.SummaryStatistics summary() {
return super.summary();
}
/**
- * Returns the minimum element, or null if empty
+ * Returns the minimum element, or null if empty.
* @param comparator the comparator
* @return minimum element, or null if empty
*/
@@ -478,16 +477,16 @@ public class ParallelArray extends Ab
/**
* Returns the minimum element, or null if empty,
- * assuming that all elements are Comparables
+ * assuming that all elements are Comparables.
* @return minimum element, or null if empty
- * @throws ClassCastException if any element is not Comparable.
+ * @throws ClassCastException if any element is not Comparable
*/
public T min() {
return super.min();
}
/**
- * Returns the maximum element, or null if empty
+ * Returns the maximum element, or null if empty.
* @param comparator the comparator
* @return maximum element, or null if empty
*/
@@ -496,10 +495,10 @@ public class ParallelArray extends Ab
}
/**
- * Returns the maximum element, or null if empty
- * assuming that all elements are Comparables
+ * Returns the maximum element, or null if empty,
+ * assuming that all elements are Comparables.
* @return maximum element, or null if empty
- * @throws ClassCastException if any element is not Comparable.
+ * @throws ClassCastException if any element is not Comparable
*/
public T max() {
return super.max();
@@ -508,9 +507,9 @@ public class ParallelArray extends Ab
/**
* Replaces each element with the running cumulation of applying
* the given reducer. For example, if the contents are the numbers
- * 1, 2, 3, and the reducer operation adds numbers, then
- * after invocation of this method, the contents would be 1,
- * 3, 6 (that is, 1, 1+2, 1+2+3);
+ * {@code 1, 2, 3}, and the reducer operation adds numbers, then
+ * after invocation of this method, the contents would be {@code 1,
+ * 3, 6} (that is, {@code 1, 1+2, 1+2+3}).
* @param reducer the reducer
* @param base the result for an empty array
* @return this (to simplify use in expressions)
@@ -523,17 +522,17 @@ public class ParallelArray extends Ab
/**
* Replaces each element with the cumulation of applying the given
* reducer to all previous values, and returns the total
- * reduction. For example, if the contents are the numbers 1,
- * 2, 3, and the reducer operation adds numbers, then after
- * invocation of this method, the contents would be 0, 1,
- * 3 (that is, 0, 0+1, 0+1+2, and the return value
- * would be 6 (that is, 1+2+3);
+ * reduction. For example, if the contents are the numbers {@code 1,
+ * 2, 3}, and the reducer operation adds numbers, then after
+ * invocation of this method, the contents would be {@code 0, 1,
+ * 3} (that is, {@code 0, 0+1, 0+1+2}, and the return value
+ * would be 6 (that is, {@code 1+2+3}).
* @param reducer the reducer
* @param base the result for an empty array
* @return the total reduction
*/
public T precumulate(Reducer reducer, T base) {
- return (T)(super.precumulate(reducer, base));
+ return super.precumulate(reducer, base);
}
/**
@@ -552,7 +551,7 @@ public class ParallelArray extends Ab
* Sorts the array, assuming all elements are Comparable. Unlike
* Arrays.sort, this sort does not guarantee that elements
* with equal keys maintain their relative position in the array.
- * @throws ClassCastException if any element is not Comparable.
+ * @throws ClassCastException if any element is not Comparable
* @return this (to simplify use in expressions)
*/
public ParallelArray sort() {
@@ -563,7 +562,7 @@ public class ParallelArray extends Ab
/**
* Returns a new ParallelArray containing only the non-null unique
* elements of this array (that is, without any duplicates), using
- * each element's equals method to test for duplication.
+ * each element's {@code equals} method to test for duplication.
* @return the new ParallelArray
*/
public ParallelArray allUniqueElements() {
@@ -658,7 +657,7 @@ public class ParallelArray extends Ab
}
/**
- * Equivalent to asList().addAll but specialized for array
+ * Equivalent to {@code asList().addAll} but specialized for array
* arguments and likely to be more efficient.
* @param other the elements to add
* @return this (to simplify use in expressions)
@@ -716,7 +715,7 @@ public class ParallelArray extends Ab
/**
* Returns an operation prefix that causes a method to operate
* only on the elements of the array for which the given selector
- * returns true
+ * returns true.
* @param selector the selector
* @return operation prefix
*/
@@ -728,7 +727,7 @@ public class ParallelArray extends Ab
/**
* Returns an operation prefix that causes a method to operate
* only on elements for which the given binary selector returns
- * true
+ * true.
* @param selector the selector
* @return operation prefix
*/
@@ -741,7 +740,7 @@ public class ParallelArray extends Ab
/**
* Returns an operation prefix that causes a method to operate
* only on elements for which the given indexed selector returns
- * true
+ * true.
* @param selector the selector
* @return operation prefix
*/
@@ -790,7 +789,7 @@ public class ParallelArray extends Ab
* @param other the other array
* @return operation prefix
* @throws IllegalArgumentException if other array is a
- * filtered view (all filters must precede all mappings).
+ * filtered view (all filters must precede all mappings)
*/
public ParallelArrayWithMapping withMapping
(BinaryOp super T, ? super U, ? extends V> combiner,
@@ -805,7 +804,7 @@ public class ParallelArray extends Ab
* @param other the other array
* @return operation prefix
* @throws IllegalArgumentException if other array is a
- * filtered view (all filters must precede all mappings).
+ * filtered view (all filters must precede all mappings)
*/
public ParallelArrayWithMapping withMapping
(ObjectAndDoubleToObject super T, ? extends V> combiner,
@@ -820,7 +819,7 @@ public class ParallelArray extends Ab
* @param other the other array
* @return operation prefix
* @throws IllegalArgumentException if other array is a
- * filtered view (all filters must precede all mappings).
+ * filtered view (all filters must precede all mappings)
*/
public ParallelArrayWithMapping withMapping
(ObjectAndLongToObject super T, ? extends V> combiner,
@@ -835,7 +834,7 @@ public class ParallelArray extends Ab
* @param other the other array
* @return operation prefix
* @throws IllegalArgumentException if other array is a
- * filtered view (all filters must precede all mappings).
+ * filtered view (all filters must precede all mappings)
*/
public ParallelArrayWithDoubleMapping withMapping
(ObjectAndObjectToDouble super T, ? super U> combiner,
@@ -850,7 +849,7 @@ public class ParallelArray extends Ab
* @param other the other array
* @return operation prefix
* @throws IllegalArgumentException if other array is a
- * filtered view (all filters must precede all mappings).
+ * filtered view (all filters must precede all mappings)
*/
public ParallelArrayWithDoubleMapping withMapping
(ObjectAndDoubleToDouble super T> combiner,
@@ -865,7 +864,7 @@ public class ParallelArray extends Ab
* @param other the other array
* @return operation prefix
* @throws IllegalArgumentException if other array is a
- * filtered view (all filters must precede all mappings).
+ * filtered view (all filters must precede all mappings)
*/
public ParallelArrayWithDoubleMapping withMapping
(ObjectAndLongToDouble super T> combiner,
@@ -880,7 +879,7 @@ public class ParallelArray extends Ab
* @param other the other array
* @return operation prefix
* @throws IllegalArgumentException if other array is a
- * filtered view (all filters must precede all mappings).
+ * filtered view (all filters must precede all mappings)
*/
public ParallelArrayWithLongMapping withMapping
(ObjectAndObjectToLong super T, ? super U> combiner,
@@ -895,7 +894,7 @@ public class ParallelArray extends Ab
* @param other the other array
* @return operation prefix
* @throws IllegalArgumentException if other array is a
- * filtered view (all filters must precede all mappings).
+ * filtered view (all filters must precede all mappings)
*/
public ParallelArrayWithLongMapping withMapping
(ObjectAndDoubleToLong super T> combiner,
@@ -910,7 +909,7 @@ public class ParallelArray extends Ab
* @param other the other array
* @return operation prefix
* @throws IllegalArgumentException if other array is a
- * filtered view (all filters must precede all mappings).
+ * filtered view (all filters must precede all mappings)
*/
public ParallelArrayWithLongMapping withMapping
(ObjectAndLongToLong super T> combiner,
@@ -964,9 +963,9 @@ public class ParallelArray extends Ab
* Returns an iterator stepping through each element of the array
* up to the current limit. This iterator does not
* support the remove operation. However, a full
- * ListIterator supporting add, remove, and set
+ * {@code ListIterator} supporting add, remove, and set
* operations is available via {@link #asList}.
- * @return an iterator stepping through each element.
+ * @return an iterator stepping through each element
*/
public Iterator iterator() {
return new ParallelArrayIterator(array, fence);
@@ -1018,27 +1017,27 @@ public class ParallelArray extends Ab
public int size() { return fence; }
/**
- * Returns the element of the array at the given index
+ * Returns the element of the array at the given index.
* @param i the index
* @return the element of the array at the given index
*/
public T get(int i) { return array[i]; }
/**
- * Sets the element of the array at the given index to the given value
+ * Sets the element of the array at the given index to the given value.
* @param i the index
* @param x the value
*/
public void set(int i, T x) { array[i] = x; }
/**
- * Returns the underlying array used for computations
+ * Returns the underlying array used for computations.
* @return the array
*/
public T[] getArray() { return array; }
/**
- * Equivalent to asList().toString()
+ * Equivalent to {@code asList().toString()}.
* @return a string representation
*/
public String toString() {
@@ -1053,7 +1052,7 @@ public class ParallelArray extends Ab
* than the length of the underlying array, causes computations to
* ignore elements past the given limit.
* @param newLimit the new upper bound
- * @throws IllegalArgumentException if newLimit less than zero.
+ * @throws IllegalArgumentException if newLimit less than zero
*/
public final void setLimit(int newLimit) {
if (newLimit < 0)