org.jtrim2.executor

Interface TaskExecutorService

All Superinterfaces:

Executor, TaskExecutor

All Known Subinterfaces:

ContextAwareTaskExecutorService, MonitorableTaskExecutorService

All Known Implementing Classes:

AbstractTaskExecutorService, AbstractTerminateNotifierTaskExecutorService, DelegatedTaskExecutorService, SingleThreadedExecutor, SyncTaskExecutor, ThreadPoolTaskExecutor

public interface TaskExecutorService
extends TaskExecutor

Defines a TaskExecutor with additional methods to better manage submitted tasks. This interface is a replacement for the ExecutorService interface in java.

In general, TaskExecutorService implementations must be shut down once no longer needed, so that implementations may terminate their internal threads. When a TaskExecutorService has been shut down it will no longer accept submitting tasks and as a consequence, it will complete them exceptionally with an OperationCanceledException.

TaskExecutorService defines two ways for shutting down itself: One is the shutdown() method and the other is the shutdownAndCancel() method. The difference between them is that while shutdown() only prevents submitting subsequent tasks, shutdownAndCancel() will actively cancel already submitted tasks.

Thread safety

Implementations of this interface are required to be safely accessible from multiple threads concurrently.

Synchronization transparency

The methods of this interface are not required to be synchronization transparent because they may execute tasks, handlers added to CompletionStage, etc.

See Also:

AbstractTaskExecutorService

Method Summary

Modifier and Type	Method and Description
ListenerRef	addTerminateListener(Runnable listener) Adds a listener which is to be notified after this TaskExecutorService terminates.
default void	awaitTermination(CancellationToken cancelToken) Waits until this TaskExecutorService will not execute any more tasks.
boolean	isShutdown() Checks whether this TaskExecutorService accepts newly submitted tasks or not.
boolean	isTerminated() Checks whether this TaskExecutorService may execute tasks submitted to it tasks or not.
void	shutdown() Shuts down this TaskExecutorService, so that it will not execute tasks submitted to it after this method call returns.
void	shutdownAndCancel() Shuts down this TaskExecutorService and cancels already submitted tasks, so that it will not execute tasks submitted to it after this method call returns.
boolean	tryAwaitTermination(CancellationToken cancelToken, long timeout, TimeUnit unit) Waits until this TaskExecutorService will not execute any more tasks or the given timeout elapses.

Methods inherited from interface org.jtrim2.executor.TaskExecutor

execute, execute, executeFunction, executeStaged

Method Detail

shutdown

void shutdown()

Shuts down this TaskExecutorService, so that it will not execute tasks submitted to it after this method call returns.

Already submitted tasks will execute normally but tasks submitted after this method returns will immediately be completed exceptionally with an OperationCanceledException.

Note that it is possible, that some tasks are submitted concurrently with this call. Those tasks can be either canceled or executed normally, depending on the circumstances.

If currently executing tasks should be canceled as well, use the shutdownAndCancel() method to shutdown this TaskExecutorService.

This method call is idempotent. That is, calling it multiple times must have no further effect.

See Also:

shutdownAndCancel()

shutdownAndCancel

void shutdownAndCancel()

Shuts down this TaskExecutorService and cancels already submitted tasks, so that it will not execute tasks submitted to it after this method call returns.

Already submitted tasks will be canceled and the tasks may detect this cancellation request by inspecting their CancellationToken but tasks submitted after this method returns will immediately be completed exceptionally with an OperationCanceledException.

Note that it is possible, that some tasks are submitted concurrently with this call. Those tasks may be treated as if they were submitted before this method call or as if they were submitted after.

If currently executing tasks should be left executing, use the shutdown() method instead to shutdown this TaskExecutorService.

This method call is idempotent. That is, calling it multiple times must have no further effect. Note however, that calling this method after the shutdown() method is meaningful because this method will cancel ongoing tasks.

See Also:

shutdown()

isShutdown

boolean isShutdown()

Checks whether this TaskExecutorService accepts newly submitted tasks or not. This method returns true, if and only, if either the #shutdown() shutdown() or the shutdownAndCancel() method has been called. Therefore if, this method returns true, subsequent submit and execute method invocations will not execute submitted tasks and will only complete them exceptionally with an OperationCanceledException.

Returns:

true if this TaskExecutorService accepts newly submitted tasks, false if it has been shut down

See Also:

isTerminated()

isTerminated

boolean isTerminated()

Checks whether this TaskExecutorService may execute tasks submitted to it tasks or not. If this method returns true, no more tasks will be executed by this TaskExecutorService and no tasks are currently executing. That is, if this method returns true subsequent submit or execute methods will not execute the submitted tasks but complete them exceptionally with an OperationCanceledException.

Also if this method returns true, subsequent awaitTermination method calls will return immediately without throwing an exception (will not even check for cancellation).

Returns:

true if this TaskExecutorService accepts newly submitted tasks, false if it has been shut down

See Also:

isTerminated()

addTerminateListener

ListenerRef addTerminateListener(Runnable listener)

Adds a listener which is to be notified after this TaskExecutorService terminates. If the listener has been already terminated, the listener is notified immediately in this addTerminateListener method call. Also, the listener may only be called at most once (per registration).

Whenever these registered listeners are notified, the isTerminated() method already returns true and calling the awaitTermination or the tryAwaitTermination method will have no effect (as they return immediately).

On what thread, the registered listeners might be called is implementation dependent: They can be called from the thread, the last task executed, the shutdown or the shutdownAndCancel methods or in any other thread, as this TaskExecutorService desires. Therefore, the listeners must be written conservatively.

The listener can be removed if no longer required to be notified by calling the unregister method of the returned reference.

Parameters:

listener - the Runnable whose run method is to be called after this TaskExecutorService terminates. This argument cannot be null.

Returns:

the reference which can be used to removed the currently added listener, so that it will not be notified anymore. This method never returns null.

Throws:

NullPointerException - thrown if the specified listener is null

See Also:

awaitTermination(CancellationToken), tryAwaitTermination(CancellationToken, long, TimeUnit)

awaitTermination

default void awaitTermination(CancellationToken cancelToken)

Waits until this TaskExecutorService will not execute any more tasks. After this method returns (without throwing an exception), subsequent isTerminated() method calls will return true.

After this method returns without throwing an exception, it is true that: No more tasks will be executed by this TaskExecutorService and no tasks are currently executing. That is, subsequent submit or execute methods will not execute the submitted tasks but complete them exceptionally with an OperationCanceledException.

The default implementation simply calls tryAwaitTermination until it returns true.

Parameters:

cancelToken - the CancellationToken which can be used to stop waiting for the termination of this TaskExecutorService. That is, if this method detects, that cancellation was requested, it will throw an OperationCanceledException. This argument cannot be null.

Throws:

NullPointerException - thrown if the specified CancellationToken is null

OperationCanceledException - thrown if cancellation request was detected by this method before this TaskExecutorService terminated. This exception is not thrown if this TaskExecutorService was terminated prior to this method call.

See Also:

addTerminateListener(Runnable)

tryAwaitTermination

boolean tryAwaitTermination(CancellationToken cancelToken,
                            long timeout,
                            TimeUnit unit)

Waits until this TaskExecutorService will not execute any more tasks or the given timeout elapses. After this method returns true, subsequent isTerminated() method calls will also return true.

After this method returns true (and does not throw an exception), it is true that: No more tasks will be executed by this TaskExecutorService and no tasks are currently executing. That is, subsequent submit or execute methods will not execute the submitted tasks but complete them exceptionally with an OperationCanceledException.

Parameters:

cancelToken - the CancellationToken which can be used to stop waiting for the termination of this TaskExecutorService. That is, if this method detects, that cancellation was requested, it will throw an OperationCanceledException. This argument cannot be null.

timeout - the maximum time to wait for this TaskExecutorService to terminate in the given time unit. This argument must be greater than or equal to zero.

unit - the time unit of the timeout argument. This argument cannot be null.

Returns:

true if this TaskExecutorService has terminated before the timeout elapsed, false if the timeout elapsed first. In case this TaskExecutorService terminated prior to this call this method always returns true.

Throws:

IllegalArgumentException - thrown if the specified timeout value is negative

NullPointerException - thrown if any of the arguments is null

OperationCanceledException - thrown if cancellation request was detected by this method before this TaskExecutorService terminated This exception is not thrown if this TaskExecutorService was terminated prior to this method call.

See Also:

addTerminateListener(Runnable)