org.jtrim2.executor

Class ManualTaskExecutor

java.lang.Object

org.jtrim2.executor.AbstractTaskExecutor

org.jtrim2.executor.ManualTaskExecutor

All Implemented Interfaces:

Executor, TaskExecutor

public final class ManualTaskExecutor
extends AbstractTaskExecutor

Defines a TaskExecutor where client code can determine where and when submitted tasks are executed. This task is generally useful for testing.

You can submit tasks the usual way as defined by the TaskExecutor interface and if you actually want to execute them, you have to call the executeCurrentlySubmitted or the tryExecuteOne methods. This executor has a FIFO queue and the previously mentioned methods will execute them in the order they were submitted, unless you call them concurrently (in this case no ordering guarantee can be made).

Warning: If you fail to execute submitted tasks, then completion handlers will not be notified, so it is the responsibility of the client code to execute them.

Thread safety

The methods of this class are safe to use by multiple threads concurrently.

Synchronization transparency

The methods of this class are not synchronization transparent.

Nested Class Summary

Nested classes/interfaces inherited from class org.jtrim2.executor.AbstractTaskExecutor

AbstractTaskExecutor.SubmittedTask<V>

Constructor Summary

Constructors

Constructor and Description
ManualTaskExecutor(boolean eagerCancel) Creates a new ManualTaskExecutor with an empty task queue.

Method Summary

Modifier and Type	Method and Description
int	executeCurrentlySubmitted() Executes every currently submitted task found in the task queue.
protected void	submitTask(CancellationToken cancelToken, AbstractTaskExecutor.SubmittedTask<?> submittedTask) Implementations must override this method to actually execute submitted tasks.
boolean	tryExecuteOne() Removes a single task from the task queue of this executor and executes it (along with its completion handler) unless the queue is empty.

Methods inherited from class org.jtrim2.executor.AbstractTaskExecutor

executeFunction

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.jtrim2.executor.TaskExecutor

execute, execute, executeStaged

Constructor Detail

ManualTaskExecutor

public ManualTaskExecutor(boolean eagerCancel)

Creates a new ManualTaskExecutor with an empty task queue.

Parameters:

eagerCancel - if this argument is true and a task is canceled, then the task will be eagerly unreferenced (allowing it to be garbage collected) and will not be attempted to be executed. In case this argument is false, submitted tasks will always be executed even if canceled (though they can check their cancellation token and cancel themselves).

Method Detail

tryExecuteOne

public boolean tryExecuteOne()

Removes a single task from the task queue of this executor and executes it (along with its completion handler) unless the queue is empty.

Note: Exceptions thrown by the submitted task will not be rethrown but can be detected via the associated CompletionStage.

Returns:

true if there was a task to be executed in the queue, false if this method did nothing because there was no submitted task

executeCurrentlySubmitted

public int executeCurrentlySubmitted()

Executes every currently submitted task found in the task queue. The tasks are executed in FIFO order. This method will collect tasks from the queue once, if a task is submitted after, it will not be executed. In particular, new tasks submitted by currently executed tasks are guaranteed not to be executed by this method.

 ManualTaskExecutor executor = new ManualTaskExecutor(false);
 executor.execute(Cancellation.UNCANCELABLE_TOKEN, (outerCancelToken) -> {
   System.out.println("OUTER-TASK");
   executor.execute(Cancellation.UNCANCELABLE_TOKEN, (innerCancelToken) -> {
     System.out.println("INNER-TASK");
   });
 });
 executor.executeCurrentlySubmitted();
 

The above code will only print "OUTER-TASK" and the executeCurrentlySubmitted method will return 1.

Returns:

the number of tasks executed by this method. This includes canceled tasks as well of which only the completion handler is executed.

submitTask

protected void submitTask(CancellationToken cancelToken,
                          AbstractTaskExecutor.SubmittedTask<?> submittedTask)

Implementations must override this method to actually execute submitted tasks.

Assuming no cancellation requests, implementations must call submittedTask.execute.

Cancellation requests can be detected using the provided CancellationToken and if an implementation chooses not to even try to execute task, it must only call submittedTask.cancel.

Implementations must always complete the passed task in some way. Either by calling its execute or its completeExceptionally (or cancel) method.

Implementation note: Submits the specified task for execution. The submitted task can be executed by subsequent calls to executeCurrentlySubmitted or tryExecuteOne methods.

This executor implementation ensures that the same CancellationToken is passed to the task as passed in the argument of the execute method.

Specified by:

submitTask in class AbstractTaskExecutor

Parameters:

cancelToken - the CancellationToken which can be checked by implementations if the currently submitted task has been canceled. Also this is the CancellationToken implementations should pass to task. This argument cannot be null.

submittedTask - the task to be executed. Implementations must execute this task at most once by calling its execute method. If the execute method is not called, an exceptional return state must be set via the completeExceptionally method. This argument cannot be null.