jsr166y.forkjoin
Class ParallelArray<T>

java.lang.Object
  extended by jsr166y.forkjoin.ParallelArray<T>
All Implemented Interfaces:
java.lang.Iterable<T>

public class ParallelArray<T>
extends java.lang.Object
implements java.lang.Iterable<T>

An array supporting parallel operations.

A ParallelArray maintains a ForkJoinExecutor and an array in order to provide parallel aggregate operations. The main operations are to apply some procedure to each element, to map each element to a new element, to replace each element, to select a subset of elements based on 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 an array, using one of the static factory methods create(int, java.lang.Class, jsr166y.forkjoin.ForkJoinExecutor), createEmpty(int, java.lang.Class, jsr166y.forkjoin.ForkJoinExecutor), createUsingHandoff(T[], jsr166y.forkjoin.ForkJoinExecutor) and createFromCopy(T[], jsr166y.forkjoin.ForkJoinExecutor). Upon construction, the encapsulated array managed by the ParallelArray must not be shared between threads without external synchronization. In particular, as is the case with any array, access by another thread of an element of a ParallelArray while another operation is in progress has undefined effects.

The ForkJoinExecutor 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 defaultExecutor() across all ParallelArrays. However, you might choose to use different ones for the sake of controlling processor usage, isolating faults, and/or ensuring progress.

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 asList(). The 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 method setLimit(int) along with element-by-element access methods get(int) and set(int, T).

Most operations can be prefixed with range bounds, filters, and mappings using withBounds, withFilter, and withMapping, respectively. For example, aParallelArray.withFilter(aPredicate).all() creates a new ParallelArray containing only those elements matching the predicate. As illustrated below, a mapping often represents accessing some field or invoking some method of an element. These versions are typically more efficient than performing selections, then mappings, then other operations in multiple (parallel) steps. The basic ideas and usages of filtering and mapping are similar to those in database query systems such as SQL, but take a more restrictive form. Series of filter and mapping prefixes may each be cascaded, but all filter prefixes must precede all mapping prefixes, to ensure efficient execution in s single parallel step. Instances of WithFilter etc are useful only as operation prefixes, and should not normally be stored in variables for future use.

This class includes some reductions, such as min, that are commonly useful for most element types, as well as a combined version, summary, that computes all of them in a single parallel step, which is normally more efficient that computing each in turn.

While ParallelArrays can be based on any kind of an object array, including "boxed" types such as Long, parallel operations on scalar "unboxed" type are likely to be substantially more efficient. For this reason, classes ParallelLongArray, and 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 specializations for these other types would add clutter without significantly improving performance beyond that of the Long and Double versions.)

The methods in this class are designed to perform efficiently with both large and small pools, even with single-thread pools on uniprocessors. However, there is some overhead in parallelizing operations, so short computations on small arrays might not execute faster than sequential versions, and might even be slower.

Sample usages. The main difference between programming with plain arrays and 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:

 import static Ops.*;
 class StudentStatistics {
   ParallelArray<Student> students = ...
   // ...
   public double getMaxSeniorGpa() {
     return students.withFilter(isSenior).withMapping(gpaField).max();
   }

   // helpers:
   static final class IsSenior implements Predicate<Student> {
     public boolean evaluate(Student s) { return s.credits > 90; }
   }
   static final IsSenior isSenior = new IsSenior();
   static final class GpaField implements MapperToDouble<Student> {
     public double map(Student s) { return s.gpa; }
   }
   static final GpaField gpaField = new GpaField();
 }
 


Nested Class Summary
static interface ParallelArray.SummaryStatistics<T>
          Summary statistics for a possibly bounded, filtered, and/or mapped ParallelArray.
static class ParallelArray.WithBounds<T>
          A restriction of parallel array operations to apply only within a given range of indices.
static class ParallelArray.WithDoubleMapping<T>
          A modifier for parallel array operations to apply to mappings of elements to doubles, not to the elements themselves
static class ParallelArray.WithFilter<T>
          A restriction of parallel array operations to apply only to elements for which a selector returns true
static class ParallelArray.WithLongMapping<T>
          A modifier for parallel array operations to apply to mappings of elements to longs, not to the elements themselves
static class ParallelArray.WithMapping<T,U>
          A modifier for parallel array operations to apply to mappings of elements, not to the elements themselves
 
Constructor Summary
protected ParallelArray(ForkJoinExecutor executor, T[] array, int limit)
          Constructor for use by subclasses to create a new ParallelArray using the given executor, and initially using the supplied array, with effective size bound by the given limit.
 
Method Summary
 void addAll(ParallelArray.WithBounds<T> other)
          Equivalent to AsList.addAll but specialized for ParallelArray arguments and likely to be more efficient.
 void addAll(ParallelArray<T> other)
          Equivalent to AsList.addAll but specialized for ParallelArray arguments and likely to be more efficient.
 void addAll(T[] other)
          Equivalent to AsList.addAll but specialized for array arguments and likely to be more efficient.
 ParallelArray<T> all()
          Returns a new ParallelArray holding all elements
 ParallelArray<T> all(java.lang.Class<? super T> elementType)
          Returns a new ParallelArray with the given element type holding all elements
 ParallelArray<T> allNonidenticalElements()
          Returns a new ParallelArray containing only the non-null unique elements of this array (that is, without any duplicates).
 ParallelArray<T> allUniqueElements()
          Returns a new ParallelArray containing only the non-null unique elements of this array (that is, without any duplicates).
 void apply(Ops.Procedure<? super T> procedure)
          Applies the given procedure to elements
 java.util.List<T> asList()
          Returns a view of this ParallelArray as a List.
 int binarySearch(T target)
          Assuming this array is sorted, returns the index of an element equal to given target, or -1 if not present.
 int binarySearch(T target, java.util.Comparator<? super T> comparator)
          Assuming this array is sorted with respect to the given comparator, returns the index of an element equal to given target, or -1 if not present.
<U,V> ParallelArray<V>
combine(ParallelArray.WithBounds<? extends U> other, Ops.Combiner<? super T,? super U,? extends V> combiner)
          Returns a ParallelArray containing results of applying combine(thisElement, otherElement) for each element.
<U,V> ParallelArray<V>
combine(ParallelArray.WithBounds<? extends U> other, Ops.Combiner<? super T,? super U,? extends V> combiner, java.lang.Class<? super V> elementType)
          Returns a ParallelArray containing results of applying combine(thisElement, otherElement) for each element.
<U,V> ParallelArray<V>
combine(ParallelArray<? extends U> other, Ops.Combiner<? super T,? super U,? extends V> combiner)
          Returns a ParallelArray containing results of applying combine(thisElement, otherElement) for each element.
<U,V> ParallelArray<V>
combine(ParallelArray<? extends U> other, Ops.Combiner<? super T,? super U,? extends V> combiner, java.lang.Class<? super V> elementType)
          Returns a ParallelArray containing results of applying combine(thisElement, otherElement) for each element.
<U,V> ParallelArray<V>
combine(U[] other, Ops.Combiner<? super T,? super U,? extends V> combiner)
          Returns a ParallelArray containing results of applying combine(thisElement, otherElement) for each element.
<U,V> ParallelArray<V>
combine(U[] other, Ops.Combiner<? super T,? super U,? extends V> combiner, java.lang.Class<? super V> elementType)
          Returns a ParallelArray containing results of applying combine(thisElement, otherElement) for each element.
static
<T> ParallelArray<T>
create(int size, java.lang.Class<? super T> elementType, ForkJoinExecutor executor)
          Creates a new ParallelArray using the given executor and an array of the given size constructed using the indicated base element type.
static
<T> ParallelArray<T>
createEmpty(int size, java.lang.Class<? super T> elementType, ForkJoinExecutor executor)
          Creates a new ParallelArray using the given executor and an array of the given size constructed using the indicated base element type, but with an initial effective size of zero, enabling incremental insertion via asList() operations.
static
<T> ParallelArray<T>
createFromCopy(int size, T[] source, ForkJoinExecutor executor)
          Creates a new ParallelArray using an array of the given size, initially holding copies of the given source truncated or padded with nulls to obtain the specified length.
static
<T> ParallelArray<T>
createFromCopy(T[] source, ForkJoinExecutor executor)
          Creates a new ParallelArray using the given executor and initially holding copies of the given source elements.
static
<T> ParallelArray<T>
createUsingHandoff(T[] handoff, ForkJoinExecutor executor)
          Creates a new ParallelArray initially using the given array and executor.
 void cumulate(Ops.Reducer<T> reducer, T base)
          Replaces each element with the running cumulation of applying the given reducer.
static ForkJoinExecutor defaultExecutor()
          Returns a common default executor for use in ParallelArrays.
 T get(int i)
          Returns the element of the array at the given index
 T[] getArray()
          Returns the underlying array used for computations
 ForkJoinExecutor getExecutor()
          Returns the executor used for computations
 int indexOf(T target)
          Returns the index of some element equal to given target, or -1 if not present
 java.util.Iterator<T> iterator()
          Returns an iterator stepping through each element of the array up to the current limit.
 T max()
          Returns the maximum element, or null if empty assuming that all elements are Comparables
 T max(java.util.Comparator<? super T> comparator)
          Returns the maximum element, or null if empty
 T min()
          Returns the minimum element, or null if empty, assuming that all elements are Comparables
 T min(java.util.Comparator<? super T> comparator)
          Returns the minimum element, or null if empty
 T precumulate(Ops.Reducer<T> reducer, T base)
          Replaces each element with the cumulation of applying the given reducer to all previous values, and returns the total reduction.
 T reduce(Ops.Reducer<T> reducer, T base)
          Returns reduction of elements
 void removeConsecutiveDuplicates()
          Removes consecutive elements that are equal (or null), shifting others leftward, and possibly decreasing size.
 void removeNulls()
          Removes null elements, shifting others leftward, and possibly decreasing size.
 void replaceWithCombination(ParallelArray.WithBounds<? extends T> other, Ops.Reducer<T> combiner)
          Replaces elements with results of applying combine(thisElement, otherElement)
 void replaceWithCombination(ParallelArray<? extends T> other, Ops.Reducer<T> combiner)
          Replaces elements with results of applying combine(thisElement, otherElement)
 void replaceWithCombination(T[] other, Ops.Reducer<T> combiner)
          Replaces elements with results of applying combine(thisElement, otherElement)
 void replaceWithGeneratedValue(Ops.Generator<? extends T> generator)
          Replaces elements with the results of applying the given generator.
 void replaceWithMappedIndex(Ops.MapperFromInt<? extends T> mapper)
          Replaces elements with the results of applying the given mapper to their indices.
 void replaceWithTransform(Ops.Mapper<? super T,? extends T> mapper)
          Replaces elements with the results of applying the given mapper to their current values.
 void replaceWithValue(T value)
          Replaces elements with the given value.
 void set(int i, T x)
          Sets the element of the array at the given index to the given value
 void setLimit(int newLimit)
          Ensures that the underlying array can be accessed up to the given upper bound, reallocating and copying the underlying array to expand if necessary.
 int size()
          Returns the effective size of the underlying array.
 void sort()
          Sorts the array, assuming all elements are Comparable.
 void sort(java.util.Comparator<? super T> comparator)
          Sorts the array.
 ParallelArray.SummaryStatistics<T> summary()
          Returns summary statistics, assuming that all elements are Comparables
 ParallelArray.SummaryStatistics<T> summary(java.util.Comparator<? super T> comparator)
          Returns summary statistics, using the given comparator to locate minimum and maximum elements.
 java.lang.String toString()
          Equivalent to asList().toString()
 ParallelArray.WithBounds<T> withBounds(int firstIndex, int upperBound)
          Returns an operation prefix that causes a method to operate only on the elements of the array between firstIndex (inclusive) and upperBound (exclusive).
 ParallelArray.WithFilter<T> withFilter(Ops.Predicate<? super T> selector)
          Returns an operation prefix that causes a method to operate only on the elements of the array for which the given selector returns true
<U> ParallelArray.WithMapping<T,U>
withMapping(Ops.Mapper<? super T,? extends U> mapper)
          Returns an operation prefix that causes a method to operate on mapped elements of the array using the given mapper.
 ParallelArray.WithDoubleMapping<T> withMapping(Ops.MapperToDouble<? super T> mapper)
          Returns an operation prefix that causes a method to operate on mapped elements of the array using the given mapper.
 ParallelArray.WithLongMapping<T> withMapping(Ops.MapperToLong<? super T> mapper)
          Returns an operation prefix that causes a method to operate on mapped elements of the array using the given mapper.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ParallelArray

protected ParallelArray(ForkJoinExecutor executor,
                        T[] array,
                        int limit)
Constructor for use by subclasses to create a new ParallelArray using the given executor, and initially using the supplied array, with effective size bound by the given limit. This constructor is designed to enable extensions via subclassing. To create a ParallelArray, use create(int, java.lang.Class, jsr166y.forkjoin.ForkJoinExecutor), createEmpty(int, java.lang.Class, jsr166y.forkjoin.ForkJoinExecutor), createUsingHandoff(T[], jsr166y.forkjoin.ForkJoinExecutor) or createFromCopy(T[], jsr166y.forkjoin.ForkJoinExecutor).

Parameters:
executor - the executor
array - the array
limit - the upper bound limit
Method Detail

defaultExecutor

public static ForkJoinExecutor defaultExecutor()
Returns a common default executor for use in ParallelArrays. This executor arranges enough parallelism to use most, but not necessarily all, of the avaliable processors on this system.

Returns:
the executor

create

public static <T> ParallelArray<T> create(int size,
                                          java.lang.Class<? super T> elementType,
                                          ForkJoinExecutor executor)
Creates a new ParallelArray using the given executor and an array of the given size constructed using the indicated base element type.

Parameters:
size - the array size
elementType - the type of the elements
executor - the executor

createUsingHandoff

public static <T> ParallelArray<T> createUsingHandoff(T[] handoff,
                                                      ForkJoinExecutor executor)
Creates a new ParallelArray initially using the given array and executor. In general, the handed off array should not be used for other purposes once constructing this ParallelArray. The given array may be internally replaced by another array in the course of methods that add or remove elements.

Parameters:
handoff - the array
executor - the executor

createFromCopy

public static <T> ParallelArray<T> createFromCopy(T[] source,
                                                  ForkJoinExecutor executor)
Creates a new ParallelArray using the given executor and initially holding copies of the given source elements.

Parameters:
source - the source of initial elements
executor - the executor

createFromCopy

public static <T> ParallelArray<T> createFromCopy(int size,
                                                  T[] source,
                                                  ForkJoinExecutor executor)
Creates a new ParallelArray using an array of the given size, initially holding copies of the given source truncated or padded with nulls to obtain the specified length.

Parameters:
source - the source of initial elements
size - the array size
executor - the executor

createEmpty

public static <T> ParallelArray<T> createEmpty(int size,
                                               java.lang.Class<? super T> elementType,
                                               ForkJoinExecutor executor)
Creates a new ParallelArray using the given executor and an array of the given size constructed using the indicated base element type, but with an initial effective size of zero, enabling incremental insertion via asList() operations.

Parameters:
size - the array size
elementType - the type of the elements
executor - the executor

getExecutor

public ForkJoinExecutor getExecutor()
Returns the executor used for computations

Returns:
the executor

apply

public void apply(Ops.Procedure<? super T> procedure)
Applies the given procedure to elements

Parameters:
procedure - the procedure

reduce

public T reduce(Ops.Reducer<T> reducer,
                T base)
Returns reduction of elements

Parameters:
reducer - the reducer
base - the result for an empty array
Returns:
reduction

all

public ParallelArray<T> all()
Returns a new ParallelArray holding all elements

Returns:
a new ParallelArray holding all elements

all

public ParallelArray<T> all(java.lang.Class<? super T> elementType)
Returns a new ParallelArray with the given element type holding all elements

Parameters:
elementType - the type of the elements
Returns:
a new ParallelArray holding all elements

combine

public <U,V> ParallelArray<V> combine(U[] other,
                                      Ops.Combiner<? super T,? super U,? extends V> combiner)
Returns a ParallelArray containing results of applying combine(thisElement, otherElement) for each element.

Parameters:
other - the other array
combiner - the combiner
Returns:
the array of mappings
Throws:
java.lang.ArrayIndexOutOfBoundsException - if other array is shorter than this array.

combine

public <U,V> ParallelArray<V> combine(ParallelArray<? extends U> other,
                                      Ops.Combiner<? super T,? super U,? extends V> combiner)
Returns a ParallelArray containing results of applying combine(thisElement, otherElement) for each element.

Parameters:
other - the other array
combiner - the combiner
Returns:
the array of mappings
Throws:
java.lang.ArrayIndexOutOfBoundsException - if other array is not the same length as this array.

combine

public <U,V> ParallelArray<V> combine(U[] other,
                                      Ops.Combiner<? super T,? super U,? extends V> combiner,
                                      java.lang.Class<? super V> elementType)
Returns a ParallelArray containing results of applying combine(thisElement, otherElement) for each element.

Parameters:
other - the other array
combiner - the combiner
elementType - the type of elements of returned array
Returns:
the array of mappings
Throws:
java.lang.ArrayIndexOutOfBoundsException - if other array is shorter than this array.

combine

public <U,V> ParallelArray<V> combine(ParallelArray.WithBounds<? extends U> other,
                                      Ops.Combiner<? super T,? super U,? extends V> combiner)
Returns a ParallelArray containing results of applying combine(thisElement, otherElement) for each element.

Parameters:
other - the other array segment
combiner - the combiner
Returns:
the array of mappings
Throws:
java.lang.ArrayIndexOutOfBoundsException - if other segment is shorter than this array.

combine

public <U,V> ParallelArray<V> combine(ParallelArray.WithBounds<? extends U> other,
                                      Ops.Combiner<? super T,? super U,? extends V> combiner,
                                      java.lang.Class<? super V> elementType)
Returns a ParallelArray containing results of applying combine(thisElement, otherElement) for each element.

Parameters:
other - the other array segment
combiner - the combiner
elementType - the type of elements of returned array
Returns:
the array of mappings
Throws:
java.lang.ArrayIndexOutOfBoundsException - if other array is shorter than this array.

combine

public <U,V> ParallelArray<V> combine(ParallelArray<? extends U> other,
                                      Ops.Combiner<? super T,? super U,? extends V> combiner,
                                      java.lang.Class<? super V> elementType)
Returns a ParallelArray containing results of applying combine(thisElement, otherElement) for each element.

Parameters:
other - the other array
combiner - the combiner
elementType - the type of elements of returned array
Returns:
the array of mappings
Throws:
java.lang.ArrayIndexOutOfBoundsException - if other array is not the same length as this array.

replaceWithTransform

public void replaceWithTransform(Ops.Mapper<? super T,? extends T> mapper)
Replaces elements with the results of applying the given mapper to their current values.

Parameters:
mapper - the mapper

replaceWithMappedIndex

public void replaceWithMappedIndex(Ops.MapperFromInt<? extends T> mapper)
Replaces elements with the results of applying the given mapper to their indices.

Parameters:
mapper - the mapper

replaceWithGeneratedValue

public void replaceWithGeneratedValue(Ops.Generator<? extends T> generator)
Replaces elements with the results of applying the given generator.

Parameters:
generator - the generator

replaceWithValue

public void replaceWithValue(T value)
Replaces elements with the given value.

Parameters:
value - the value

replaceWithCombination

public void replaceWithCombination(ParallelArray<? extends T> other,
                                   Ops.Reducer<T> combiner)
Replaces elements with results of applying combine(thisElement, otherElement)

Parameters:
other - the other array
combiner - the combiner
Throws:
java.lang.ArrayIndexOutOfBoundsException - if other array has fewer elements than this array.

replaceWithCombination

public void replaceWithCombination(T[] other,
                                   Ops.Reducer<T> combiner)
Replaces elements with results of applying combine(thisElement, otherElement)

Parameters:
other - the other array
combiner - the combiner
Throws:
java.lang.ArrayIndexOutOfBoundsException - if other array has fewer elements than this array.

replaceWithCombination

public void replaceWithCombination(ParallelArray.WithBounds<? extends T> other,
                                   Ops.Reducer<T> combiner)
Replaces elements with results of applying combine(thisElement, otherElement)

Parameters:
other - the other array segment
combiner - the combiner
Throws:
java.lang.ArrayIndexOutOfBoundsException - if other segment has fewer elements.than this array,

indexOf

public int indexOf(T target)
Returns the index of some element equal to given target, or -1 if not present

Parameters:
target - the element to search for
Returns:
the index or -1 if not present

binarySearch

public int binarySearch(T target)
Assuming this array is sorted, returns the index of an element equal to given target, or -1 if not present. If the array is not sorted, the results are undefined.

Parameters:
target - the element to search for
Returns:
the index or -1 if not present

binarySearch

public int binarySearch(T target,
                        java.util.Comparator<? super T> comparator)
Assuming this array is sorted with respect to the given comparator, returns the index of an element equal to given target, or -1 if not present. If the array is not sorted, the results are undefined.

Parameters:
target - the element to search for
comparator - the comparator
Returns:
the index or -1 if not present

summary

public ParallelArray.SummaryStatistics<T> summary(java.util.Comparator<? super T> comparator)
Returns summary statistics, using the given comparator to locate minimum and maximum elements.

Parameters:
comparator - the comparator to use for locating minimum and maximum elements
Returns:
the summary.

summary

public ParallelArray.SummaryStatistics<T> summary()
Returns summary statistics, assuming that all elements are Comparables

Returns:
the summary.

min

public T min(java.util.Comparator<? super T> comparator)
Returns the minimum element, or null if empty

Parameters:
comparator - the comparator
Returns:
minimum element, or null if empty

min

public T min()
Returns the minimum element, or null if empty, assuming that all elements are Comparables

Returns:
minimum element, or null if empty
Throws:
java.lang.ClassCastException - if any element is not Comparable.

max

public T max(java.util.Comparator<? super T> comparator)
Returns the maximum element, or null if empty

Parameters:
comparator - the comparator
Returns:
maximum element, or null if empty

max

public T max()
Returns the maximum element, or null if empty assuming that all elements are Comparables

Returns:
maximum element, or null if empty
Throws:
java.lang.ClassCastException - if any element is not Comparable.

cumulate

public void cumulate(Ops.Reducer<T> reducer,
                     T base)
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);

Parameters:
reducer - the reducer
base - the result for an empty array

precumulate

public T precumulate(Ops.Reducer<T> reducer,
                     T base)
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);

Parameters:
reducer - the reducer
base - the result for an empty array
Returns:
the total reduction

sort

public void sort(java.util.Comparator<? super T> comparator)
Sorts the array. Unlike Arrays.sort, this sort does not guarantee that elements with equal keys maintain their relative position in the array.

Parameters:
comparator - the comparator to use

sort

public void sort()
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:
java.lang.ClassCastException - if any element is not Comparable.

removeConsecutiveDuplicates

public void removeConsecutiveDuplicates()
Removes consecutive elements that are equal (or null), shifting others leftward, and possibly decreasing size. This method uses each non-null element's equals method to test for duplication. This method may be used after sorting to ensure that this ParallelArray contains a set of unique elements.


removeNulls

public void removeNulls()
Removes null elements, shifting others leftward, and possibly decreasing size.


allUniqueElements

public ParallelArray<T> allUniqueElements()
Returns a new ParallelArray containing only the non-null unique elements of this array (that is, without any duplicates). This method uses each element's equals method to test for duplication.

Returns:
the new ParallelArray

allNonidenticalElements

public ParallelArray<T> allNonidenticalElements()
Returns a new ParallelArray containing only the non-null unique elements of this array (that is, without any duplicates). This method uses reference identity to test for duplication.

Returns:
the new ParallelArray

withBounds

public ParallelArray.WithBounds<T> withBounds(int firstIndex,
                                              int upperBound)
Returns an operation prefix that causes a method to operate only on the elements of the array between firstIndex (inclusive) and upperBound (exclusive).

Parameters:
firstIndex - the lower bound (inclusive)
upperBound - the upper bound (exclusive)
Returns:
operation prefix

withFilter

public ParallelArray.WithFilter<T> withFilter(Ops.Predicate<? super T> selector)
Returns an operation prefix that causes a method to operate only on the elements of the array for which the given selector returns true

Parameters:
selector - the selector
Returns:
operation prefix

withMapping

public <U> ParallelArray.WithMapping<T,U> withMapping(Ops.Mapper<? super T,? extends U> mapper)
Returns an operation prefix that causes a method to operate on mapped elements of the array using the given mapper.

Parameters:
mapper - the mapper
Returns:
operation prefix

withMapping

public ParallelArray.WithDoubleMapping<T> withMapping(Ops.MapperToDouble<? super T> mapper)
Returns an operation prefix that causes a method to operate on mapped elements of the array using the given mapper.

Parameters:
mapper - the mapper
Returns:
operation prefix

withMapping

public ParallelArray.WithLongMapping<T> withMapping(Ops.MapperToLong<? super T> mapper)
Returns an operation prefix that causes a method to operate on mapped elements of the array using the given mapper.

Parameters:
mapper - the mapper
Returns:
operation prefix

iterator

public java.util.Iterator<T> iterator()
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 operations is available via asList().

Specified by:
iterator in interface java.lang.Iterable<T>
Returns:
an iterator stepping through each element.

asList

public java.util.List<T> asList()
Returns a view of this ParallelArray as a List. This List has the same structural and performance characteristics as ArrayList, and may be used to modify, replace or extend the bounds of the array underlying this ParallelArray. The methods supported by this list view are not in general implemented as parallel operations. This list is also not itself thread-safe. In particular, performing list updates while other parallel operations are in progress has undefined (and surely undesired) effects.

Returns:
a list view

size

public int size()
Returns the effective size of the underlying array. The effective size is the current limit, if used (see setLimit(int)), or the length of the array otherwise.

Returns:
the effective size of array

get

public T get(int i)
Returns the element of the array at the given index

Parameters:
i - the index
Returns:
the element of the array at the given index

set

public void set(int i,
                T x)
Sets the element of the array at the given index to the given value

Parameters:
i - the index
x - the value

getArray

public T[] getArray()
Returns the underlying array used for computations

Returns:
the array

toString

public java.lang.String toString()
Equivalent to asList().toString()

Overrides:
toString in class java.lang.Object
Returns:
a string representation

addAll

public void addAll(T[] other)
Equivalent to AsList.addAll but specialized for array arguments and likely to be more efficient.

Parameters:
other - the elements to add

addAll

public void addAll(ParallelArray<T> other)
Equivalent to AsList.addAll but specialized for ParallelArray arguments and likely to be more efficient.

Parameters:
other - the elements to add

addAll

public void addAll(ParallelArray.WithBounds<T> other)
Equivalent to AsList.addAll but specialized for ParallelArray arguments and likely to be more efficient.

Parameters:
other - the elements to add

setLimit

public final void setLimit(int newLimit)
Ensures that the underlying array can be accessed up to the given upper bound, reallocating and copying the underlying array to expand if necessary. Or, if the given limit is less than the length of the underlying array, causes computations to ignore elements past the given limit.

Parameters:
newLimit - the new upper bound
Throws:
java.lang.IllegalArgumentException - if newLimit less than zero.