de.caff.util.concurrent

## Class Exec

- java.lang.Object
- - de.caff.util.concurrent.Exec

-     public final class Exec
      extends java.lang.Object

  Class with static helper methods for thread pool execution.
  Since:
    August 16, 2022
  Author:
    Rammi

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `(package private) static class` | `Exec.DefaultThreadFactory` Default thread factory.
    `static class` | `Exec.FinishingThreadPoolExecutor` This is a wrapper for a thread-pool executor which accepts runnable tasks and can wait until all of them are finished.
    `(package private) static class` | `Exec.PrivilegedThreadFactory` Privileged thread factor.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static double` | `DEFAULT_CPU_UTILIZATION_FACTOR` CPU utilization factor, leave 5% for computer and GUI.
    `static int` | `DEFAULT_MAX_THREADS` The default for the maximum allowed number of threads.
    `static double` | `DEFAULT_WAIT_TO_COMPUTE_RATIO` Default wait-to-compute ratio.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static int` | `calcNumThreads(double cpuUtilizationFactor, double waitToComputeRatio, int maxThreads)` Calculate a useful number of threads for a task.
    `static java.util.concurrent.ThreadPoolExecutor` | `createDefaultExecutor()` Create a default thread pool executor with a default number of threads, a keep-alive time of 0, a linked blocking queue, and a rejection handler which discards all unexecutable threads.
    `static java.util.concurrent.ThreadPoolExecutor` | `createDefaultExecutor(double cpuUtilizationFactor, double waitToComputeRatio, int maxThreads)` Create a default thread pool executor with a useful number of threads, a keep alive time of 0, a linked blocking queue, and a rejection handler which discards all unexecutable threads.
    `static java.util.concurrent.ThreadPoolExecutor` | `createDefaultExecutor(int maxThreads)` Create a default thread pool executor with a restricted but default number of threads, a keep-alive time of 0, a linked blocking queue, and a rejection handler which discards all unexecutable threads.
    `static java.util.concurrent.ThreadPoolExecutor` | `createDefaultExecutor(java.lang.String basicThreadName, double cpuUtilizationFactor, double waitToComputeRatio, int maxThreads)` Create a default thread pool executor with a useful number of threads, a keep-alive time of 0, a linked blocking queue, and a rejection handler which discards all unexecutable threads.
    `static java.util.concurrent.ThreadFactory` | `defaultNamedThreadFactory(java.lang.String baseName)` Get a default thread factory where threads get an individual name made up from the given basic name.
    `static java.util.concurrent.ThreadFactory` | `privilegedNamedThreadFactory(java.lang.String baseName)` Get a privileged thread factory where threads get an individual name made up from the given basic name.
    `static java.util.concurrent.ThreadFactory` | `privilegedNamedThreadFactory(java.lang.String baseName, java.lang.ClassLoader classLoader)` Get a privileged thread factory where threads get an individual name made up from the given basic name.

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

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

- - ### Field Detail

    - #### DEFAULT_MAX_THREADS

          public static final int DEFAULT_MAX_THREADS

      The default for the maximum allowed number of threads. This can be changed by setting Java property `"caff.exec.maxthreads"`, preferably at startup via command line, but at least before this class is loaded, e.g. statically in the startup class or early in the startup method.

    - #### DEFAULT_WAIT_TO_COMPUTE_RATIO

          public static final double DEFAULT_WAIT_TO_COMPUTE_RATIO

      Default wait-to-compute ratio.
      See Also:
        Constant Field Values

    - #### DEFAULT_CPU_UTILIZATION_FACTOR

          public static final double DEFAULT_CPU_UTILIZATION_FACTOR

      CPU utilization factor, leave 5% for computer and GUI.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### calcNumThreads

          public static int calcNumThreads(double cpuUtilizationFactor,
                                           double waitToComputeRatio,
                                           int maxThreads)

      Calculate a useful number of threads for a task.

      This uses the number of CPUs as a base together with the parameters, to calculate a useful number of threads for a thread pool.

      Parameters:
        `cpuUtilizationFactor` - how much of the CPU should be used to run the threads, a number between `0.0` (none) and `1.0` (everything). Leave a bit of room for other tasks your computer has to perform.
        `waitToComputeRatio` - value which defines the ratio of the time your tasks are waiting for input against the time they spend actual computing. A number between `0.0` (no waiting, only computing) and `1.0` (no computing, only waiting).
        `maxThreads` - upper limit to the number of threads, at least 1
      Returns:
        useful value for the number of threads in a thread pool

    - #### createDefaultExecutor

          @NotNull
          public static java.util.concurrent.ThreadPoolExecutor createDefaultExecutor(double cpuUtilizationFactor,
                                                                                               double waitToComputeRatio,
                                                                                               int maxThreads)

      Create a default thread pool executor with a useful number of threads, a keep alive time of 0, a linked blocking queue, and a rejection handler which discards all unexecutable threads.
      Parameters:
        `cpuUtilizationFactor` - how much of the CPU should be used to run the threads, a number between `0.0` (none) and `1.0` (everything). Leave a bit of room for other tasks your computer has to perform.
        `waitToComputeRatio` - value which defines the ratio of the time your tasks are waiting for input against the time they spend actual computing. A number between `0.0` (no waiting, only computing) and `1.0` (no computing, only waiting).
        `maxThreads` - upper limit to the number of threads, at least 1
      Returns:
        prepared thread pool executor

    - #### createDefaultExecutor

          @NotNull
          public static java.util.concurrent.ThreadPoolExecutor createDefaultExecutor(int maxThreads)

      Create a default thread pool executor with a restricted but default number of threads, a keep-alive time of 0, a linked blocking queue, and a rejection handler which discards all unexecutable threads. This calls `createDefaultExecutor(double,double,int)` with `DEFAULT_CPU_UTILIZATION_FACTOR` and `DEFAULT_WAIT_TO_COMPUTE_RATIO`.
      Parameters:
        `maxThreads` - upper limit to the created number of threads
      Returns:
        prepared thread pool executor

    - #### createDefaultExecutor

          @NotNull
          public static java.util.concurrent.ThreadPoolExecutor createDefaultExecutor()

      Create a default thread pool executor with a default number of threads, a keep-alive time of 0, a linked blocking queue, and a rejection handler which discards all unexecutable threads. This calls `createDefaultExecutor(double,double,int)` with `DEFAULT_CPU_UTILIZATION_FACTOR`, `DEFAULT_WAIT_TO_COMPUTE_RATIO`, and `DEFAULT_MAX_THREADS`.
      Returns:
        prepared thread pool executor

    - #### createDefaultExecutor

          @NotNull
          public static java.util.concurrent.ThreadPoolExecutor createDefaultExecutor(@NotNull
                                                                                               java.lang.String basicThreadName,
                                                                                               double cpuUtilizationFactor,
                                                                                               double waitToComputeRatio,
                                                                                               int maxThreads)

      Create a default thread pool executor with a useful number of threads, a keep-alive time of 0, a linked blocking queue, and a rejection handler which discards all unexecutable threads.
      Parameters:
        `basicThreadName` - basic name used for threads, see `defaultNamedThreadFactory(String)`
        `cpuUtilizationFactor` - how much of the CPU should be used to run the threads, a number between `0.0` (none) and `1.0` (everything). Leave a bit of room for other tasks your computer has to perform.
        `waitToComputeRatio` - value which defines the ratio of the time your task are waiting for input against the time they spend actual computing. A number between `0.0` (no waiting, only computing) and `1.0` (no computing, only waiting).
        `maxThreads` - upper limit to the number of threads, at least 1
      Returns:
        prepared thread pool executor

    - #### defaultNamedThreadFactory

          @NotNull
          public static java.util.concurrent.ThreadFactory defaultNamedThreadFactory(@NotNull
                                                                                              java.lang.String baseName)

      Get a default thread factory where threads get an individual name made up from the given basic name. This is basically the same as `Executors.defaultThreadFactory()`, only you can set a dedicated name.

      Threads will get individual names made up from the given `baseName`, a pool number for the factory and a number for each thread in the individual pool in the format `<baseName>-<poolnr>-<threadnr>`.

      Parameters:
        `baseName` - basic name
      Returns:
        thread factory which creates threads with names based on the given `baseName`

    - #### privilegedNamedThreadFactory

          @NotNull
          public static java.util.concurrent.ThreadFactory privilegedNamedThreadFactory(@NotNull
                                                                                                 java.lang.String baseName)

      Get a privileged thread factory where threads get an individual name made up from the given basic name. This is basically the same as `Executors.privilegedThreadFactory()`, only you can set a dedicated name.

      Threads will get individual names made up from the given `baseName`, a pool number for the factory and a number for each thread in the individual pool in the format `<baseName>-<poolnr>-<threadnr>`.

      Parameters:
        `baseName` - basic name
      Returns:
        thread factory which creates threads with names based on the given `baseName`

    - #### privilegedNamedThreadFactory

          @NotNull
          public static java.util.concurrent.ThreadFactory privilegedNamedThreadFactory(@NotNull
                                                                                                 java.lang.String baseName,
                                                                                                 @NotNull
                                                                                                 java.lang.ClassLoader classLoader)

      Get a privileged thread factory where threads get an individual name made up from the given basic name. This is basically the same as `Executors.privilegedThreadFactory()`, only you can set a dedicated name and a dedicated class loader.

      Threads will get individual names made up from the given `baseName`, a pool number for the factory and a number for each thread in the individual pool in the format `<baseName>-<poolnr>-<threadnr>`.

      Parameters:
        `baseName` - basic name
        `classLoader` - class loader set as context class loader in the created threads
      Returns:
        thread factory which creates threads with names based on the given `baseName`