Task interface and DefaultTask modifications - backward compatible

With this commit task events are published automatically when an asynchronous task (task.run(runnable)))
is started and finished. Additionally, task can be run in a synchronous manner and can trigger task events
with additional methods added to the Task interface.

This commit brings additional methods to the Task interface (empty default implementations provided):
* start and finish method: a job can notify when it is starting and ending in a synchronous manner
* setCancelCallback(runnable) method: Can be used to add a callback when a task is canceled

The DefaultTask implementation is modified:
* TaskEvent are published when start() and finish() are called (synchronous task)
* TaskEvent are published just before the runnable is started and after it is  finished
* A try finally statement is used in the async case to ensure a taskevent is sent even in the case of job execution failure
* And event is called when cancel is called, and:
  * Async job : future.cancel(true) is called, + the custom cancel callback is called, if set
  * Sync job : the custom cancel callback is called, if set

* adds a test to check whether many parallel tasks send an event when they are starting and when they are done
* documentation

Author: NicoKiaru

src/main/java/org/scijava/task/DefaultTask.java

@@ -36,11 +36,32 @@
 import org.scijava.thread.ThreadService;
 
 /**
- * Default implementation of {@link Task}. It launches code via the linked
- * {@link ThreadService}, and reports status updates via the linked
- * {@link EventService}.
+ * Default implementation of {@link Task}. Throughout the task (or job),
+ * {@link Task#setProgressValue(long)} can be called to inform
+ * how the job is progressing.
  *
- * @author Curtis Rueden
+ * Asynchronous case:
+ * - A job (runnable) is sent for execution to the linked {@link ThreadService}.
+ * It reports status updates via the linked {@link EventService}.
+ * A {@link org.scijava.task.event.TaskEvent} is sent before the job
+ * is started and when finished.
+ * In the asynchronous case, upon task cancellation ({@link Task#cancel(String)} call),
+ * the runnable associated to the ThreadService is attempted to be stopped
+ * by calling {@link Future#cancel(boolean)}.
+ * This default behaviour can be supplemented by an additional
+ * custom callback which can be set in {@link Task#setCancelCallBack(Runnable)}.
+ *
+ * Synchronous case:
+ * - A job that reports its status in between calls of {@link Task#start()},
+ * and {@link Task#finish()}. It also reports its status via
+ * the linked {@link EventService}.
+ * Start and finish calls allow publishing proper {@link org.scijava.task.event.TaskEvent}
+ * to subscribers (with the EventService).
+ * Upon cancellation of a synchronous task, it is the responsibility
+ * of the synchronous task to handle its own cancellation through
+ * a custom callback which can be set via {@link Task#setCancelCallBack(Runnable)}.
+ *
+ * @author Curtis Rueden, Nicolas Chiaruttini
  */
 public class DefaultTask implements Task {
 
@@ -51,13 +72,16 @@ public class DefaultTask implements Task {
 
 	private boolean canceled;
 	private String cancelReason;
+	volatile boolean isDone = false;
 
 	private String status;
 	private long step;
 	private long max;
 
 	private String name;
 
+	private Runnable cancelCallBack;
+
 	/**
 	 * Creates a new task.
 	 * 
@@ -76,20 +100,35 @@ public DefaultTask(final ThreadService threadService,
 
 	// -- Task methods --
 
+	// - Asynchronous
 	@Override
 	public void run(final Runnable r) {
 		if (r == null) throw new NullPointerException();
 		future(r);
 	}
 
+	// - Asynchronous
 	@Override
 	public void waitFor() throws InterruptedException, ExecutionException {
 		future().get();
 	}
 
+	// - Synchronous
+	@Override
+	public void start() {
+		fireTaskEvent();
+	}
+
+	// - Synchronous
+	@Override
+	public void finish() {
+		isDone=true;
+		fireTaskEvent();
+	}
+
 	@Override
 	public boolean isDone() {
-		return future != null && future.isDone();
+		return (isDone) || (future != null && future.isDone());
 	}
 
 	@Override
@@ -136,6 +175,16 @@ public boolean isCanceled() {
 	public void cancel(final String reason) {
 		canceled = true;
 		cancelReason = reason;
+		if (cancelCallBack!=null) cancelCallBack.run();
+		if (future!=null) {
+			isDone = future.cancel(true);
+		}
+		fireTaskEvent();
+	}
+
+	@Override
+	public void setCancelCallBack(Runnable r) {
+		this.cancelCallBack = r;
 	}
 
 	@Override
@@ -169,7 +218,15 @@ private Future<?> future(final Runnable r) {
 	private synchronized void initFuture(final Runnable r) {
 		if (future != null) return;
 		if (r == null) throw new IllegalArgumentException("Must call run first");
-		future = threadService.run(r);
+		future = threadService.run(() -> {
+			try {
+				fireTaskEvent(); // Triggers an event just before the task is executed
+				r.run();
+			} finally {
+				isDone = true;
+				fireTaskEvent(); // Triggers an event just after the task has successfully completed or failed
+			}
+		});
 	}
 
 	private void fireTaskEvent() {

src/main/java/org/scijava/task/Task.java

@@ -37,26 +37,56 @@
 /**
  * A self-aware job which reports its status and progress as it runs.
  *
- * @author Curtis Rueden
+ * There are two ways to use a Task object:
+ * - A job can be run asynchronously by using {@link Task#run(Runnable)}, and
+ * can report its progression from within the Runnable.
+ *
+ * - A {@link Task} object can simply be used to report in a synchronous manner
+ * the progression of a piece of code. In the case of synchronous reporting,
+ * the job is considered started when {@link Task#start()} is called and
+ * finished when {@link Task#finish()} is called. A finished job can be finished
+ * either because it is done or because it has been cancelled.
+ *
+ * A cancel callback can be set with {@link Task#setCancelCallBack(Runnable)}.
+ * The runnable argument will be executed in the case of an external event
+ * requesting a cancellation of the task - typically, if a user clicks
+ * a cancel button on the GUI, task.cancel("User cancellation requested") will
+ * be called. As a result, the task implementors should run the callback.
+ * This callback can be used to make the task aware that a cancellation
+ * has been requested, and should proceed to stop its execution.
+ *
+ * See also {@link TaskService}, {@link DefaultTask}
+ *
+ * @author Curtis Rueden, Nicolas Chiaruttini
  */
 public interface Task extends Cancelable, Named {
 
 	/**
-	 * Starts running the task.
+	 * Starts running the task - asynchronous job
 	 *
 	 * @throws IllegalStateException if the task was already started.
 	 */
 	void run(Runnable r);
 
 	/**
-	 * Waits for the task to complete.
+	 * Waits for the task to complete - asynchronous job
 	 *
 	 * @throws IllegalStateException if {@link #run} has not been called yet.
 	 * @throws InterruptedException if the task is interrupted.
 	 * @throws ExecutionException if the task throws an exception while running.
 	 */
 	void waitFor() throws InterruptedException, ExecutionException;
 
+	/**
+	 * reports that the task is started - synchronous job
+	 */
+	default void start() {}
+
+	/**
+	 * reports that the task is finished - synchronous job
+	 */
+	default void finish() {}
+
 	/** Checks whether the task has completed. */
 	boolean isDone();
 
@@ -102,4 +132,12 @@ public interface Task extends Cancelable, Named {
 	 * @see #getProgressMaximum()
 	 */
 	void setProgressMaximum(long max);
+
+	/**
+	 * If the task is cancelled (external call to {@link Task#cancel(String)}),
+	 * the input runnable argument should be executed by task implementors.
+	 *
+	 * @param runnable : should be executed if this task is cancelled through {@link Task#cancel(String)}
+	 */
+	default void setCancelCallBack(Runnable runnable) {}
 }

src/test/java/org/scijava/task/TaskEventTest.java

@@ -0,0 +1,106 @@
+package org.scijava.task;
+
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+import org.scijava.Context;
+import org.scijava.event.EventHandler;
+import org.scijava.task.event.TaskEvent;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import static org.junit.Assert.assertEquals;
+
+/**
+ * Tests whether many tasks run in parallel consistently trigger an Event
+ * when each task is started and when each task is ended.
+ *
+ * The test fails inconsistently, sometimes with a few tasks remaining, sometimes with almost all tasks remaining.
+ */
+
+public class TaskEventTest {
+
+    private TaskService taskService;
+    private TaskEventListener eventListener;
+
+    static int nTasks = 500; // Putting higher value can lead to issues because too many threads cannot be launched in parallel
+
+    @Before
+    public void setUp() {
+        final Context ctx = new Context(TaskService.class);
+        taskService = ctx.service(TaskService.class);
+        eventListener = new TaskEventListener();
+        ctx.inject(eventListener);
+    }
+
+    @After
+    public void tearDown() {
+        taskService.context().dispose();
+    }
+
+    @Test
+    public void testManyTasks() throws InterruptedException {
+        for (int i=0;i<nTasks;i++) {
+            createTask(taskService, "Task_"+i, 100, 10, 100);
+        }
+        Thread.sleep(5000);
+        assertEquals(0, eventListener.getLeftOvers().size());
+    }
+
+    public static void createTask(
+            TaskService taskService,
+            String taskName,
+            int msBeforeStart,
+            int msUpdate,
+            int msTaskDuration) {
+        Task task = taskService.createTask(taskName);
+
+        new Thread(
+                () -> {
+                    try {
+                        System.out.println("Waiting to start task "+taskName);
+                        Thread.sleep(msBeforeStart);
+
+                        // Task started
+                        task.setProgressMaximum(100);
+
+                        task.run(() -> {
+                            int totalMs = 0;
+                            while(totalMs<msTaskDuration) {
+                                try {
+                                    Thread.sleep(msUpdate);
+                                } catch (InterruptedException e) {
+                                    e.printStackTrace();
+                                }
+                                totalMs+=msUpdate;
+                                task.setProgressValue((int)(((double)totalMs/msTaskDuration)*100.0));
+                            }
+                            // Task ended
+                        });
+
+                    } catch (InterruptedException e) {
+                        e.printStackTrace();
+                    }
+                }).start();
+    }
+
+    public static class TaskEventListener {
+
+        Set<Task> tasks = new HashSet<>();
+
+        @EventHandler
+        private synchronized void onEvent(final TaskEvent evt) {
+            Task task = evt.getTask();
+            if (task.isDone()) {
+                tasks.remove(task);
+            } else {
+                tasks.add(task);
+            }
+        }
+
+        public synchronized Set<Task> getLeftOvers() {
+            return new HashSet<>(tasks);
+        }
+    }
+}