Package org.omegazero.common.event

Class TaskQueueExecutor

java.lang.Object
org.omegazero.common.event.AbstractTaskQueueExecutor
org.omegazero.common.event.TaskQueueExecutor
public class TaskQueueExecutor extends AbstractTaskQueueExecutor
Used for running Tasks concurrently, backed by a Queue, which need not be thread-safe. Up to a predefined number of threads can be used for executing tasks. These parameters may be configured in the constructor or using the TaskQueueExecutor.Builder.

Tasks are queued using the queue(Task) methods. Upon queuing a task, any applicable idle worker thread may pick up the task and execute it. Generally, if no TaskQueueExecutor.Handle is used, no guarantee is made about the order in which tasks with the same priority will be executed, as this is also dependent on the backing queue. However, if the backing queue guarantees insertion order for equal priority tasks, and a single worker thread is used, these tasks will be processed in the order in which they were queued.

This class is thread-safe.

Since:
2.6

  • Constructor Details

    • TaskQueueExecutor

      public TaskQueueExecutor(Queue<Task> queue, int maxWorkerThreadCount, boolean daemon, String threadName)
      Creates a new TaskQueueExecutor.
      Parameters:
      queue - The backing queue
      maxWorkerThreadCount - The maximum number of worker threads allowed
      daemon - Whether worker threads should be daemon threads
      threadName - The thread name prefix of the worker threads
      See Also:

  • Method Details

    • queue

      public boolean queue(Task task)
      Queues a task to be executed by any available worker thread.

      Equivalent to a call to: 

       queue(task, null)
      Specified by:
      queue in class AbstractTaskQueueExecutor
      Parameters:
      task - The task to queue
      Returns:
      true if the task was successfully queued
      See Also:

    • queue

      public boolean queue(Task task, TaskQueueExecutor.Handle handle)
      Queues a task to be executed by an available worker thread. If the backing queue supports prioritization, tasks with the lowest priority value will be executed first.

      This call may fail and return false if the task could not be added because the queue has reached its maximum size.

      If no worker thread is available or there is a backlog of tasks, and the number of worker threads is below the maximum, a new worker thread will be created.

      An optional TaskQueueExecutor.Handle may be given to control task execution. It is guaranteed that no more than one task with the same Handle will be executed concurrently (however, note that it is still undefined by which thread each task is executed). Additionally, if the backing queue guarantees insertion order for tasks with the same priority, it is also guaranteed that all tasks with the same priority and Handle will be executed in the order they were added.

      Parameters:
      task - The task to queue
      handle - An optional Handle to control task execution
      Returns:
      true if the task was successfully queued
      Since:
      2.9
      See Also:

    • unqueue

      public boolean unqueue(Task task)
      Description copied from class: AbstractTaskQueueExecutor
      Removes the given task from the queue.
      Specified by:
      unqueue in class AbstractTaskQueueExecutor
      Parameters:
      task - The task to remove
      Returns:
      true if the task was queued previously and removed successfully
      See Also:

    • newHandle

      public TaskQueueExecutor.Handle newHandle()
      Creates a new TaskQueueExecutor.Handle for use in queue(Task, Handle).

      If multiple tasks are queued with the same Handle instance, it is guaranteed that no more than one task will be executed concurrently (however, note that it is still undefined by which thread each task is executed). Additionally, if the backing queue guarantees insertion order for tasks with the same priority, it is also guaranteed that all tasks with the same priority will be executed in the order they were added.

      Handles need not be explicitly closed and can simply be discarded (left unreferenced) if no longer used.

      Returns:
      The new Handle
      Since:
      2.9
      See Also:
      • randomHandleThreads

    • isQueueEmpty

      public boolean isQueueEmpty()
      Returns true if the queue is empty.
      Returns:
      true if the queue is empty

    • getQueuedTaskCount

      public int getQueuedTaskCount()
      Returns the number of queued tasks.
      Returns:
      Number of queued tasks

    • exit

      public boolean exit(boolean blocking)
      Shuts this TaskQueueExecutor down by interrupting all idle worker threads, causing them to exit. Worker threads that are currently running a task are not interrupted, but will exit after finishing the task.

      If blocking is true, the calling thread will be blocked until all worker threads have exited. If the calling thread is interrupted while waiting, this method returns false.

      Specified by:
      exit in class AbstractTaskQueueExecutor
      Parameters:
      blocking - true to wait for all worker threads to exit
      Returns:
      true if the calling thread was interrupted while waiting for the worker threads to exit

    • getMaxWorkerThreadCount

      public int getMaxWorkerThreadCount()
      Returns the configured maximum number of worker threads.
      Returns:
      The maximum number of worker threads

    • getWorkerThreadCount

      public int getWorkerThreadCount()
      Returns the current number of worker threads.
      Returns:
      The number of active worker threads
      See Also:

    • setErrorHandler

      public void setErrorHandler(Consumer<Throwable> errorHandler)
      Description copied from class: AbstractTaskQueueExecutor
      Sets the error handler that will be called when an error occurs while executing a task in any of the worker threads.

      If this handler is not set, the error will be printed to stderr.

      Specified by:
      setErrorHandler in class AbstractTaskQueueExecutor
      Parameters:
      errorHandler - The error handler, or null to remove an existing error handler

    • from

      public static TaskQueueExecutor.Builder from(Queue<Task> queue)
      Creates a new TaskQueueExecutor.Builder with the given backing queue for the TaskQueueExecutor.
      Parameters:
      queue - The backing queue
      Returns:
      The builder
      See Also:

    • fromPriority

      public static TaskQueueExecutor.Builder fromPriority()
      Creates a new TaskQueueExecutor.Builder for a TaskQueueExecutor backed by a PriorityQueue. This queue supports prioritization, but makes no guarantee about the order at which tasks with the same priority are executed.
      Returns:
      The builder
      See Also:

    • fromSequential

      public static TaskQueueExecutor.Builder fromSequential()
      Creates a new TaskQueueExecutor.Builder for a TaskQueueExecutor backed by a ArrayDeque. This queue does not support prioritization, but has insertion order, meaning tasks will generally be executed in the order they were queued.
      Returns:
      The builder
      See Also: