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 java.lang.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

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `SplitProcessor(java.lang.String name)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and 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.
    `java.lang.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 Detail

    - #### SplitProcessor

          protected SplitProcessor(java.lang.String name)

      Constructor.
      Parameters:
        `name` - name of this instance

  - ### Method Detail

    - #### 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 java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.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