uk.ac.starlink.util

## Class SplitPolicy

- java.lang.Object
- - uk.ac.starlink.util.SplitPolicy

-     public class SplitPolicy
      extends java.lang.Object

  Defines the details of a concurrency policy as used by SplitProcessor.
  Since:
    5 Nov 2019

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static short` | `DFLT_MAX_TASKS_PER_CORE` Default value for maximum average number of subtasks per core.
    `static int` | `DFLT_MIN_TASK_SIZE` Default value for minimum subtask size.
    `static SplitPolicy` | `DFLT_POLICY` Default splitting policy.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SplitPolicy()` Constructs a policy with default configuration.
    `SplitPolicy(java.util.function.Supplier<java.util.concurrent.ForkJoinPool> fjPoolSupplier, int minTaskSize, short maxTasksPerCore)` Constructs a policy with supplied configuration options.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.concurrent.ForkJoinPool` | `getForkJoinPool()` Returns the ForkJoinPool used by this policy.
    `short` | `getMaxTasksPerCore()` Returns the maximum number of tasks (on average) to be executed on each core as a result of decomposition, or zero for no limit.
    `int` | `getMinTaskSize()` Returns the smallest task size used by this policy.
    `java.lang.String` | `toString()`
    `boolean` | `willAttemptSplit(Splittable<?> content)` Indicates whether an attempt should be made to split a splittable in order to process it.

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

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

- - ### Field Detail

    - #### DFLT_MIN_TASK_SIZE

          public static final int DFLT_MIN_TASK_SIZE

      Default value for minimum subtask size. The current value for this is conservative, in that it will not result in concurrency for relatively small jobs. The (JDK8) `ForkJoinTask` javadocs recommend as a rough rule of thumb a value in the range of 1e2-1e4 steps, so this possibly could be reduced.
      See Also:
        Constant Field Values

    - #### DFLT_MAX_TASKS_PER_CORE

          public static final short DFLT_MAX_TASKS_PER_CORE

      Default value for maximum average number of subtasks per core. The value of 8 is suggested by the example parallel computation framework sketch in the (JDK8) `Spliterator` javadocs.
      See Also:
        Constant Field Values

    - #### DFLT_POLICY

          public static final SplitPolicy DFLT_POLICY

      Default splitting policy.

  - ### Constructor Detail

    - #### SplitPolicy

          public SplitPolicy()

      Constructs a policy with default configuration.

    - #### SplitPolicy

          public SplitPolicy(java.util.function.Supplier<java.util.concurrent.ForkJoinPool> fjPoolSupplier,
                             int minTaskSize,
                             short maxTasksPerCore)

      Constructs a policy with supplied configuration options.
      Parameters:
        `fjPoolSupplier` - supplier for fork/join pool for execution, or null to use the common pool; if non-null this supplier will be used a maximum of once for lazy acquisition
        `minTaskSize` - smallest acceptable size of sub-task to split tasks into, or non-positive value for default (`DFLT_MIN_TASK_SIZE`)
        `maxTasksPerCore` - maximum number of tasks (on average) to be executed on each core as a result of decomposition, or zero for no limit, or negative value for default limit (`DFLT_MAX_TASKS_PER_CORE`)

  - ### Method Detail

    - #### getForkJoinPool

          public java.util.concurrent.ForkJoinPool getForkJoinPool()

      Returns the ForkJoinPool used by this policy.
      Returns:
        forkjoinpool

    - #### getMinTaskSize

          public int getMinTaskSize()

      Returns the smallest task size used by this policy.
      Returns:
        smallest acceptable size of sub-task to split tasks into

    - #### getMaxTasksPerCore

          public short getMaxTasksPerCore()

      Returns the maximum number of tasks (on average) to be executed on each core as a result of decomposition, or zero for no limit.
      Returns:
        maximum tasks per core, or zero

    - #### willAttemptSplit

          public boolean willAttemptSplit(Splittable<?> content)

      Indicates whether an attempt should be made to split a splittable in order to process it. If it's too small for instance, false will be returned.
      Parameters:
        `content` - splittable
      Returns:
        true iff processing will try to split content

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`