--- jsr166/src/extra166y/ParallelArray.java 2011/12/05 04:08:47 1.3 +++ jsr166/src/extra166y/ParallelArray.java 2013/02/15 22:27:11 1.13 @@ -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 { /* @@ -273,26 +272,26 @@ public class ParallelArray extends Ab * mapped ParallelArray. */ public static interface SummaryStatistics { - /** Return the number of elements */ + /** Returns the number of elements */ public int size(); - /** Return the minimum element, or null if empty */ + /** Returns the minimum element, or null if empty */ public T min(); - /** Return the maximum element, or null if empty */ + /** Returns the maximum element, or null if empty */ public T max(); - /** Return the index of the minimum element, or -1 if empty */ + /** Returns the index of the minimum element, or -1 if empty */ public int indexOfMin(); - /** Return the index of the maximum element, or -1 if empty */ + /** Returns the index of the maximum element, or -1 if empty */ public int indexOfMax(); } /** - * Returns the executor used for computations + * Returns the executor used for computations. * @return the executor */ 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 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 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 */ @@ -756,7 +755,7 @@ public class ParallelArray extends Ab * @param op the op * @return operation prefix */ - public ParallelArrayWithMapping withMapping + public ParallelArrayWithMapping withMapping (Op op) { return super.withMapping(op); } @@ -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 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 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 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 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 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 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 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 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 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) @@ -1096,7 +1095,7 @@ public class ParallelArray extends Ab } /** - * Make len slots available at index + * Makes len slots available at index. */ final void insertSlotsAt(int index, int len) { if (len <= 0)