| 42 |
|
* <p>A ParallelArray is not a List. It relies on random access across |
| 43 |
|
* array elements to support efficient parallel operations. However, |
| 44 |
|
* a ParallelArray can be viewed and manipulated as a List, via method |
| 45 |
< |
* {@link ParallelArray#asList}. The <tt>asList</tt> view allows |
| 45 |
> |
* {@link ParallelArray#asList}. The {@code asList} view allows |
| 46 |
|
* incremental insertion and modification of elements while setting up |
| 47 |
|
* a ParallelArray, generally before using it for parallel |
| 48 |
|
* operations. Similarly, the list view may be useful when accessing |
| 49 |
|
* the results of computations in sequential contexts. A |
| 50 |
|
* ParallelArray may also be created using the elements of any other |
| 51 |
|
* Collection, by constructing from the array returned by the |
| 52 |
< |
* Collection's <tt>toArray</tt> method. The effects of mutative |
| 53 |
< |
* <tt>asList</tt> operations may also be achieved directly using |
| 52 |
> |
* Collection's {@code toArray} method. The effects of mutative |
| 53 |
> |
* {@code asList} operations may also be achieved directly using |
| 54 |
|
* method {@link #setLimit} along with element-by-element access |
| 55 |
|
* methods {@link #get}</tt> and {@link #set}. |
| 56 |
|
* |
| 61 |
|
* {@link ParallelDoubleArray} are also supplied, and designed to |
| 62 |
|
* smoothly interoperate with ParallelArrays. You should also use a |
| 63 |
|
* ParallelLongArray for processing other integral scalar data |
| 64 |
< |
* (<tt>int</tt>, <tt>short</tt>, etc). And similarly use a |
| 65 |
< |
* ParallelDoubleArray for <tt>float</tt> data. (Further |
| 64 |
> |
* ({@code int}, {@code short}, etc). And similarly use a |
| 65 |
> |
* ParallelDoubleArray for {@code float} data. (Further |
| 66 |
|
* specializations for these other types would add clutter without |
| 67 |
|
* significantly improving performance beyond that of the Long and |
| 68 |
|
* Double versions.) |
| 70 |
|
* <p>Most usages of ParallelArray involve sets of operations prefixed |
| 71 |
|
* with range bounds, filters, and mappings (including mappings that |
| 72 |
|
* combine elements from other ParallelArrays), using |
| 73 |
< |
* <tt>withBounds</tt>, <tt>withFilter</tt>, and <tt>withMapping</tt>, |
| 73 |
> |
* {@code withBounds}, {@code withFilter}, and {@code withMapping}, |
| 74 |
|
* respectively. For example, |
| 75 |
< |
* <tt>aParallelArray.withFilter(aPredicate).all()</tt> creates a new |
| 75 |
> |
* {@code aParallelArray.withFilter(aPredicate).all()} creates a new |
| 76 |
|
* ParallelArray containing only those elements matching the |
| 77 |
|
* predicate. And for ParallelLongArrays a, b, and c, |
| 78 |
< |
* <tt>a.withMapping(CommonOps.longAdder(),b).withMapping(CommonOps.longAdder(),c).min()</tt> |
| 78 |
> |
* {@code a.withMapping(CommonOps.longAdder(),b).withMapping(CommonOps.longAdder(),c).min()} |
| 79 |
|
* returns the minimum value of a[i]+b[i]+c[i] for all i. As |
| 80 |
|
* illustrated below, a <em>mapping</em> often represents accessing |
| 81 |
|
* some field or invoking some method of an element. These versions |
| 87 |
|
* be cascaded, but all filter prefixes must precede all mapping |
| 88 |
|
* prefixes, to ensure efficient execution in a single parallel step. |
| 89 |
|
* In cases of combined mapping expressions, this rule is only |
| 90 |
< |
* dynamically enforced. For example, <tt>pa.withMapping(op, |
| 91 |
< |
* pb.withFilter(f))</tt> will compile but throw an exception upon |
| 90 |
> |
* dynamically enforced. For example, {@code pa.withMapping(op, |
| 91 |
> |
* pb.withFilter(f))} will compile but throw an exception upon |
| 92 |
|
* execution because the filter precedes the mapping. |
| 93 |
|
* |
| 94 |
|
* <p>While series of filters and mappings are allowed, it is |
| 95 |
|
* usually more efficient to combine them into single filters or |
| 96 |
|
* mappings when possible. For example |
| 97 |
< |
* <tt>pa.withMapping(addOne).withMapping(addOne)</tt> is generally |
| 98 |
< |
* less efficient than <tt>pa.withMapping(addTwo)</tt>. Methods |
| 99 |
< |
* <tt>withIndexedFilter</tt> and <tt>withIndexedMapping</tt> may be |
| 97 |
> |
* {@code pa.withMapping(addOne).withMapping(addOne)} is generally |
| 98 |
> |
* less efficient than {@code pa.withMapping(addTwo)}. Methods |
| 99 |
> |
* {@code withIndexedFilter} and {@code withIndexedMapping} may be |
| 100 |
|
* useful when combining such expressions. |
| 101 |
|
* |
| 102 |
< |
* <p>This class includes some reductions, such as <tt>min</tt>, that |
| 102 |
> |
* <p>This class includes some reductions, such as {@code min}, that |
| 103 |
|
* are commonly useful for most element types, as well as a combined |
| 104 |
< |
* version, <tt>summary</tt>, that computes all of them in a single |
| 104 |
> |
* version, {@code summary}, that computes all of them in a single |
| 105 |
|
* parallel step, which is normally more efficient than computing each |
| 106 |
|
* in turn. |
| 107 |
|
* |
| 117 |
|
* programming with aggregates is that you must separately define each |
| 118 |
|
* of the component functions on elements. For example, the following |
| 119 |
|
* returns the maximum Grade Point Average across all senior students, |
| 120 |
< |
* given a (fictional) <tt>Student</tt> class: |
| 120 |
> |
* given a (fictional) {@code Student} class: |
| 121 |
|
* |
| 122 |
|
* <pre> |
| 123 |
|
* import static Ops.*; |
| 386 |
|
|
| 387 |
|
/** |
| 388 |
|
* Replaces elements with results of applying |
| 389 |
< |
* <tt>op(thisElement, otherElement)</tt>. |
| 389 |
> |
* {@code op(thisElement, otherElement)}. |
| 390 |
|
* @param other the other array |
| 391 |
|
* @param combiner the combiner |
| 392 |
|
* @return this (to simplify use in expressions) |
| 400 |
|
|
| 401 |
|
/** |
| 402 |
|
* Replaces elements with results of applying |
| 403 |
< |
* <tt>op(thisElement, otherElement)</tt>. |
| 403 |
> |
* {@code op(thisElement, otherElement)}. |
| 404 |
|
* @param other the other array |
| 405 |
|
* @param combiner the combiner |
| 406 |
|
* @return this (to simplify use in expressions) |
| 507 |
|
/** |
| 508 |
|
* Replaces each element with the running cumulation of applying |
| 509 |
|
* the given reducer. For example, if the contents are the numbers |
| 510 |
< |
* <tt>1, 2, 3</tt>, and the reducer operation adds numbers, then |
| 511 |
< |
* after invocation of this method, the contents would be <tt>1, |
| 512 |
< |
* 3, 6</tt> (that is, <tt>1, 1+2, 1+2+3</tt>); |
| 510 |
> |
* {@code 1, 2, 3}, and the reducer operation adds numbers, then |
| 511 |
> |
* after invocation of this method, the contents would be {@code 1, |
| 512 |
> |
* 3, 6} (that is, {@code 1, 1+2, 1+2+3}); |
| 513 |
|
* @param reducer the reducer |
| 514 |
|
* @param base the result for an empty array |
| 515 |
|
* @return this (to simplify use in expressions) |
| 522 |
|
/** |
| 523 |
|
* Replaces each element with the cumulation of applying the given |
| 524 |
|
* reducer to all previous values, and returns the total |
| 525 |
< |
* reduction. For example, if the contents are the numbers <tt>1, |
| 526 |
< |
* 2, 3</tt>, and the reducer operation adds numbers, then after |
| 527 |
< |
* invocation of this method, the contents would be <tt>0, 1, |
| 528 |
< |
* 3</tt> (that is, <tt>0, 0+1, 0+1+2</tt>, and the return value |
| 529 |
< |
* would be 6 (that is, <tt> 1+2+3</tt>); |
| 525 |
> |
* reduction. For example, if the contents are the numbers {@code 1, |
| 526 |
> |
* 2, 3}, and the reducer operation adds numbers, then after |
| 527 |
> |
* invocation of this method, the contents would be {@code 0, 1, |
| 528 |
> |
* 3} (that is, {@code 0, 0+1, 0+1+2}, and the return value |
| 529 |
> |
* would be 6 (that is, {@code 1+2+3}); |
| 530 |
|
* @param reducer the reducer |
| 531 |
|
* @param base the result for an empty array |
| 532 |
|
* @return the total reduction |
| 562 |
|
/** |
| 563 |
|
* Returns a new ParallelArray containing only the non-null unique |
| 564 |
|
* elements of this array (that is, without any duplicates), using |
| 565 |
< |
* each element's <tt>equals</tt> method to test for duplication. |
| 565 |
> |
* each element's {@code equals} method to test for duplication. |
| 566 |
|
* @return the new ParallelArray |
| 567 |
|
*/ |
| 568 |
|
public ParallelArray<T> allUniqueElements() { |
| 657 |
|
} |
| 658 |
|
|
| 659 |
|
/** |
| 660 |
< |
* Equivalent to <tt>asList().addAll</tt> but specialized for array |
| 660 |
> |
* Equivalent to {@code asList().addAll} but specialized for array |
| 661 |
|
* arguments and likely to be more efficient. |
| 662 |
|
* @param other the elements to add |
| 663 |
|
* @return this (to simplify use in expressions) |
| 963 |
|
* Returns an iterator stepping through each element of the array |
| 964 |
|
* up to the current limit. This iterator does <em>not</em> |
| 965 |
|
* support the remove operation. However, a full |
| 966 |
< |
* <tt>ListIterator</tt> supporting add, remove, and set |
| 966 |
> |
* {@code ListIterator} supporting add, remove, and set |
| 967 |
|
* operations is available via {@link #asList}. |
| 968 |
|
* @return an iterator stepping through each element |
| 969 |
|
*/ |
| 1037 |
|
public T[] getArray() { return array; } |
| 1038 |
|
|
| 1039 |
|
/** |
| 1040 |
< |
* Equivalent to <tt>asList().toString()</tt> |
| 1040 |
> |
* Equivalent to {@code asList().toString()} |
| 1041 |
|
* @return a string representation |
| 1042 |
|
*/ |
| 1043 |
|
public String toString() { |
