ThreadWorkPool

package saker.build.thirdparty.saker.util.thread

public interface ThreadUtils.ThreadWorkPool extends AutoCloseable

saker.build.thirdparty.saker.util.thread.ThreadUtils.ThreadWorkPool

java.lang.AutoCloseable

Interface for a thread pool that is capable of executing tasks offered to it.

An instance of a thread pool schedules the offered tasks to it in an implementation dependent manner.

The thread pools can be closed, in which case the pending tasks will be waited for, and the pool will no longer accept task offerings to it.

The thread pools can be reset, in which case it will wait for all pending tasks to complete, but unlike close(), it will be reuseable. Spawned threads will probably stay alive when resetting a thread pool.

Thread pools can be signaled to exit, in which case it will not wait for the pending tasks, but will prevent adding any more tasks if the pending ones are finished. Thread pools can be reset after signaling exit.

Note, that some thread pool implementations are allowed to be offered tasks to them even after they're closed. However, if they do so, they must handle their graceful teardown without explicit second closing.

Some thread pool implementations may allow resetting them after they've been closed. In this case, the thread pool must be closed again if the resetting is successful. In general, closing can be called multiple times, and every reset call should be matched to a corresponding close call.

This interface is not designed to be implemented by users. Clients should instantiate thread pools using the static factory methods in the ThreadUtils class.

Methods

public void	close() Closes the thread pool in a non-interruptible, cancelling way.
public void	closeInterruptible() Closes the thread pool in an interruptible way.
public void	exit() Sends an exit signal to the thread pool.
public void	offer(ThrowingRunnable task) Offers a task to be executed in this thread pool.
public void	reset() Resets the thread pool in a non-interruptible way so it accepts task offered to it.
public void	resetInterruptible() Resets the thread pool in an interruptible way so it accepts tasks offered to it.

public abstract void close() throws ParallelExecutionException, IllegalThreadStateException

Closes the thread pool in a non-interruptible, cancelling way.

This method will wait for all pending tasks to finish, and then closes the thread pool completely for further use.

During the closing, new tasks can still be offered to the thread pool, only if there are still any tasks running. If there are no tasks running, and closing is requested, no more tasks can be offered to the thread pool.

A closed thread pool cannot be reset.

If the current thread is interrupted, it will be treated as the tasks in the thread pool are cancelled. The currently executing task threads will be interrupted, and the waiting for the tasks will continue. The interrupted flag of the current thread is stored, and the current thread is reinterrupted if necessary. If any task was cancelled due to interruption, a ParallelExecutionException will signal that accordingly.

ParallelExecutionExceptionIf any of the tasks threw an exception. If this exception is thrown, the thread pool is considered to be successfully closed.

IllegalThreadStateExceptionIf the thread pool is being closed on a thread that is part of the thread pool. I.e. the pool is being closed from a task thread.

public abstract void closeInterruptible() throws ParallelExecutionException, InterruptedException, IllegalThreadStateException

Closes the thread pool in an interruptible way.

This method will wait for all pending tasks to finish, and then closes the thread pool completely for further use.

A closed thread pool cannot be reset.

If the current thread is interrupted, the InterruptedException is propagated to the caller. This means that the thread pool wasn't closed, but that it is signaled to exit. Pending tasks are not interrupted.

ParallelExecutionExceptionIf any of the tasks threw an exception. If this exception is thrown, the thread pool is considered to be successfully closed.

InterruptedExceptionIf the current thread was interrupted while waiting for the pending tasks.

IllegalThreadStateExceptionIf the thread pool is being closed on a thread that is part of the thread pool. I.e. the pool is being closed from a task thread.

public abstract void exit()

Sends an exit signal to the thread pool.

The method returns immediately, only sends a signal that the thread pool should exit if no more tasks are being scheduled.

After exiting, the thread pool can be considered as closed, however reset() still can be called to return the thread pool to a working state.

Similar to close(), new tasks can still be offered to the thread pool, only if there are still any tasks running. If there are no tasks running, no more tasks can be offered to the thread pool, unless reset() is called.

public abstract void offer(ThrowingRunnable task) throws NullPointerException, IllegalStateException

Offers a task to be executed in this thread pool.

The offered task is scheduled to be executed in an implementation dependent manner. It may be executed right away, it may be delegated to an other thread, may be delayed to an other time, or in any other ways that the implementation sees fit.

If users want to run a task that returns some result, they need to employ their own synchronization mechanics.

taskThe task to be executed by this work pool.

NullPointerExceptionIf the task is null.

IllegalStateExceptionIf the thread pool has been closed, or exited without resetting.

public abstract void reset() throws ParallelExecutionException, IllegalStateException, IllegalThreadStateException

Resets the thread pool in a non-interruptible way so it accepts task offered to it.

Resetting will wait for pending tasks to finish (if any), and throw the exception from the tasks to the caller. If a ParallelExecutionException is thrown, the thread pool is considered to be successfully reset, but the tasks threw an exception during their execution.

This method handles if the current thread is interrupted while waiting for the tasks to finish. Unlike close(), interrupting the current thread will not interrupt the task executor threads, so they won't be cancelled by that. The interrupted flag of the current thread is stored, and the current thread is reinterrupted if necessary.

Resetting a non-closed thread pool or resetting a thread pool multiple times has no effect.

Warning: Call this method only, if you can ensure that the offered tasks will properly finish, and will not deadlock. As this method basically ignores the interruption of the current thread, this can result in deadlocking, or leaving unclosed resources in the JVM.

ParallelExecutionExceptionIf any of the tasks threw an exception. If this exception is thrown, the thread pool is considered to be successfully reset.

IllegalStateExceptionIf the thread pool have been explicitly closed and cannot be reset.

IllegalThreadStateExceptionIf the thread pool is being closed on a thread that is part of the thread pool. I.e. the pool is being closed from a task thread.

public abstract void resetInterruptible() throws ParallelExecutionException, InterruptedException, IllegalStateException, IllegalThreadStateException

Resets the thread pool in an interruptible way so it accepts tasks offered to it.

If the current method is interrupted during the waiting for the task, the InterruptedException is propagated to the caller. This means that there are still pending tasks in the thread pool. If this happens, tasks can be still offered to the thread pool, as it is still in an alive state.

Resetting a non-closed thread pool or resetting a thread pool multiple times has no effect.

ParallelExecutionExceptionIf any of the tasks threw an exception. If this exception is thrown, the thread pool is considered to be successfully reset.

InterruptedExceptionIf the current thread was interrupted while waiting for the pending tasks.

IllegalStateExceptionIf the thread pool have been explicitly closed.

IllegalThreadStateExceptionIf the thread pool is being closed on a thread that is part of the thread pool. I.e. the pool is being closed from a task thread.