org.jtrim2.executor

Interface TaskExecutor

All Superinterfaces:

Executor

All Known Subinterfaces:

ContextAwareTaskExecutor, ContextAwareTaskExecutorService, MonitorableTaskExecutor, MonitorableTaskExecutorService, TaskExecutorService

All Known Implementing Classes:

AbstractTaskExecutor, AbstractTaskExecutorService, AbstractTerminateNotifierTaskExecutorService, ContextAwareWrapper, DelegatedTaskExecutorService, ManualTaskExecutor, SingleThreadedExecutor, SyncTaskExecutor, ThreadPoolTaskExecutor

public interface TaskExecutor
extends Executor

Executes tasks at some time in the future. This interface defines a more robust way to execute tasks than java.util.concurrent.Executor. That is, this interface defines a simpler way for canceling tasks and allows to continue after the completion of the submitted task via a CompletionStage. It is possible to continue execution regardless how the submitted task completed (success, failure or canceled). For more control over the life of a TaskExecutor, see the extending TaskExecutorService interface.

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:

CancelableTask, TaskExecutorService, TaskExecutors.upgradeToStoppable(TaskExecutor)

Method Summary

Modifier and Type	Method and Description
default CompletionStage<Void>	execute(CancellationToken cancelToken, CancelableTask task) Executes the task at some time in the future.
default void	execute(Runnable command) Note that although the task itself is not cancelable explicitly, the executor might cancel it by not executing the submitted task.
<V> CompletionStage<V>	executeFunction(CancellationToken cancelToken, CancelableFunction<? extends V> function) Executes the function at some time in the future.
default CompletionStage<Void>	executeStaged(Runnable task) Executes an non-cancelable task at some time in the future.

Method Detail

executeFunction

<V> CompletionStage<V> executeFunction(CancellationToken cancelToken,
                                       CancelableFunction<? extends V> function)

Executes the function at some time in the future. When and on what thread, the function is to be executed is completely implementation dependent. Implementations may choose to execute tasks later on a separate thread or synchronously in the calling thread at the discretion of the implementation.

Type Parameters:

V - the type of the result of the submitted function

Parameters:

cancelToken - the CancellationToken which is to be checked if the submitted task is to be canceled. If this CancellationToken signals a cancellation request, this TaskExecutor may choose to not even attempt to execute the submitted task. This argument may not be null. When the task cannot be canceled, use the static Cancellation.UNCANCELABLE_TOKEN for this argument (even in this case, the TaskExecutor may be able to cancel the task, if it was not submitted for execution).

function - the function to be executed by this TaskExecutor. This argument cannot be null.

Returns:

the CompletionStage which can be used to execute tasks after the completion of the submitted function and process the result of the submitted function. This method never returns null.

Throws:

NullPointerException - thrown if the CancellationToken or the task is null

See Also:

Cancellation.createCancellationSource(), Cancellation.UNCANCELABLE_TOKEN

execute

default CompletionStage<Void> execute(CancellationToken cancelToken,
                                      CancelableTask task)

Executes the task at some time in the future. When and on what thread, the task is to be executed is completely implementation dependent. Implementations may choose to execute tasks later on a separate thread or synchronously in the calling thread at the discretion of the implementation.

Parameters:

cancelToken - the CancellationToken which is to be checked if the submitted task is to be canceled. If this CancellationToken signals a cancellation request, this TaskExecutor may choose to not even attempt to execute the submitted task. This argument may not be null. When the task cannot be canceled, use the static Cancellation.UNCANCELABLE_TOKEN for this argument (even in this case, the TaskExecutor may be able to cancel the task, if it was not submitted for execution).

task - the task to be executed by this TaskExecutor. This argument cannot be null.

Returns:

the CompletionStage which can be used to execute tasks after the completion of the submitted task. This method never returns null.

Throws:

NullPointerException - thrown if the CancellationToken or the task is null

See Also:

Cancellation.createCancellationSource(), Cancellation.UNCANCELABLE_TOKEN

executeStaged

default CompletionStage<Void> executeStaged(Runnable task)

Executes an non-cancelable task at some time in the future. When and on what thread, the task is to be executed is completely implementation dependent. Implementations may choose to execute tasks later on a separate thread or synchronously in the calling thread at the discretion of the implementation.

Note that although the task itself is not cancelable explicitly, the executor might cancel it by not executing the submitted task. For example, due to a call to the shutdownAndCancel method of TaskExecutorService.

The default implementation delegates the call to execute(CancellationToken, CancelableTask).

Parameters:

task - the task to be executed by this TaskExecutor. This argument cannot be null.

Returns:

the CompletionStage which can be used to execute tasks after the completion of the submitted task. This method never returns null.

Throws:

NullPointerException - thrown if the task is null

See Also:

Cancellation.createCancellationSource(), Cancellation.UNCANCELABLE_TOKEN

execute

default void execute(Runnable command)

Note that although the task itself is not cancelable explicitly, the executor might cancel it by not executing the submitted task. For example, due to a call to the shutdownAndCancel method of TaskExecutorService.

The default implementation delegates the call to executeStaged and logs uncaught errors thrown by the submitted task.

Specified by:

execute in interface Executor