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 |
533 |
|
*/ |
534 |
|
public T precumulate(Reducer<T> reducer, T base) { |
535 |
< |
return (T)(super.precumulate(reducer, base)); |
535 |
> |
return super.precumulate(reducer, base); |
536 |
|
} |
537 |
|
|
538 |
|
/** |
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() { |