Package dev.aahmedlab.concurrent

Class BoundedExecutor

java.lang.Object
dev.aahmedlab.concurrent.BoundedExecutor
public final class BoundedExecutor extends Object
A bounded executor implementation with a bounded queue and configurable rejection policies.

This bounded executor provides bounded capacity to prevent resource exhaustion and offers multiple strategies for handling task submission when the executor is at capacity. It supports graceful shutdown, task accounting, and monitoring capabilities.

Since:
1.0.0
Author:
Abdullah Ahmed

  • Constructor Details

    • BoundedExecutor

      public BoundedExecutor(int poolSize, int capacity, RejectionPolicy rejectionPolicy)
      Creates a bounded executor with the specified parameters.
      Parameters:
      poolSize - the number of worker threads
      capacity - the maximum number of tasks that can be queued
      rejectionPolicy - the policy to use when the queue is full
      Throws:
      IllegalArgumentException - if poolSize or capacity is less than or equal to 0
      Since:
      1.0.0

  • Method Details

    • create

      public static BoundedExecutor create(int poolSize, int capacity)
      Creates a bounded executor with a BLOCK rejection policy. This is the most common configuration for bounded executors.
      Parameters:
      poolSize - the number of worker threads
      capacity - the maximum number of tasks that can be queued
      Returns:
      a new BoundedExecutor instance
      Throws:
      IllegalArgumentException - if poolSize or capacity is less than or equal to 0
      Since:
      1.0.0

    • createFixed

      public static BoundedExecutor createFixed(int poolSize)
      Creates a fixed-size executor with a bounded queue. The queue capacity is twice the pool size, providing a good balance between throughput and memory usage.
      Parameters:
      poolSize - the number of worker threads
      Returns:
      a new BoundedExecutor instance
      Throws:
      IllegalArgumentException - if poolSize is less than or equal to 0
      Since:
      1.0.0

    • createCpuBound

      public static BoundedExecutor createCpuBound()
      Creates an executor optimized for CPU-bound tasks. Uses the number of available processors as the pool size with a small bounded queue.
      Returns:
      a new BoundedExecutor instance optimized for CPU-bound tasks
      Since:
      1.0.0

    • createIoBound

      public static BoundedExecutor createIoBound()
      Creates an executor optimized for I/O-bound tasks. Uses twice the number of available processors as the pool size with a larger bounded queue.
      Returns:
      a new BoundedExecutor instance optimized for I/O-bound tasks
      Since:
      1.0.0

    • submit

      public void submit(Runnable task) throws InterruptedException
      Submits a task for execution in the bounded executor.
      Parameters:
      task - the task to execute
      Throws:
      NullPointerException - if task is null
      RejectedExecutionException - if the executor is shut down or the queue is full (for ABORT policy)
      InterruptedException - if the thread is interrupted while waiting (for BLOCK policy)
      Since:
      1.0.0

    • shutdown

      public void shutdown()
      Initiates a graceful shutdown of the bounded executor.

      This method:

      • Sets the pool state to SHUTDOWN
      • Closes the task queue (new submissions will be rejected)
      • Allows currently executing tasks to complete
      • Processes all tasks already in the queue
      Since:
      1.0.0

    • shutdownNow

      public List<Runnable> shutdownNow()
      Initiates an immediate shutdown of the bounded executor.

      This method:

      • Sets the pool state to STOP
      • Closes the task queue (new submissions will be rejected)
      • Interrupts all worker threads
      • Returns the list of tasks that were still queued in the queue

      Note: Tasks that were already taken from the queue by workers before they observed the STOP state may be dropped and will not be included in the returned list. This is a documented behavior due to the inherent race between draining the queue and workers taking tasks.

      Returns:
      list of tasks that never began execution
      Since:
      1.0.0

    • awaitTermination

      public boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedException
      Blocks until all tasks have completed execution after a shutdown request, or the timeout occurs, or the current thread is interrupted, whichever happens first.
      Parameters:
      timeout - the maximum time to wait
      unit - the time unit of the timeout argument
      Returns:
      true if this executor terminated and false if the timeout elapsed before termination
      Throws:
      InterruptedException - if interrupted while waiting
      Since:
      1.0.0

    • isShutdown

      public boolean isShutdown()
      Returns true if this pool has been shut down.
      Returns:
      true if this pool has been shut down
      Since:
      1.0.0

    • isTerminated

      public boolean isTerminated()
      Returns true if this pool has been terminated. A pool is terminated after shutdown() or shutdownNow() and all worker threads have exited.
      Returns:
      true if this pool has been terminated
      Since:
      1.0.0

    • isRunning

      public boolean isRunning()
      Returns true if this pool is running and accepting new tasks.
      Returns:
      true if this pool is running
      Since:
      1.0.0

    • getPoolSize

      public int getPoolSize()
      Returns the number of worker threads in this pool.
      Returns:
      the number of worker threads
      Since:
      1.0.0

    • getQueueSize

      public int getQueueSize()
      Returns the current number of tasks in the queue.
      Returns:
      the number of queued tasks
      Since:
      1.0.0

    • getQueueRemainingCapacity

      public int getQueueRemainingCapacity()
      Returns the remaining capacity of the queue.
      Returns:
      the remaining capacity
      Since:
      1.0.0

    • isQueueFull

      public boolean isQueueFull()
      Returns true if the queue is full.
      Returns:
      true if the queue is full
      Since:
      1.0.0