Package uk.ac.starlink.util

# Class SplitProcessor<S extends Splittable<S>>

java.lang.Object
uk.ac.starlink.util.SplitProcessor<S>

public abstract class SplitProcessor<S extends Splittable<S>> extends Object
Invokes processing on Splittables.

Instances of this class perform a similar function to that implemented in the Stream class from the Java 8 Streams framework. There is much less functionality and cleverness here, but the behaviour is predictable and permits external iteration rather than imposing internal iteration.

Since:
  9 Sep 2019
Author:
  Mark Taylor

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`SplitProcessor(String name)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`abstract <A> A`
`collect(SplitCollector<S,A> collector, S content)`
Collects content from a splittable object into an accumulator, as defined by a provided collector.
`static <S extends Splittable<S>>
SplitProcessor<S>`
`createBasicParallelProcessor(SplitPolicy policy)`
Returns a SplitProcessor instance that works in parallel, with one accumulator created for every forked subtask.
`static <S extends Splittable<S>>
SplitProcessor<S>`
`createPoolParallelProcessor(SplitPolicy policy)`
Returns a SplitProcessor instance that works in parallel, with a pool of reusable accumulators shared by forked subtasks.
`static <S extends Splittable<S>>
SplitProcessor<S>`
`createSequentialProcessor()`
Returns a SplitProcessor instance that performs sequential processing.
`static <S extends Splittable<S>>
SplitProcessor<S>`
`createStandardProcessor(SplitPolicy policy, boolean isPool)`
Returns a suitable processor instance.
`String`
`toString()`
`abstract boolean`
`willAttemptSplit(S content)`
Indicates whether this processor will attempt to split the given splittable object when processing it.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Constructor Details

### SplitProcessor

protected SplitProcessor(String name)
Constructor.

Parameters:
  `name` - name of this instance

## Method Details

### willAttemptSplit

public abstract boolean willAttemptSplit(S content)
Indicates whether this processor will attempt to split the given splittable object when processing it. If for instance its size is known to be too small for this processor's policy, false will be returned.

Parameters:
  `content` - splittable object
Returns:
  true iff splitting will be attempted during processing

### collect

public abstract <A> A collect(SplitCollector<S,A> collector, S content)
Collects content from a splittable object into an accumulator, as defined by a provided collector.

Parameters:
  `collector` - defines collection semantics
  `content` - input data
Returns:
  accumulator into which content has been collected

### toString

public String toString()

Overrides:
  `toString` in class `Object`

### createSequentialProcessor

public static <S extends Splittable<S>> SplitProcessor<S> createSequentialProcessor()
Returns a SplitProcessor instance that performs sequential processing.

Returns:
  new processor

### createBasicParallelProcessor

public static <S extends Splittable<S>> SplitProcessor<S> createBasicParallelProcessor(SplitPolicy policy)
Returns a SplitProcessor instance that works in parallel, with one accumulator created for every forked subtask.

Parameters:
  `policy` - parallel execution policy, or null for default
Returns:
  new processor

### createPoolParallelProcessor

public static <S extends Splittable<S>> SplitProcessor<S> createPoolParallelProcessor(SplitPolicy policy)
Returns a SplitProcessor instance that works in parallel, with a pool of reusable accumulators shared by forked subtasks. This is expected to be beneficial if accumulator construction or combination is computationally expensive. However, it's probably not necessary when working with accumulators that simply have a large memory footprint, since multiple accumulators ought not to be in simultaneous use either way.

Parameters:
  `policy` - parallel execution policy, or null for default
Returns:
  new processor

### createStandardProcessor

public static <S extends Splittable<S>> SplitProcessor<S> createStandardProcessor(SplitPolicy policy, boolean isPool)
Returns a suitable processor instance. This will defer to one of `createSequentialProcessor`, `createBasicParallelProcessor` or `createPoolParallelProcessor`, depending on its arguments.

Parameters:
  `policy` - parallel execution policy, or null for default
  `isPool` - true to prefer pooling
Returns:
  new processor