Module iu.util
Package edu.iu

Class IuParallelWorkloadController

java.lang.Object
edu.iu.IuParallelWorkloadController
All Implemented Interfaces:
UnsafeFunction<UnsafeConsumer<IuTaskController>,IuTaskController>, AutoCloseable
public class IuParallelWorkloadController extends Object implements UnsafeFunction<UnsafeConsumer<IuTaskController>,IuTaskController>, AutoCloseable
Controls parallel processing over a bounded workload.

UML Class Diagram

Each controller is closeable, timed, and operates in a dedicated task executor. It's expected for all tasks related to the workload to complete within the established a given timeout interval, after which active tasks will be interrupted and related resources will be torn down.

All tasks should handle exceptions. By default, any Throwable not handled by task execution notifies an immediate stop to all work and for the controller to close. The exception that caused the failure will be thrown as the cause of ExecutionException from await().

See Also:

  • Constructor Details

    • IuParallelWorkloadController

      public IuParallelWorkloadController(String name, int size, Duration timeout)
      Creates a new workload controller.
      Parameters:
      name - descriptive name of the workload, for logging and error reporting
      size - maximum number of parallel tasks to execute at the same time
      timeout - total time to live for all workload-related tasks

  • Method Details

    • setLog

      public void setLog(Logger log)
      Provides an alternative logger to use for tracing workload events.

      Uses a class-level delegating default logger until this method provides an alternative.

      Parameters:
      log - alternative logger

    • setGracefulShutdown

      public void setGracefulShutdown(Duration gracefulShutdown)
      Sets the time to wait for worker threads to complete after closing the controller, before shutting down the thread pool.
      Parameters:
      gracefulShutdown - Duration

    • setGracefulTermination

      public void setGracefulTermination(Duration gracefulTermination)
      Sets the time to wait for the thread pool to shut down, after closing the controller and waiting for worker threads to complete gracefully, before interrupting all threads managed by this controller.
      Parameters:
      gracefulTermination - Duration

    • setGracefulDestroy

      public void setGracefulDestroy(Duration gracefulDestroy)
      Sets the time to wait for the thread pool to shut down, after closing the controller, waiting for worker threads to complete gracefully, and interrupting all threads managed by this controller.

      After the graceful destroy period has passed, all threads managed by this controller and still running will be abandoned and a Level.WARNING will be logged. This condition indicates a possible resource leak.

      Parameters:
      gracefulDestroy - Duration

    • setFailedExecutionHandler

      public void setFailedExecutionHandler(Consumer<Throwable> failedExecutionHandler)
      Overrides the default execution handler.
      Parameters:
      failedExecutionHandler - consumer to accept any task execution failures, may call defaultHandleFailedExecution(Throwable) to inject default behavior.

    • defaultHandleFailedExecution

      public void defaultHandleFailedExecution(Throwable cause)
      Invoked by default if any task throws an exception during execution.
      Parameters:
      cause - task execution error

    • getSpawnedThreadCount

      public long getSpawnedThreadCount()
      Gets a count of threads spawned by this controller.
      Returns:
      thread count

    • getPendingTaskCount

      public long getPendingTaskCount()
      Gets a count of tasks submitted to this controller that have not yet completed.
      Returns:
      pending task count

    • getCompletedTaskCount

      public long getCompletedTaskCount()
      Gets a count of tasks completed by this controller.
      Returns:
      pending task count

    • getElapsed

      public Duration getElapsed()
      Gets the time elapsed since the controller was created.
      Returns:
      time elapsed

    • getRemaining

      public Duration getRemaining()
      Gets the time remaining until the controller expires.
      Returns:
      time remaining; may be zero or negative if already isExpired()

    • getExpires

      public Instant getExpires()
      Gets the instant the timeout interval expires.
      Returns:
      instant the timeout interval expires.

    • isExpired

      public boolean isExpired()
      Determines whether or not the controller has expired.

      Once expired, all threads waiting on the controller will be notified and the controller will be closed. No more tasks may be submitted once the controller has expired; all remaining tasks will be interrupted and/or throw IllegalStateException with a message indicating a timeout.

      Returns:
      true if the controller is expired; else false

    • await

      public void await() throws ExecutionException, InterruptedException, TimeoutException
      Wait until either all pending tasks have completed, or until the controller expires.
      Throws:
      ExecutionException - If a task used defaultHandleFailedExecution(Throwable) to report an execution error. The first error reported will be the cause, and additional errors reported prior to shutdown will be suppressed.
      InterruptedException - if interrupted waiting for pending tasks to complete. If task execution was interrupted, that condition will be the cause of ExecutionException; InterruptedException thrown directly indicates this thread, not a task thread, was interrupted.
      TimeoutException - if the controller expires before all pending tasks complete normally. If task times out, that condition will be the cause of ExecutionException; TimeoutException thrown directly indicates this thread, not a task thread, timed out.

    • apply

      public IuTaskController apply(UnsafeConsumer<IuTaskController> task) throws InterruptedException, TimeoutException
      Submits an asynchronous task for processing.

      This method will block until a thread is available for excuting the task, or until the controller has expired. Applications should, however, use IuRateLimitter or similar to restrict prevent the need for blocking, and should enforce SLOs on workload runtimes to ensure algorithm scalability can be calculated to approach but not reach the upper limit.

      To ensure resources are released gracefully and efficiently when the workload timeout expires, both the thread the created the task and the thread executing the task may use IuTaskController to synchronize task execution.

      Specified by:
      apply in interface UnsafeFunction<UnsafeConsumer<IuTaskController>,IuTaskController>
      Parameters:
      task - task, will be provided a IuTaskController for synchronizing task execution.
      Returns:
      IuTaskController
      Throws:
      TimeoutException - if the workload expiration timeout is reached before a worker thread is available
      InterruptedException - if the current thread is interrupted before a worker thread picks up the task

    • isClosed

      public boolean isClosed()
      Determines whether or not this controller is closed.
      Returns:
      true if closed; false if still available for accepting new tasks

    • close

      public void close() throws InterruptedException, TimeoutException
      Shuts down all activity and releases resources related to the workload.

      This method is invoked from a timer when the controller expires. No more tasks can be submitted once the controller is closed. Repeat calls to this method have no effect.

      Specified by:
      close in interface AutoCloseable
      Throws:
      InterruptedException
      TimeoutException

    • toString

      public String toString()
      Overrides:
      toString in class Object